OpenSearch/x-pack/docs/en/watcher/input/search.asciidoc

[[input-search]]
=== Search Input

Use the `search` input to load the results of an Elasticsearch search request
into the execution context when the watch is triggered. See
<<search-input-attributes, Search Input Attributes>> for all of the
supported attributes.

In the search input's `request` object, you specify:

* The indices you want to search
* The {ref}/search-request-search-type.html[search type]
* The search request body

The search request body supports the full Elasticsearch Query DSL--it's the
same as the body of an Elasticsearch `_search` request.

For example, the following input retrieves all `event`
documents from the `logs` index:

[source,js]
--------------------------------------------------
"input" : {
  "search" : {
    "request" : {
      "indices" : [ "logs" ],
      "body" : {
        "query" : { "match_all" : {}}
      }
    }
  }
}
--------------------------------------------------
// NOTCONSOLE

You can use date math and wildcards when specifying indices. For example,
the following input loads the latest VIXZ quote from today's daily quotes index:

[source,js]
--------------------------------------------------
{
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "<stock-quotes-{now/d}>" ],
        "body" : {
          "size" : 1,
          "sort" : {
            "timestamp" : { "order" : "desc"}
          },
          "query" : {
            "term" : { "symbol" : "vix"}
          }
        }
      }
    }
  }
}
--------------------------------------------------
// NOTCONSOLE

==== Extracting Specific Fields

You can specify which fields in the search response you want to load into the
watch payload with the `extract` attribute. This is useful when a search
generates a large response and you are only interested in particular fields.

For example, the following input loads only the total number of hits into the
watch payload:

[source,js]
--------------------------------------------------
"input": {
    "search": {
      "request": {
        "indices": [ ".watcher-history*" ]
      },
      "extract": [ "hits.total.value" ]
    }
  },
--------------------------------------------------
// NOTCONSOLE

==== Using Templates

The `search` input supports {ref}/search-template.html[search templates]. For
example, the following snippet references the indexed template called
`my_template` and passes a value of 23 to fill in the template's `value`
parameter:

[source,js]
--------------------------------------------------
{
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "logs" ],
        "template" : {
          "id" : "my_template",
          "params" : {
            "value" : 23
          }
        }
      }
    }
  }
  ...
}
--------------------------------------------------
// NOTCONSOLE

==== Applying Conditions

The `search` input is often used in conjunction with the <<condition-script,
`script`>> condition. For example, the following snippet adds a condition to
check if the search returned more than five hits:

[source,js]
--------------------------------------------------
{
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "logs" ],
        "body" : {
          "query" : { "match_all" : {} }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total.value" : { "gt" : 5 }}
  }
  ...
}
--------------------------------------------------
// NOTCONSOLE

==== Accessing the Search Results

Conditions, transforms, and actions can access the search results through the
watch execution context. For example:

* To load all of the search hits into an email body, use `ctx.payload.hits`.
* To reference the total number of hits, use `ctx.payload.hits.total.value`.
* To access a particular hit, use its zero-based array index. For example, to
  get the third hit, use `ctx.payload.hits.hits.2`.
* To get a field value from a particular hit, use
  `ctx.payload.hits.hits.<index>.fields.<fieldname>`. For example, to get the
  message field from the first hit, use `ctx.payload.hits.hits.0.fields.message`.

NOTE: The total number of hits in the search response is returned as an object
in the response. It contains a `value`, the number of hits, and a `relation` that
indicates if the value is accurate (`"eq"`) or a lower bound of the total hits
that match the query (`"gte"`). You can set `track_total_hits` to true in
the search request to tell Elasticsearch to always track the number of hits
accurately.

[[search-input-attributes]]
==== Search Input Attributes

[cols=",^,,", options="header"]
|======
| Name                                          |Required   | Default             | Description

| `request.search_type`                         | no        | `query_then_fetch`  | The {ref}/search-request-search-type.html#search-request-search-type[type]
                                                                                    of search request to perform. Valid values are: `dfs_query_and_fetch`,
                                                                                    `dfs_query_then_fetch`, `query_and_fetch`, and `query_then_fetch`. The
                                                                                    Elasticsearch default is `query_then_fetch`.

| `request.indices`                             | no        | -                   | The indices to search. If omitted, all indices are searched, which is the
                                                                                    default behaviour in Elasticsearch.

| `request.body`                                | no        | -                   | The body of the request. The {ref}/search-request-body.html[request body]
                                                                                    follows the same structure you normally send in the body of a REST `_search`
                                                                                    request. The body can be static text or include `mustache` <<templates, templates>>.

| `request.template`                            | no        | -                   | The body of the search template. See <<templates, configure templates>>
                                                                                    for more information.

| `request.indices_options.expand_wildcards`    | no        | `open`              | How to expand wildcards. Valid values are: `all`, `open`, `closed`, and `none`
                                                                                    See {ref}/multi-index.html#multi-index[`expand_wildcards`] for more information.

| `request.indices_options.ignore_unavailable`  | no        | `true`              | Whether the search should ignore unavailable indices. See
                                                                                    {ref}/multi-index.html#multi-index[`ignore_unavailable`] for more information.

| `request.indices_options.allow_no_indices`    | no        | `true`              | Whether to allow a search where a wildcard indices expression results in no
                                                                                    concrete indices. See {ref}/multi-index.html#multi-index[allow_no_indices]
                                                                                    for more information.

| `extract`                                     | no        | -                   | A array of JSON keys to extract from the search response and load as the payload.
                                                                                    When a search generates a large response, you can use `extract` to select the
                                                                                    relevant fields instead of loading the entire response.

| `timeout`                                     | no        | 30s                 | The timeout for waiting for the search api call to return. If no response is
                                                                                    returned within this time, the search input times out and fails. This setting
                                                                                    overrides the default search operations timeouts.
|======

You can reference the following variables in the execution context when
specifying the request `body`:

[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.
|======