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

[[transform-search]]
=== Search Transform

A <<transform, Transform>> that executes a search on the cluster and replaces
the current payload in the watch execution context with the returned search
response. The following snippet shows how a simple search transform can be
defined on the watch level:

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

Like every other search based construct, one can make use of the full search
API supported by Elasticsearch. For example, the following search transform
execute a search over all events indices, matching events with `error` priority:

[source,js]
--------------------------------------------------
{
  "transform" : {
    "search" : {
      "request" : {
        "indices" : [ "events-*" ],
        "body" : {
          "size" : 0,
          "query" : {
            "match" : { "priority" : "error"}
          }
        }
      }
    }
  }
}
--------------------------------------------------
// NOTCONSOLE

The following table lists all available settings for the search transform:

[[transform-search-settings]]
.Search Transform Settings
[cols=",^,,", options="header"]
|======
| Name                                          |Required   | Default           | Description

| `request.search_type`                         | no        | query_then_fetch  | The search {ref}/search-request-body.html#request-body-search-search-type[type].

| `request.indices`                             | no        | all indices       | One or more indices to search on.

| `request.body`                                | no        | `match_all` query | 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.indices_options.expand_wildcards`    | no        | `open`            | Determines how to expand indices wildcards. Can be one
                                                                                  of `open`, `closed`, `none` or `all`
                                                                                  (see {ref}/multi-index.html[multi-index support])

| `request.indices_options.ignore_unavailable`  | no        | `true`            | A boolean value that determines whether the search
                                                                                  should leniently ignore unavailable indices
                                                                                  (see {ref}/multi-index.html[multi-index support])

| `request.indices_options.allow_no_indices`    | no        | `true`            | A boolean value that determines whether the search
                                                                                  should leniently return no results when no indices
                                                                                  are resolved (see {ref}/multi-index.html[multi-index support])

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

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

[[transform-search-template]]
==== Template Support

The search transform support mustache <<templates, templates>>. This can either
be as part of the body definition, or alternatively, point to an existing
template (either defined in a file or {ref}/search-template.html#pre-registered-templates[registered]
as a script in Elasticsearch).

For example, the following snippet shows a search that refers to the scheduled
time of the watch:

[source,js]
--------------------------------------------------
{
  "transform" : {
    "search" : {
      "request" : {
        "indices" : [ "logstash-*" ],
        "body" : {
          "size" : 0,
          "query" : {
            "bool" : {
              "must" : {
                "match" : { "priority" : "error"}
              },
              "filter" : [
                {
                  "range" : {
                    "@timestamp" : {
                      "from" : "{{ctx.trigger.scheduled_time}}||-30s",
                      "to" : "{{ctx.trigger.triggered_time}}"
                    }
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}
--------------------------------------------------
// NOTCONSOLE

The model of the template is a union between the provided `template.params`
settings and the <<watch-execution-context, standard watch execution context model>>.

The following is an example of using templates that refer to provided parameters:

[source,js]
--------------------------------------------------
{
  "transform" : {
    "search" : {
      "request" : {
        "indices" : [ "logstash-*" ],
        "template" : {
          "source" : {
            "size" : 0,
            "query" : {
              "bool" : {
                "must" : {
                  "match" : { "priority" : "{{priority}}"}
                },
                "filter" : [
                  {
                    "range" : {
                      "@timestamp" : {
                        "from" : "{{ctx.trigger.scheduled_time}}||-30s",
                        "to" : "{{ctx.trigger.triggered_time}}"
                      }
                    }
                  }
                ]
              }
            },
            "params" : {
              "priority" : "error"
            }
          }
        }
      }
    }
  }
}
--------------------------------------------------
// NOTCONSOLE