Available:neighbor() v1.174.0

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.

For more information about sequence functions and combined usage, see Sequence Query Functions.

ParameterTypeRequiredDefault ValueDescription
directionenumoptional[a] preceding Specifies whether to look at preceding or succeeding events.
   Values
   precedingLook at preceding events
   succeedingLook at succeeding events
distanceintegeroptional[a] 1 The number of events to look ahead or behind.
  Maximum1000010,000 events
include[b]array of stringsrequired   The fields to include from the neighboring event.
prefixstringoptional[a]   A prefix to add to the included field names to distinguish them from the current event's fields.

[a] Optional parameters use their default value unless explicitly set.

[b] The parameter name include can be omitted.

Hide omitted argument names for this function

Show omitted argument names for this function

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.

neighbor() Examples

Click + next to an example below to get the full details.

Access Fields From Single Neighboring Event in a Sequence - Example 1

Access fields from a single neighboring (preceeding) event in a sequence using the neighbor() function

Query
logscale
head()
| neighbor(key, prefix=prev)
Introduction

In this example, the neighbor() function is used to look at the preceeding event; the one just before 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

  1. Starting with the source repository events.

  2. logscale
    head()

    Selects the oldest events ordered by time.

  3. logscale
    | neighbor(key, prefix=prev)

    For each event, looks at the event immediately before it, and returns the value of the field key within the current event as a field named prev.key.

    It is also possible to look at an event further away, if defining a distance: neighbor(key, prefix=prev, distance=2)

  4. Event Result set.

Summary and Results

In this example, the value of a field from a preceding event is added to each event.

Sample output from the incoming example data:

keyprev.key
a<no value>
aa
ba
cb

The query is useful for comparing events or detecting patterns in sequential data.

Access Fields From Single Neighboring Event in a Sequence - Example 2

Access fields from a single neighboring (succeeding) event in a sequence using the neighbor() function

Query
logscale
head()
| neighbor(key, prefix=succ, direction=succeeding)
Introduction

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

  1. Starting with the source repository events.

  2. logscale
    head()

    Selects the oldest events ordered by time.

  3. 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.

  4. 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:

keysucc.key
aa
ab
bc
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

  1. Starting with the source repository events.

  2. logscale
    head()

    Selects the oldest events ordered by time.

  3. 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.

  4. 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:

keyprev.key
a<no value>
a<no value>
ba
ca

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()

Query
logscale
head()
| neighbor(key, prefix=prev)
| partition(accumulate(count()), condition=test(key != prev.key))
Introduction

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

  1. Starting with the source repository events.

  2. logscale
    head()

    Selects the oldest events ordered by time.

  3. logscale
    | neighbor(key, prefix=prev)

    Accesses the value in the field key from the previous event.

  4. logscale
    | partition(accumulate(count()), condition=test(key != prev.key))

    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.

  5. 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_countprev.key
a1<no value>
a2a
a3a
b1a
a1b
b1a
b2b

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

Query
logscale
head()
| neighbor(value, prefix=prev)
| change := value - prev.value
| change > 5
Introduction

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

  1. Starting with the source repository events.

  2. logscale
    head()

    Selects the oldest events ordered by time.

  3. 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.

  4. 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.

  5. logscale
    | change > 5

    Filters for values in the field change to show only events where the change is greater than 5.

  6. 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:

valuechangeprev.value
1064

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()

Query
logscale
head()
| neighbor(start, prefix=prev)
| duration := start - prev.start
| accumulate(sum(duration, as=accumulated_duration))
Introduction

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

  1. Starting with the source repository events.

  2. logscale
    head()

    Selects the oldest events ordered by time.

  3. 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.

  4. 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.

  5. logscale
    | accumulate(sum(duration, as=accumulated_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.

  6. 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:

startaccumulated_durationdurationprev.start
11000<no value><no value>
12331331331100
3002190217691233
4324322413223002

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.

Detect Continuously Upwards Going Trend

Detect continuously upwards going trend using the slidingWindow() function combined with neighbor()

Query
logscale
head()
| neighbor(value, prefix=prev)
| change := value - prev.value
| slidingWindow(
    [
         {change >= 0 | count(as=positiveTrend)},
         {change < 0  | count(as=negativeTrend)}
    ],
    events=2
    )
| positiveTrend >= 2
Introduction

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

  1. Starting with the source repository events.

  2. logscale
    head()

    Selects the oldest events ordered by time.

  3. logscale
    | neighbor(value, prefix=prev)

    Creates a new field named prev.value containing the value from the previous event.

  4. 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.

  5. logscale
    | slidingWindow(
    [
         {change >= 0 | count(as=positiveTrend)},
         {change < 0  | count(as=negativeTrend)}
    ],
    events=2
    )

    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.

  6. logscale
    | positiveTrend >= 2

    Filters for windows where there are at least 2 positive (or zero) changes.

  7. 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.

Sample output from the incoming example data:

valuepositiveTrendnegativeTrendchangeprev.value
102046