objectArray:eval()

objectArray:eval() function iterates over the values of a nested array, applies the function on each element, and returns results in a new array field. Currently, the function supports only flat arrays as the output.

For best performance, we recommend using objectArray:eval() only for nested arrays (e.g., JSON structures). For flat arrays, the array:eval() function is a recommended equivalent.

The function's behavior is exemplified by this query:

logscale
objectArray:eval("foo[]", var=x, function=function, asArray="out[]")

which iterates over the values of the array foo[] from start to end — or to the first "gap" (missing index) in the array.

The following form of the function using the var argument:

logscale
objectArray:eval("my_array[]", var=x, function={_mapped := concat([x.a, x.b])}, asArray="_mapped[]")

is equivalent to this form (without var):

logscale
objectArray:eval("my_array[]", function={_mapped := concat([my_array[].a, my_array[].b])}, asArray="_mapped[]")

When using this function:

  • The variable defined by the var argument is validated to ensure it does not contain object/array access patterns, i.e. [..] or ..

  • The variable becomes available as a "pseudo-field" (meaning that it's not like a proper field in the event) in the function argument (see objectArray:eval() Examples).

  • The "pseudo-field" can access structured data on the array entries using an array access pattern consisting of [number] for array indexing and . for sub-selections of object fields. These can be repeated/combined arbitrarily; for example, x.foo[0].bar.baz is a valid pattern.

  • The mapping between input and output array entries is done by the function argument: for each input array entry, function maps an output array entry. The output/result value of function is the value of the same field (without []) given by the asArray argument.

objectArray:eval() Examples

Given an array with the following values:

JSON
arr[0]: fisk
arr[0].a: a0
arr[0].b: b0
arr[1].a: a1
arr[1].b: b1
arr[1].c: c1
arr[2].a: a2
arr[4].b: b2
other: abc

The following query:

logscale
objectArray:eval("arr[]", var=x, function={_mapped := concat([x.a, x.b])}, asArray="_mapped[]")

concatenates the values a and b from each array element. For example, this array element: 

arr[0].a: a0
arr[0].b: b0

is translated to: 

_mapped[0]: a0b0

across the whole input array: 

_mapped[0]: a0b0
_mapped[1]: a1b1
_mapped[2]: a2
_mapped[3]: b2

arr[0]: fisk

arr[0].a: a0
arr[0].b: b0

arr[1].a: a1
arr[1].b: b1

arr[1].c: c1

arr[2].a: a2

arr[4].b: b2

other: abc

A new field _mapped has been added to the event with the concatenated value for the source array arr.

When used with nested arrays, multiple values can be accessed and processed. For example, this input:

JSON
foo[0].key.value": y
"foo[0].key.others[0]": 1
"foo[0].key.others[1]": 2
foo[1].nothing": 355

can be concatenated to a single string using this query:

logscale
objectArray:eval("foo[]", var=x, function={_mapped := concat([x.key.value, "x.key.others[0]", "x.key.others[1]"])}, asArray="_mapped[]")

thus producing the following output: 

_mapped[0]: y12
"foo[0].key.value": y
"foo[0].key.others[0]": 1
"foo[0].key.others[1]": 2