OpenSearch/watcher/docs/reference/input/search.asciidoc

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

An <<input, input>> that enables you to search the Elasticsearch cluster that Watcher is running on and load the 
response into a watch's execution context as the initial payload. See <<search-input-attributes>> for the supported attributes. 

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`. 
* 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`.

[[search-input-attributes]]
.Search Input Attributes
[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`, `query_then_fetch`, and `scan`. 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.types`                               | no        | -           | The document types to search for. If omitted, all document types are 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 internal search operations <<default-internal-ops-timeouts, 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.
|======

===== Submitting Searches

You can use the search input to submit any valid search request to your Elasticsearch cluster.
For example, the following snippet returns all `event` documents in the `logs` index.

[source,json]
--------------------------------------------------
"input" : {
  "search" : {
    "request" : {
      "indices" : [ "logs" ],
      "types" : [ "event" ],
      "body" : {
        "query" : { "match_all" : {}}
      }
    }
  }
}
--------------------------------------------------

===== 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,json]
--------------------------------------------------
"input": {
    "search": {
      "request": {
        "indices": [".watch_history*"]
      },
      "extract": ["hits.total"]
    }
  },
--------------------------------------------------

===== 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,json]
--------------------------------------------------
{
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "logs" ],
        "template" : {
          "id" : "my_template",
          "params" : {
            "value" : 23
          }
        }
      }
    }
  }
  ...
}
--------------------------------------------------

===== 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,json]
--------------------------------------------------
{
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "logs" ],
        "body" : {
          "query" : { "match_all" : {} }
        }
      }
    }
  },
  "condition" : {
    "script" : "return ctx.payload.hits.total > 5"
  }
  ...
}
--------------------------------------------------