Skip to content
This is an archived version of the documentation downloaded from LogScale Documentation Archives. Up to date documentation, and documentation for later versions, is available on LogScale Documentation

## `array:contains()`

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.

When the `array:contains()` function is not flexible enough, is is recommended to use `objectArray:exists()` for nested arrays or `array:exists()` for flat arrays.

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 parameter name `array` can be omitted.

Hide omitted argument names for this function

Show omitted argument names for this function

> Omitted Argument Names

> The argument name for `array` can be omitted; the following forms of this function are equivalent:

> logscale Syntax

>     array:contains("value",value="value")

> and:

> logscale Syntax

>     array:contains(array="value",value="value")

> These examples show basic structure only.

Hide negatable operation for this function

Show negatable operation for this function

> Negatable Function Operation

> This function is negatable, implying the inverse of the result. For example:

> logscale Syntax

>     !array:contains()

> Or:

> logscale Syntax

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

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

#### Aggregate Array Content

Search and group array elements by value using the `array:contains()` function with `groupBy()`)

##### Query

logscale

    array:contains("incidents[]", value="Cozy Bear")
    | groupBy(host)

##### Introduction

Given events containing an `incidents` array:

Event 1

@timestamp | host | incidents[0] | incidents[1]
--- | --- | --- | ---
2025-11-05T10:15:30.000Z | v1 | Evil Bear | Cozy Bear

Event 2

@timestamp | host | incidents[0] | incidents[1] | incidents[2]
--- | --- | --- | --- | ---
2025-11-05T10:15:31.000Z | v15 | Fancy Fly | Tiny Cat | 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

1. Starting with the source repository events.

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

3. logscale

       | groupBy(host)

   Groups the result events extracted from the array by the host.

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

logscale

    array:contains("incidents[]", value="Cozy Bear")

##### Introduction

In this example, the `array:contains()` function is used to check if a given value exists in a given array.

Example incoming data might look like this:

@timestamp | host | incidents[0] | incidents[1] | incidents[2]
--- | --- | --- | --- | ---
2025-11-05T10:15:30.000Z | server1 | Evil Bear | Cozy Bear | <no value>
2025-11-05T10:15:31.000Z | server2 | Fancy Bear | Evil Bear | Tiny Cat
2025-11-05T10:15:32.000Z | server3 | Cozy Bear | Fancy Bear | Evil Bear
2025-11-05T10:15:33.000Z | server4 | Tiny Cat | Fancy Bear | <no value>
2025-11-05T10:15:34.000Z | server5 | CozyBear | Cozy Bears | Evil Bear

##### Step-by-Step

1. Starting with the source repository events.

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

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

Sample output from the incoming example data:

host | incidents[0] | incidents[1] | incidents[2]
--- | --- | --- | ---
server1 | Evil Bear | Cozy Bear | <no value>
server3 | Cozy Bear | Fancy Bear | Evil Bear

Note that only events containing the exact string `Cozy Bear` are included in the results. Events with similar values like `CozyBear` or `Cozy Bears` are excluded as they do not match exactly.

#### Enter search term