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

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

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

While limited in its functionality, the advantage of this condition over the <<condition-script, Script Condition>>
is that you do not have to enable dynamic scripting to use compare conditions.

===== Using a Compare Condition

The following snippet configures a `compare` condition that returns `true` if the number of
the total hits in the search result (typically loaded by the <<input-search, Search Input>>) is
higher or equals 5:

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

  "condition" : {
    "compare" : { 
      "ctx.payload.hits.total" : { <1>
        "gte" : 5 <2>
      }
  }
  ...
}
--------------------------------------------------
<1> The field name is the path to the execution context model
<2> The field name (here `gte`) is the comparison operator, and the value is the value to compare to.


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

[options="header"]
|======
| Name                                  | Description
| `ctx.watch_id`                        | The id of the watch that is currently executing.
| `ctx.execution_time`                  | The time execution of this watch started.
| `ctx.trigger.triggered_time`          | The time this watch was triggered.
| `ctx.trigger.scheduled_time`          | The time this watch was supposed to be triggered.
| `ctx.metadata.*`                      | Any metadata associated with the watch.
| `ctx.payload.*`                       | The payload data loaded by the watch's input.
|======

TIP:  You can reference entries in arrays using their zero-based array indices. For example, to access the third
      element of the `ctx.payload.hits.hits` array, use `ctx.payload.hits.hits.2`.

[[condition-compare-operators]]
The comparison operator can be any one of the following:

[options="header"]
|======
| Name             | Description
| `eq`             | Returns `true` when the resolved value equals the given one (applies to numeric, string, list, object and values)
| `not_eq`         | Returns `true` when the resolved value does not equal the given one  (applies to numeric, string, list, object and null values)
| `gt`             | Returns `true` when the resolved value is greater than the given one (applies to numeric and string values)
| `gte`            | Returns `true` when the resolved value is greater/equal than/to the given one (applies to numeric and string values)
| `lt`             | Returns `true` when the resolved value is less than the given one (applies to numeric and string values)
| `lte`            | Returns `true` when the resolved value is less/equal than/to the given one (applies to numeric and string values)
|======

When dealing with dates/times, the specified value can hold date math expression in the form of `<{expression}>`. For example, one
can compare the watch execution time as follows:
[source,json]
--------------------------------------------------
{
  ...

  "condition" : {
    "compare" : {
      "ctx.execution_time" : {
        "gte" : "<{now-5m}>"
      }
  }
  ...
}
--------------------------------------------------

It is also possible to compare one value in the context model to another value in the same model. This can be done by
specifying the compared value as a path in the form of `{{path}}`. The following snippet shows a condition that compares
two values in the payload

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

  "condition" : {
    "compare" : {
      "ctx.payload.aggregations.status.buckets.error.doc_count" : {
        "not_eq" : "{{ctx.payload.aggregations.handled.buckets.true.doc_count}}"
      }
  }
  ...
}
--------------------------------------------------