Checks whether the given value matches any of the values of the array and excludes the event from the search result if it does not match any value.
Parameter | Type | Required | Default Value | Description |
---|---|---|---|---|
array [a] | string | required | A string in the format of a valid array followed by [] . A valid array can either be an identifier, a valid array followed by . and an identifier, or a valid array followed by an array index surrounded by square brackets. For example, for events with fields incidents[0], incidents[1], ... this would be incidents[] . | |
value | string | required | The exact value of the array to search for. | |
[a] The argument name |
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:logscalearray:contains("value[]",value="value")
and:
logscalearray:contains(array="value[]",value="value")
These examples show basic structure only.
Hide negatable operation for this function
Negatable Function OperationThis function is negatable, implying the inverse of the result. For example:
logscale!array:contains()
Or:
logscalenot array:contains()
For more information, see Negating the Result of Filter Functions.
A specific syntax applies for this query function, see Array Syntax for details.
array:contains()
Examples
Aggregate Array Content
Query
array:contains("incidents[]", value="Cozy Bear")
| groupBy(host)
Introduction
Given events containing an incidents
array:
Event 1
|--------------|-------------|
| host | v1 |
| incidents[0] | Evil Bear |
| incidents[1] | Cozy Bear |
|--------------|-------------|
Event 2
|--------------|-------------|
| host | v15 |
| incidents[0] | Fancy Fly |
| incidents[1] | Tiny Cat |
| incidents[2] | Cozy Bears |
|--------------|-------------|
Finds all the events where the field
incidents contains the
exact value Cozy Bear
and group them by which hosts
were affected, giving output event:
Step-by-Step
Starting with the source repository events.
- logscale
array:contains("incidents[]", value="Cozy Bear")
Extracts elements from the array incidents from the field host that match the text
Cozy Bear
. The items will be output into the host field. - logscale
| groupBy(host)
Groups the result events extracted from the array by the host.
Event Result set.
Summary and Results
The result is an aggregated count of the array elements matching
Cozy Bear
.
field | value |
---|---|
host | v1 |
_count | 1 |
Check for Values in Array
Use array query filter array:contains()
to check for a value in a flat array
Query
array:contains("incidents[]", value="Cozy Bear")
Introduction
Array query filters are data structure elements that make it
possible to define a list of values in a single field. The
different array query functions can be used to extract, filter and
search data and then index it into an array. In this example, the
array:contains()
function is used to check if
a given value exists in a given array.
Step-by-Step
Starting with the source repository events.
- logscale
array:contains("incidents[]", value="Cozy Bear")
Checks if the value of
Cozy Bear
exists within the incidents array field. If the array contains the value, the whole event is included in the search result. Event Result set.
Summary and Results
The query is used as a filter to check if a given value exists in a given array within the event set. If the given value does not match any of the values of the array, then the event is excluded from the search result. Arrays are used when ingesting security event logs where fields may have more than one value. If the array contains other values along with the specified value, these are also included in the search results.