Available:array:exists()
v1.175.0
The array:exists() function is available
from version 1.175.0.
The function filters events based on array contents. It checks if an array contains at least one element that meets a specified condition.
The array:exists() function is useful when
array:contains() is not flexible enough,
for example, when users want to compare the elements of the
array to the values of other fields or when they want to use
query functions in the condition.
Note
It is recommended to use the
array:contains() function to check for
simple values. See array:contains().
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
array[a] | string | required | Name of the array in which to search for matching elements. Must follow valid Array Syntax for array of scalars. For example, for events with fields incidents[0], incidents[1], ... this would be incidents[]. | |
condition | non-aggregate pipeline | required | A non-aggregate pipeline. If an event passes through the pipeline, the event is included, otherwise it is excluded. | |
var | string | optional[b] | input array name. | Name of the variable to be used in the condition argument. |
[b] Optional parameters use their default value unless explicitly set. | ||||
Hide omitted argument names for this function
Omitted Argument NamesThe argument name for
arraycan be omitted; the following forms of this function are equivalent:logscale Syntaxarray:exists("value",condition=)and:
logscale Syntaxarray:exists(array="value",condition=)These examples show basic structure only.
The array:exists() function can use other
filter functions, such as in() or
if(), or pipelines.
Note that for structured arrays, the
objectArray:exists() function must be used
instead of the array:exists() function. For
more information, see objectArray:exists().
For a complete list of functions for flat arrays, see
Array Query Functions.
array:exists()Examples
Click next to an example below to get the full details.
Check For Existence of Element Contained in Given List of Values
Check for the existence of an element contained in a given list of
simple values in a flat array using
array:exists() function with in()
Query
kvparse()
| array:exists(array="a[]", condition=in(a, values=[3, 4]))Introduction
In this example, the array:exists() function is
used with the condition
argument and the filter function in() to check if
given values are in the array.
Example incoming data might look like this:
| a[0] | a[1] |
|---|---|
| 1 | 2 |
| 1 | 3 |
| 1 | 4 |
Step-by-Step
Starting with the source repository events.
- logscale
kvparse()Parses the string into key value pairs.
- logscale
| array:exists(array="a[]", condition=in(a, values=[3, 4]))Filters for events where the a[] array contains the values
3or4. Event Result set.
Summary and Results
The query is used to check for the existence of simple values in a flat array.
Sample output from the incoming example data:
"a[0]","a[1]"
"1","3"
"1","4"Check For Existence of Element Larger Than Given Number
Check for the existence of an element larger than a given number
in a flat array using array:exists() function
Query
kvparse()
| array:exists(array="a[]", condition={a>2})Introduction
In this example, the array:exists() function is
used with the condition
argument to check if a given value is in the array.
Note
It is recommended to use the array:contains()
function to check for simple values. See
array:contains().
Example incoming data might look like this:
| a[0] | a[1] |
|---|---|
| 1 | 2 |
| 1 | 3 |
| 1 | 4 |
Step-by-Step
Starting with the source repository events.
- logscale
kvparse()Parses the string into key value pairs.
- logscale
| array:exists(array="a[]", condition={a>2})Filters for events where the a[] array contains a value greater than
2. Event Result set.
Summary and Results
The query is used to check for the existence of simple values in a flat array.
Sample output from the incoming example data:
| a[0] | a[1] |
|---|---|
| 1 | 3 |
| 1 | 4 |
Check For Existence of Element Using Complex Conditions
Check for the existence of elements using complex conditions in
flat array using array:exists() function with
in() and if()
Query
kvParse()
| array:exists(
array="a[]",
condition=if(in(a, values=[2,5]), then=true, else=in(a, values=[3, 6]))Introduction
In this example, the array:exists() function is
used with the condition
argument and if() function along with the
in() function to check if given values are in the
array.
The example demonstrates how to use the kvParse()
function along with the if() function to create a
logical OR-like condition in the expression language. It allows for more
complex filtering logic, when a direct logical OR
operator is not available.
Example incoming data might look like this:
| a[0] | a[1] |
|---|---|
| 1 | 2 |
| 1 | 3 |
| 1 | 4 |
Step-by-Step
Starting with the source repository events.
- logscale
kvParse()Parses the string into key value pairs.
- logscale
| array:exists( array="a[]", condition=if(in(a, values=[2,5]), then=true, else=in(a, values=[3, 6]))Filters for events where the a[] array contains the values
2or5. If not containing these values, it filters for events where the a[] array contains the values3or6. Event Result set.
Summary and Results
The query is used to check for the existence of simple values in nested arrays.
Sample output from the incoming example data:
| a[0] | a[1] |
|---|---|
| 1 | 2 |
| 1 | 3 |
Check For Existence of Elements Using Filtering Pipeline
Check for the existence of element in a flat array using the
array:exists() function with a filtering
pipeline
Query
kvParse()
| array:exists(
array="a[]",
var=x,
condition={ x=3 OR x=4 | test(x>=b) })Introduction
In this example, the array:exists() function is
used with the condition
argument and test() function to check if given
values are in the array.
Example incoming data might look like this:
| a[0] | a[1] | b |
|---|---|---|
| 1 | 2 | 4 |
| 1 | 3 | 4 |
| 1 | 4 | 3 |
Step-by-Step
Starting with the source repository events.
- logscale
kvParse()Parses the string into key value pairs.
- logscale
| array:exists( array="a[]", var=x, condition={ x=3 OR x=4 | test(x>=b) })Filters for events where the a[] array contains the values
3or4and where x is greater than or equal to the value of the field b in the event. Event Result set.
Summary and Results
The query is used to compare array entries to both fixed values and field values. The query outputs the event that passed the filtering condition in the pipeline.
Sample output from the incoming example data:
| a[0] | a[1] | b |
|---|---|---|
| 1 | 4 | 3 |
Check For Existence of Simple Values in Nested Array Using objectArray:exists()
Check for the existence of simple values in nested array using
objectArray:exists() function with
array:exists() as filter function
Query
kvParse()
| objectArray:exists(
array="a[]",
condition=array:exists(array="a.field.b[]", var=x, condition=test(x==2)))Introduction
In this example, the objectArray:exists()
function is used with the
condition argument and
array:exists() function to check if given
values are in the array.
The objectArray:exist() part
handles the structured part of the example, whereas the
array:exists() is used within the condition to loop
through the nested array. In a nested array, the outermost call must be
objectArray:exists(), the inner one could in theory
be either function, but LogScale recommends using
array:exists().
Example incoming data might look like this:
| a[0].field.b[0] | a[0].field.b[1] | a[1].field.b[0] | a[2].field.b[0] |
|---|---|---|---|
| 1 | <no value> | <no value> | <no value> |
| 1 | 2 | <no value> | <no value> |
| <no value> | <no value> | 3 | <no value> |
| 1 | 2 | 3 | 4 |
Step-by-Step
Starting with the source repository events.
- logscale
kvParse()Parses the string into key value pairs.
- logscale
| objectArray:exists( array="a[]", condition=array:exists(array="a.field.b[]", var=x, condition=test(x==2)))Filters for elements in the array a[] that meet the given condition, then checks if there exists a value in the a.field.b[] array that equals
2. Event Result set.
Summary and Results
The query is used to test for the existence of simple values in nested arrays. The query outputs the events that passed the filtering condition.
Sample output from the incoming example data:
| a[0].field.b[0] | a[0].field.b[1] | a[1].field.b[0] | a[2].field.b[0] |
|---|---|---|---|
| 1 | 2 | <no value> | <no value> |
| 1 | 2 | 3 | 4 |
Check for AWS Resources in Vendor Array
Filter events based on specific AWS resource ARNs using the
objectArray:exists() function
Query
objectArray:exists(array="Vendor.resources[]", condition={Vendor.resources.ARN="arn:aws:*"})Introduction
In this example, the objectArray:exists() function
is used to filter events where an AWS resource ARN exists within a
vendor's resource array that matches a specific pattern.
Example incoming data might look like this:
| @timestamp | Vendor.resources |
|---|---|
| 2023-06-15T10:00:00Z, [{"ARN": "arn:aws:s3:::bucket1", "Type": "S3"}, {"ARN": "arn:aws:ec2:instance1", "Type": "EC2"}] | |
| 2023-06-15T10:01:00Z, [{"ARN": "arn:azure:vm1", "Type": "VM"}, {"ARN": "arn:azure:storage1", "Type": "Storage"}] | |
| 2023-06-15T10:02:00Z, [{"ARN": "arn:aws:lambda:function1", "Type": "Lambda"}, {"ARN": "arn:aws:s3:::bucket2", "Type": "S3"}] | |
| 2023-06-15T10:03:00Z, [{"ARN": "arn:gcp:instance1", "Type": "VM"}, {"ARN": "arn:gcp:storage1", "Type": "Storage"}] |
Step-by-Step
Starting with the source repository events.
- logscale
objectArray:exists(array="Vendor.resources[]", condition={Vendor.resources.ARN="arn:aws:*"})Filters events by checking if any element in the Vendor.resources array contains an ARN field that matches the pattern
arn:aws:*. Thearrayparameter specifies the array to search through, and theconditionparameter defines the matching criteria. Event Result set.
Summary and Results
The query is used to identify events that contain AWS resources by
checking the ARN patterns in the resource array. The
objectArray:exists() function filters events based
on array content matching specific conditions.
This query is useful, for example, to monitor AWS-specific resources in a multi-cloud environment, audit AWS resource usage, or filter out non-AWS resources from the analysis.
Sample output from the incoming example data:
| @timestamp | Vendor.resources |
|---|---|
| 2023-06-15T10:00:00Z, [{"ARN": "arn:aws:s3:::bucket1", "Type": "S3"}, {"ARN": "arn:aws:ec2:instance1", "Type": "EC2"}] | |
| 2023-06-15T10:02:00Z, [{"ARN": "arn:aws:lambda:function1", "Type": "Lambda"}, {"ARN": "arn:aws:s3:::bucket2", "Type": "S3"}] |
Note that only events containing AWS ARNs (starting with "arn:aws:") are included in the results, while events with Azure and GCP resources are filtered out.