OpenSearch/watcher/docs/reference/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 results. The following snippet shows how a simple search
transform can be defined on the watch level:

[source,json]
.Simple Search Transform
--------------------------------------------------
{
  ...

  "transform" : {
    "search" : {
      "request" : {
        "body" : { "query" : { "match_all" : {} }}
      }
    }
  }
  ...
}
--------------------------------------------------

Like every other search based construct, one can make use of elasticsearch's full search API by providing
additional parameters:

[source,json]
.Simple Search Transform
--------------------------------------------------
{
  "transform" : {
    "search" : {
      "request" : {
        "indices" : [ "logstash-*" ],
        "body" : {
          "size" : 0,
          "query" : {
            "match" : { "priority" : "error"}
          }
        }
      }
    }
  }
}
--------------------------------------------------

The above example executes a {ref}/search-request-search-type.html#count[count] search over all the logstash indices, matching all
the events with `error` priority.

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

[[transform-search-settings]]
.Search Transform Settings
[options="header"]
|======
| Name                                  |Required   | Default                                                                  | Description
| `request.search_type`                         | no        | {ref}/search-request-search-type.html#query-then-fetch[query_then_fetch] | The search {ref}/search-request-search-type.html[search type]
| `request.indices`                             | no        | all indices                                                              | One or more indices to search on (may be a comma-delimited string or an array of indices names).
| `request.types`                               | no        | all types                                                                | One or more document types to search on (may be a comma-delimited string or an array of document types names)
| `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 internal search operations <<default-internal-ops-timeouts, timeouts>>.
|======

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

As can be seen in the <<transform-search-settings, table>> above, the search transform support mustache templates.
This can either be as part of the body definition, or alternatively, point to a pre defined/registered template (either
defined in a file or {ref}/search-template.html#pre-registered-templates[registered] as a script in elasticsearch).
The following snippet shows an example of a search that refers to the scheduled time of the watch:

[source,json]
.Simple Search Transform using body template support
--------------------------------------------------
{
  "transform" : {
    "search" : {
      "index" : [ "logstash-*" ],
      "type" : "event",
      "body" : {
        "size" : 0,
        "query" : {
          "filtered" : {
            "filter" : {
              "bool" : {
                "must" : [
                  {
                    "range" : {
                      "@timestamp" : {
                        "from" : "{{ctx.trigger.scheduled_time}}||-30s",
                        "to" : "{{ctx.trigger.triggered_time}}"
                      }
                    }
                  },
                  {
                    "query" : {
                      "match" : { "priority" : "error"}
                    }
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
}
--------------------------------------------------

The model of the template (based on which the mustache template will be evaluated) is a union between the provided
`template.params` settings and the <<watch-execution-context, standard watch execution context model>>.

[source,json]
.Simple Search Transform using an inline template
--------------------------------------------------
{
  "transform" : {
    "search" : {
      "index" : [ "logstash-*" ],
      "type" : "event",
      "body" : {
        "size" : 0,
        "template" {
          "inline" : {
            "query" : {
              "filtered" : {
                "filter" : {
                  "bool" : {
                    "must" : [
                      {
                        "range" : {
                          "@timestamp" : {
                            "from" : "{{ctx.trigger.scheduled_time}}||-30s",
                            "to" : "{{ctx.trigger.triggered_time}}"
                          }
                        }
                      },
                      {
                        "query" : {
                          "match" : { "priority" : "{{priority}}"}
                        }
                      }
                    ]
                  }
                }
              }
            },
            "params" : {
              "priority" : "error"
            }
          }
        }
      }
    }
  }
}
--------------------------------------------------