Important
This function is considered experimental and under active development and should not be used in production.
The function must be enabled using the feature flag ArrayFunctions. See Enabling & Disabling Feature Flags.
Evaluates the function
argument on all values in the array under the
array
argument overwriting
the array. If the asArray
argument is supplied, then array:eval()
saves the
result in an array under the given prefix. This overwrites existing arrays
of that name.
The output array is always compacted, meaning that the array indices are
guaranteed to be continuous, for example,
0,1,2,...
.
Parameter | Type | Required | Default Value | Description |
---|---|---|---|---|
array [a] | string | required | The array name in LogScale Array Syntax, for example, for events with fields incidents[0], incidents[1], ... this would be incidents[] , as in array:eval(array="incidents[]", ... . | |
asArray | string | optional[b] | value passed to the array parameter | The output array. |
function | non-aggregate function | required | The function to be applied to each element of the array. Must write a value to a field named the same as the output array. | |
var | string | optional[b] | input array name | Name of the variable to be used in the function argument. |
[b] Optional parameters use their default value unless explicitly set. |
Hide omitted argument names for this function
Omitted Argument NamesThe argument name for
array
can be omitted; the following forms of this function are equivalent:logscale Syntaxarray:eval("value",function="value")
and:
logscale Syntaxarray:eval(array="value",function="value")
These examples show basic structure only.
array:eval()
Examples
Click
next to an example below to get the full details.Evaluate Function Argument on Values in Array
Evaluate the function
argument on all values in a flat array
Query
array:eval(values, as=squared, var="x", function={x := x*x})
Introduction
The array:eval()
function is used for test
purposes. It evaluates the
function
argument on all values in the array under the
array
argument
overwriting the input array. If an
as
argument has
been supplied, array:eval()
will save the
result in an array under the supplied prefix. The purpose of
this query is to square the value of each item in the array.
Example incoming data might look like this:
values [0] = 2
values [1] = 3
values [2] = 4
Step-by-Step
Starting with the source repository events.
- logscale
array:eval(values, as=squared, var="x", function={x := x*x})
Squares the value of each item in the array. If input values
(x)
are 2,3,4 then the output values when squared(x*x)
will be 4,9,16. Event Result set.
Summary and Results
The query is used to square the value of each item in the array. This is a good example of manipulating array values, for example to format the output before display.
Sample output from the incoming example data:
field | value |
---|---|
squared[0] | 4 |
squared[1] | 9 |
squared[2] | 16 |
Perform Formatting on All Values in an Array
Perform formatting on all values in a flat array using the array:eval()
function
Query
array:eval("devices[]", asArray="upperDevices[]", var=d, function={upperDevices :=upper("d")})
Introduction
The array:eval()
function is used to apply a
specific function to each value inside an array. The
array:eval()
function processes every item in
the list (array) one by one, performs some kind of calculation or
operation, and either overwrites the original array or saves the
result in a new array. In this example, the
array:eval()
function is used to convert all
values (for example [Thermostat, Smart Light]
)
in an array devices[] from lowercase to
uppercase and show the results in a new array.
Example incoming data might look like this:
{\"devices\":[\"Thermostat\",\"Smart Plug\"],\"room\":\"Kitchen\"}" |
{\"devices\":[\"Smart Light\",\"Thermostat\",\"Smart Plug\"],\"room\":\"Living Room\"}" |
{\"devices\":[\"Smart Light\",\"Smart Plug\"],\"room\":\"Bedroom\"}" |
{\"devices\":[\"Thermostat\",\"Smart Camera\"],\"room\":\"Hallway\"}" |
{\"devices\":[\"Smart Light\",\"Smart Lock\"],\"room\":\"Front Door\"}" |
Step-by-Step
Starting with the source repository events.
- logscale
array:eval("devices[]", asArray="upperDevices[]", var=d, function={upperDevices :=upper("d")})
Formats all values in the array devices[] to uppercase and returns the results in a new array named upperDevices[]. The values in the original array stay the same:
[Thermostat, Smart Plug, Smart Light]
and the new array contains the returned results:[THERMOSTAT, SMART PLUG, SMART LIGHT]
Event Result set.
Summary and Results
The query is used to turn values in an array into uppercase. The
array:eval()
function can also be used for
squaring a list of numbers in an array.
Sample output from the incoming example data:
devices[] | upperDevices[] |
---|---|
Thermostat | THERMOSTAT |
Smart Plug | SMART PLUG |
Smart Light | SMART LIGHT |
Square Values in an Array
Square values in an array using the array:eval()
function
Query
array:eval("values[]", asArray="squared[]", var=element, function={squared :=element*element})
Introduction
The array:eval()
function is used to apply a
specific function to each value inside an array. The
array:eval()
function processes every item in
the list (array) one by one, performs some kind of calculation or
operation, and either overwrites the original array or saves the
result in a new array. In this example, the
array:eval()
function is used to square a
list of numbers (for example 2
,
3
, and 4
) and show the
results in a new array.
Example incoming data might look like this:
values [0] = 2 |
values [1] = 3 |
values [2] = 4 |
Step-by-Step
Starting with the source repository events.
- logscale
array:eval("values[]", asArray="squared[]", var=element, function={squared :=element*element})
Squares all values in the array values[] and returns the results in a new array named squared[]. The values in the original array stay the same:
[2, 3, 4]
and the new array contains the squared results:[4, 9, 16]
Event Result set.
Summary and Results
The query is used to square a list of numbers in an array. The
array:eval()
function can also be used for
performing formatting on values in an array.
Sample output from the incoming example data:
field | value |
---|---|
squared[0] | 4 |
squared[1] | 9 |
squared[2] | 16 |