The neighbor() function is available from
version 1.174.0.
The neighbor() function allows access to
fields from a single neighboring event in a sequence. It
retrieves fields from either a preceding or succeeding event at
a specified distance from the current event. The
neighbor() function is particularly useful
for comparing events or detecting patterns in sequential data.
Hide omitted argument names for this functionShow omitted argument names for this function
Omitted Argument Names
The argument name for include can be omitted; the following forms of this function are equivalent:
logscale Syntax
neighbor(["value"])
and:
logscale Syntax
neighbor(include=["value"])
These examples show basic structure only.
Note
The neighbor() function must be
used after an aggregator function (for example,
head(),
sort(),
bucket(),
groupBy()
timeChart()) to ensure event ordering, as the
neighbor() function requires a
specific order to calculate cumulative values correctly.
The neighbor can be found a maximum of 10,000 events
away.
In this example, the neighbor() function is used to
look at the succeeding event; the one just after the current event as no
distance is specified.
Note that the neighbor() function must be used
after an aggregator function to ensure event ordering.
Example incoming data might look like this:
key
a
a
b
c
Step-by-Step
Starting with the source repository events.
logscale
head()
Selects the oldest events ordered by time.
logscale
|neighbor(key, prefix=succ,direction=succeeding)
For each event, looks at the event immediately after it, and returns the
results in a field named
succ.key.
Event Result set.
Summary and Results
The query is used to access fields from a single neighboring event in a
sequence, retrieving fields from either a preceding or succeeding event
at a specified distance (number of events) from the current event.
Sample output from the incoming example data:
key
succ.key
a
a
a
b
b
c
c
<no value>
The query is useful for comparing event values or detecting patterns in
sequential data.
Access Fields From Single Neighboring Event in a Sequence - Example 3
Access fields from a single neighboring (further away) event in a sequence using the neighbor() function
Query
logscale
head()|neighbor(key, prefix=prev,distance=2)
Introduction
In this example, the neighbor() function is used to
look at a preceeding event with the specified distance of
2 away from the current event.
Note that the neighbor() function must be used
after an aggregator function to ensure event ordering.
Example incoming data might look like this:
key
a
a
b
c
Step-by-Step
Starting with the source repository events.
logscale
head()
Selects the oldest events ordered by time.
logscale
|neighbor(key, prefix=prev,distance=2)
For each event, looks two events back in the sequence. It retrieves the
key value from that event two positions back, and
adds this value to the current event's data, labeled with
prev.key.
Event Result set.
Summary and Results
The query is used to access fields from each event at a specified
distance (number of events) away in a sequence of events, retrieving
fields from either a preceding or succeeding event at a specified
distance from the current event.
Sample output from the incoming example data:
key
prev.key
a
<no value>
a
<no value>
b
a
c
a
The query is useful for comparing events with others that are not
immediately adjacent in your data sequence.
Count Events Within Partitions Based on Condition
Count events within partitions based on a specific condition using the partition() function combined with neighbor() and accumulate()
Accumulations can be partitioned based on a condition, such as a change
in value. This is achieved by combining the three functions
partition(), neighbor() and
accumulate(). In this example, the combination of
the 3 sequence functions is used to count events within partitions
defined by changes in a key field.
Note that sequence functions must be used after an aggregator function
to ensure event ordering.
Example incoming data might look like this:
key
a
a
a
b
a
b
b
Step-by-Step
Starting with the source repository events.
logscale
head()
Selects the oldest events ordered by time.
logscale
|neighbor(key, prefix=prev)
Accesses the value in the field key from the
previous event.
The partition() function splits the sequence of
events based on the specified condition. A new partition starts when
the current key value is different from the
previous key value. Within each partition, it
counts the number of events, and returns the results in a field named
_count.
Event Result set.
Summary and Results
The query is used to compute an accumulated count of events within
partitions based on a specific condition, in this example change in
value for the field key.
Sample output from the incoming example data:
key
_count
prev.key
a
1
<no value>
a
2
a
a
3
a
b
1
a
a
1
b
b
1
a
b
2
b
The query is useful for analyzing sequences of events, especially when
you want to identify and count consecutive occurrences of a particular
attribute in order to identify and analyze patterns or sequences within
your data.
Detect Changes And Compute Differences Between Events - Example 1
Detect changes and compute differences between events using the neighbor() function
In this example, the neighbor() function is used to
detect changes in values and alert on large increase.
Note that the neighbor() function must be used
after an aggregator function to ensure event ordering.
Example incoming data might look like this:
value
3
5.5
4
10
Step-by-Step
Starting with the source repository events.
logscale
head()
Selects the oldest events ordered by time.
logscale
|neighbor(value, prefix=prev)
Retrieves the value from
preceeding event, and assigns this value to the current event's data in
a new field named prev.value.
logscale
|change:=value - prev.value
Calculates the difference between current and previous values, and
returns the results - the calculated difference - in a field named
change.
logscale
|change>5
Filters for values in the field
change to show only events where
the change is greater than 5.
Event Result set.
Summary and Results
The query is used to detect changes in values and alert on a quantified
increase. The query will identify events where the value has increased
by more than 5 compared to the previous event.
Sample output from the incoming example data:
value
change
prev.value
10
6
4
The query is useful for real-time monitoring and alerting systems where
you need to quickly identify significant changes in sequential data. It
allows for immediate detection of anomalies or important shifts in your
data, enabling prompt responses to potential issues or opportunities.
Detect Changes And Compute Differences Between Events - Example 2
Detect changes and compute differences between events using the neighbor() function combined with accumulate()
In this example, the neighbor() function is used
with accumulate() to calculate a running total of
durations.
Note that the neighbor() function must be used
after an aggregator function to ensure event ordering.
Example incoming data might look like this:
start
1100
1233
3002
4324
Step-by-Step
Starting with the source repository events.
logscale
head()
Selects the oldest events ordered by time.
logscale
|neighbor(start, prefix=prev)
Retrieves the value in the start
field from preceeding event, and assigns this value to the current
event's data in a new field named
prev.start.
logscale
|duration := start - prev.start
Calculates the time difference between current and previous start
values, and returns the results - the calculated difference - in a field
named duration.
Calculates a running total sum of the values in the field
duration and returns the results
in a field named
accumulated_duration. Each event
will show its individual duration and the total accumulated duration up
to that point.
Event Result set.
Summary and Results
The query is used to calculate the time difference between consecutive
events. The format of this query is a useful pattern when analyzing
temporal data, to provide insights into process efficiency, system
performance over time etc. In this example, the
acculated_duration provides a
value that can be used to compare against the
duration field within each
event.
Sample output from the incoming example data:
start
accumulated_duration
duration
prev.start
1100
0
<no value>
<no value>
1233
133
133
1100
3002
1902
1769
1233
4324
3224
1322
3002
For example, in the results, the third event shows a large increase in
duration against the
accumulated_duration and the
start time of the previous event (in
prev.start). If analyzing
execution times of a process, this could indicate a fault or delay
compared to previous executions.
In this example, the slidingWindow() function
combined with neighbor() is used to detect
continuously upwards going trend. It looks for sequences where the value
is consistently increasing or staying the same over at least two
consecutive measurements.
Note that sequence functions must be used after an aggregator function
to ensure event ordering.
Example incoming data might look like this:
value
3
5.5
4
6
10
Step-by-Step
Starting with the source repository events.
logscale
head()
Selects the oldest events ordered by time.
logscale
|neighbor(value, prefix=prev)
Creates a new field named
prev.value containing the
value from the previous event.
logscale
|change:=value - prev.value
Calculates the change between the current value and the previous
value, and assigns the returned results to a field named
change.
Creates a sliding window of 2 events. Within each window, it counts
changes equal to zero or higher (positive or zero changes) and returns
the results in a field named
positiveTrend, and then also
counts the negative changes and returns the results in a field named
negativeTrend.
logscale
|positiveTrend>=2
Filters for windows where there are at least 2 positive (or zero)
changes.
Event Result set.
Summary and Results
The query is used to detect a continuous upwards trend in a series of
values. The query can be used to monitor system metrics for consistent
increases (for example, memory usage, CPU load) and to identify
potential anomalies in time-series data.