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

[role="xpack"]
[[transform-search]]
=== Search {watcher-transform}

A <<transform,{watcher-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
{watcher-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
{watcher-transform}:

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

| `request.search_type`                         | no        | query_then_fetch  | The search <<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
                                                                                  <<search-request-body,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 <<multi-index,multi-index support>>)

| `request.indices_options.ignore_unavailable`  | no        | `true`            | A boolean value that determines whether the search
                                                                                  should leniently ignore unavailable indices
                                                                                  (see <<multi-index,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 <<multi-index,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 {watcher-transform} times out and fails. This setting
                                                                                  overrides the default timeouts.
|======

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

The search {watcher-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
<<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