OpenSearch/watcher/docs/reference/condition/array-compare.asciidoc

[[condition-array-compare]]
==== Array Compare Condition

A watch <<condition, condition>> that compares an array of values in the <<watch-execution-context, Watch Execution Context Model>>
to a given value. The values in the model are identified by a path within that model.

==== Using an Array Compare Condition

The following snippet configures an `array_compare` condition that returns `true` if there is at least one bucket in the
aggregations buckets that has a `doc_count` higher than or equal to 25:

[source,json]
--------------------------------------------------
{
  ...

  "condition": {
    "array_compare": {
      "ctx.payload.aggregations.top_tweeters.buckets" : { <1>
        "path": "doc_count" <2>,
        "gte": { <3>
          "value": 25, <4>
          "quantifier": "some" <5>
        }
      }
    }
  }
  ...
}
--------------------------------------------------
<1> The field name is the path to the array (array path) in the execution context model
<2> The value of the field `path` (here `doc_count`) is the path to the value for each element of the array that the
comparison operator will be applied to
<3> The field name (here `gte`) is the name of the comparison operator
<4> The value of the field `value` in the comparison operator object is the comparison value
<5> The value of the field `quantifier` (`all` or `some`) specifies whether the comparison must be true for all or for
at least one of the values to evaluate the comparison to true

NOTE: The `path` element is optional and will default to `""` if not specified.

NOTE: The `quantifier` element is optional and will default to `"some"` if not specified.

The array path is a "dot-notation" expression that can reference the following variables in the watch context:

[options="header"]
|======
| Name                                  | Description
| `ctx.metadata.*`                      | Any metadata associated with the watch.
| `ctx.payload.*`                       | The payload data loaded by the watch's input.
|======

This array path must resolve to an array.

The comparison operator can be any one of the operators supported by the
<<condition-compare-operators, Compare Condition>>.

The quantifier operator can be any one of the following:

[options="header"]
|======
| Name             | Description
| `all`             | Returns `true` when the resolved value compares `true` according to the comparison operator for all the elements in the array
| `some`            | Returns `true` when the resolved value compares `true` according to the comparison operator for at least one element in the array
|======

NOTE: If the array is empty, `all` causes the comparison operator to evaluate to `true` and `some` causes the comparison
operator to evaluate to `false`.

NOTE: It is also possible to use date math expressions and values in the context model as in the <<condition-compare, Compare Condition>>.