elasticsearch/docs/reference/search/search-template-api.asciidoc

[[search-template-api]]
=== Search template API
++++
<titleabbrev>Search template</titleabbrev>
++++

Runs a search with a <<search-template,search template>>.

////
[source,console]
----
PUT _scripts/my-search-template
{
  "script": {
    "lang": "mustache",
    "source": {
      "query": {
        "match": {
          "message": "{{query_string}}"
        }
      },
      "from": "{{from}}",
      "size": "{{size}}"
    },
    "params": {
      "query_string": "My query string"
    }
  }
}

PUT my-index/_doc/1?refresh
{
  "message": "hello world"
}
----
// TESTSETUP
////

[source,console]
----
GET my-index/_search/template
{
  "id": "my-search-template",
  "params": {
    "query_string": "hello world",
    "from": 0,
    "size": 10
  }
}
----

[[search-template-api-request]]
==== {api-request-title}

`GET <target>/_search/template`

`GET _search/template`

`POST <target>/_search/template`

`POST _search/template`

[[search-template-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `read`
<<privileges-list-indices,index privilege>> for the target data stream, index,
or alias. For cross-cluster search, see <<remote-clusters-security>>.

[[search-template-api-path-params]]
==== {api-path-parms-title}

`<target>`::
(Optional, string) Comma-separated list of data streams, indices, and aliases to
search. Supports wildcards (`*`). To search all data streams and indices, omit
this parameter or use `*`.

[[search-template-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `true`.

`ccs_minimize_roundtrips`::
(Optional, Boolean) If `true`, network round-trips are minimized for
cross-cluster search requests. Defaults to `true`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]

`explain`::
(Optional, Boolean) If `true`, the response includes additional details about
score computation as part of a hit. Defaults to `false`.

`ignore_throttled`::
(Optional, Boolean) If `true`, specified concrete, expanded, or aliased indices
are not included in the response when throttled. Defaults to `true`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=preference]

`rest_total_hits_as_int`::
(Optional, Boolean) If `true`, the response returns `hits.total` as an integer.
If false, it returns `hits.total` as an object. Defaults to `false`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=scroll]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=search_type]

`typed_keys`::
(Optional, Boolean) If `true`, the response prefixes aggregation and suggester
names with their respective types. Defaults to `false`.

[[search-template-api-request-body]]
==== {api-request-body-title}

// tag::body-params[]
`explain`::
(Optional, Boolean) If `true`, returns detailed information about score
calculation as part of each hit. Defaults to `false`.
// end::body-params[]
+
If you specify both this and the `explain` query parameter, the API uses only
the query parameter.

// tag::body-params[]
`id`::
(Required*, string) ID of the search template to use. If no `source` is
specified, this parameter is required.

`params`::
(Optional, object) Key-value pairs used to replace Mustache variables in the
template. The key is the variable name. The value is the variable value.

`profile`::
(Optional, Boolean) If `true`, the query execution is profiled. Defaults to
`false`.

`source`::
(Required*, object) An inline search template. Supports the same parameters as
the <<search-search,search API>>'s request body. Also supports
https://mustache.github.io/[Mustache] variables.
+
If no `id` is specified, this parameter is required.
// end::body-params[]