123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706 |
- [[search-template]]
- === Search Template
- Allows you to use the mustache language to pre render search requests.
- [source,console]
- ------------------------------------------
- GET _search/template
- {
- "source" : {
- "query": { "match" : { "{{my_field}}" : "{{my_value}}" } },
- "size" : "{{my_size}}"
- },
- "params" : {
- "my_field" : "message",
- "my_value" : "foo",
- "my_size" : 5
- }
- }
- ------------------------------------------
- // TEST[setup:my_index]
- [[search-template-api-request]]
- ==== {api-request-title}
- `GET _search/template`
- [[search-template-api-desc]]
- ==== {api-description-title}
- The `/_search/template` endpoint allows you to use the mustache language to pre-
- render search requests, before they are executed and fill existing templates
- with template parameters.
- For more information on how Mustache templating and what kind of templating you
- can do with it check out the https://mustache.github.io/mustache.5.html[online
- documentation of the mustache project].
- NOTE: The mustache language is implemented in {es} as a sandboxed scripting
- language, hence it obeys settings that may be used to enable or disable scripts
- per type and context as described in the
- <<allowed-script-types-setting, scripting docs>>.
- [[search-template-api-path-params]]
- ==== {api-path-parms-title}
- include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index]
- [[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]
- `profile`::
- (Optional, boolean) If `true`, the query execution is profiled. Defaults
- to `false`.
- `rest_total_hits_as_int`::
- (Optional, boolean) If `true`, `hits.total` are rendered as an integer in
- the response. 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`, aggregation and suggester names are
- prefixed by their respective types in the response. Defaults to `false`.
-
- [[search-template-api-request-body]]
- ==== {api-request-body-title}
- The API request body must contain the search definition template and its parameters.
- [[search-template-api-example]]
- ==== {api-response-codes-title}
- [[pre-registered-templates]]
- ===== Store a search template
- You can store a search template using the stored scripts API.
- [source,console]
- ------------------------------------------
- POST _scripts/<templateid>
- {
- "script": {
- "lang": "mustache",
- "source": {
- "query": {
- "match": {
- "title": "{{query_string}}"
- }
- }
- }
- }
- }
- ------------------------------------------
- // TEST[continued]
- //////////////////////////
- The API returns the following result if the template has been successfully
- created:
- [source,console-result]
- --------------------------------------------------
- {
- "acknowledged" : true
- }
- --------------------------------------------------
- //////////////////////////
- The template can be retrieved by calling
- [source,console]
- ------------------------------------------
- GET _scripts/<templateid>
- ------------------------------------------
- // TEST[continued]
- The API returns the following result:
- [source,console-result]
- ------------------------------------------
- {
- "script" : {
- "lang" : "mustache",
- "source" : "{\"query\":{\"match\":{\"title\":\"{{query_string}}\"}}}",
- "options": {
- "content_type" : "application/json; charset=UTF-8"
- }
- },
- "_id": "<templateid>",
- "found": true
- }
- ------------------------------------------
- This template can be deleted by calling
- [source,console]
- ------------------------------------------
- DELETE _scripts/<templateid>
- ------------------------------------------
- // TEST[continued]
- [[use-registered-templates]]
- ===== Using a stored search template
- To use a stored template at search time send the following request:
- [source,console]
- ------------------------------------------
- GET _search/template
- {
- "id": "<templateid>", <1>
- "params": {
- "query_string": "search for these words"
- }
- }
- ------------------------------------------
- // TEST[catch:missing]
- <1> Name of the stored template script.
- [[_validating_templates]]
- ==== Validating a search template
- A template can be rendered in a response with given parameters by using the
- following request:
- [source,console]
- ------------------------------------------
- GET _render/template
- {
- "source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
- "params": {
- "statuses" : {
- "status": [ "pending", "published" ]
- }
- }
- }
- ------------------------------------------
- The API returns the rendered template:
- [source,console-result]
- ------------------------------------------
- {
- "template_output": {
- "query": {
- "terms": {
- "status": [ <1>
- "pending",
- "published"
- ]
- }
- }
- }
- }
- ------------------------------------------
- <1> `status` array has been populated with values from the `params` object.
- Stored templates can also be rendered by calling the following request:
- [source,js]
- ------------------------------------------
- GET _render/template/<template_name>
- {
- "params": {
- "..."
- }
- }
- ------------------------------------------
- // NOTCONSOLE
- [[search-template-explain-parameter]]
- ===== Using the explain parameter
- You can use the `explain` parameter when running a template:
- [source,console]
- ------------------------------------------
- GET _search/template
- {
- "id": "my_template",
- "params": {
- "status": [ "pending", "published" ]
- },
- "explain": true
- }
- ------------------------------------------
- // TEST[catch:missing]
- [[search-template-profile-parameter]]
- ===== Profiling
- You can use the `profile` parameter when running a template:
- [source,console]
- ------------------------------------------
- GET _search/template
- {
- "id": "my_template",
- "params": {
- "status": [ "pending", "published" ]
- },
- "profile": true
- }
- ------------------------------------------
- // TEST[catch:missing]
- [[search-template-query-string-single]]
- ===== Filling in a query string with a single value
- [source,console]
- ------------------------------------------
- GET _search/template
- {
- "source": {
- "query": {
- "term": {
- "message": "{{query_string}}"
- }
- }
- },
- "params": {
- "query_string": "search for these words"
- }
- }
- ------------------------------------------
- // TEST[setup:my_index]
- [[search-template-converting-to-json]]
- ===== Converting parameters to JSON
- The `{{#toJson}}parameter{{/toJson}}` function can be used to convert parameters
- like maps and array to their JSON representation:
- [source,console]
- ------------------------------------------
- GET _search/template
- {
- "source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
- "params": {
- "statuses" : {
- "status": [ "pending", "published" ]
- }
- }
- }
- ------------------------------------------
- which is rendered as:
- [source,js]
- ------------------------------------------
- {
- "query": {
- "terms": {
- "status": [
- "pending",
- "published"
- ]
- }
- }
- }
- ------------------------------------------
- // NOTCONSOLE
- A more complex example substitutes an array of JSON objects:
- [source,console]
- ------------------------------------------
- GET _search/template
- {
- "source": "{\"query\":{\"bool\":{\"must\": {{#toJson}}clauses{{/toJson}} }}}",
- "params": {
- "clauses": [
- { "term": { "user" : "foo" } },
- { "term": { "user" : "bar" } }
- ]
- }
- }
- ------------------------------------------
- which is rendered as:
- [source,js]
- ------------------------------------------
- {
- "query": {
- "bool": {
- "must": [
- {
- "term": {
- "user": "foo"
- }
- },
- {
- "term": {
- "user": "bar"
- }
- }
- ]
- }
- }
- }
- ------------------------------------------
- // NOTCONSOLE
- [[search-template-concatenate-array]]
- ===== Concatenating array of values
- The `{{#join}}array{{/join}}` function can be used to concatenate the
- values of an array as a comma delimited string:
- [source,console]
- ------------------------------------------
- GET _search/template
- {
- "source": {
- "query": {
- "match": {
- "emails": "{{#join}}emails{{/join}}"
- }
- }
- },
- "params": {
- "emails": [ "username@email.com", "lastname@email.com" ]
- }
- }
- ------------------------------------------
- which is rendered as:
- [source,js]
- ------------------------------------------
- {
- "query" : {
- "match" : {
- "emails" : "username@email.com,lastname@email.com"
- }
- }
- }
- ------------------------------------------
- // NOTCONSOLE
- The function also accepts a custom delimiter:
- [source,console]
- ------------------------------------------
- GET _search/template
- {
- "source": {
- "query": {
- "range": {
- "born": {
- "gte" : "{{date.min}}",
- "lte" : "{{date.max}}",
- "format": "{{#join delimiter='||'}}date.formats{{/join delimiter='||'}}"
- }
- }
- }
- },
- "params": {
- "date": {
- "min": "2016",
- "max": "31/12/2017",
- "formats": ["dd/MM/yyyy", "yyyy"]
- }
- }
- }
- ------------------------------------------
- which is rendered as:
- [source,js]
- ------------------------------------------
- {
- "query": {
- "range": {
- "born": {
- "gte": "2016",
- "lte": "31/12/2017",
- "format": "dd/MM/yyyy||yyyy"
- }
- }
- }
- }
- ------------------------------------------
- // NOTCONSOLE
- [[search-template-default-values]]
- ===== Default values
- A default value is written as `{{var}}{{^var}}default{{/var}}` for instance:
- [source,js]
- ------------------------------------------
- {
- "source": {
- "query": {
- "range": {
- "line_no": {
- "gte": "{{start}}",
- "lte": "{{end}}{{^end}}20{{/end}}"
- }
- }
- }
- },
- "params": { ... }
- }
- ------------------------------------------
- // NOTCONSOLE
- When `params` is `{ "start": 10, "end": 15 }` this query would be rendered as:
- [source,js]
- ------------------------------------------
- {
- "range": {
- "line_no": {
- "gte": "10",
- "lte": "15"
- }
- }
- }
- ------------------------------------------
- // NOTCONSOLE
- But when `params` is `{ "start": 10 }` this query would use the default value
- for `end`:
- [source,js]
- ------------------------------------------
- {
- "range": {
- "line_no": {
- "gte": "10",
- "lte": "20"
- }
- }
- }
- ------------------------------------------
- // NOTCONSOLE
- [[search-template-conditional-clauses]]
- ===== Conditional clauses
- Conditional clauses cannot be expressed using the JSON form of the template.
- Instead, the template *must* be passed as a string. For instance, let's say
- we wanted to run a `match` query on the `line` field, and optionally wanted
- to filter by line numbers, where `start` and `end` are optional.
- The `params` would look like:
- [source,js]
- ------------------------------------------
- {
- "params": {
- "text": "words to search for",
- "line_no": { <1>
- "start": 10,
- "end": 20
- }
- }
- }
- ------------------------------------------
- // NOTCONSOLE
- <1> The `line_no`, `start`, and `end` parameters are optional.
- When written as a query, the template would include invalid JSON, such as
- section markers like `{{#line_no}}`:
- [source,js]
- ------------------------------------------
- {
- "query": {
- "bool": {
- "must": {
- "match": {
- "line": "{{text}}" <1>
- }
- },
- "filter": {
- {{#line_no}} <2>
- "range": {
- "line_no": {
- {{#start}} <3>
- "gte": "{{start}}" <4>
- {{#end}},{{/end}} <5>
- {{/start}}
- {{#end}} <6>
- "lte": "{{end}}" <7>
- {{/end}}
- }
- }
- {{/line_no}}
- }
- }
- }
- }
- ------------------------------------------
- // NOTCONSOLE
- <1> Fill in the value of param `text`
- <2> Include the `range` filter only if `line_no` is specified
- <3> Include the `gte` clause only if `line_no.start` is specified
- <4> Fill in the value of param `line_no.start`
- <5> Add a comma after the `gte` clause only if `line_no.start`
- AND `line_no.end` are specified
- <6> Include the `lte` clause only if `line_no.end` is specified
- <7> Fill in the value of param `line_no.end`
- Because search templates cannot include invalid JSON, you can pass the same
- query as a string instead:
- [source,js]
- --------------------
- "source": "{\"query\":{\"bool\":{\"must\":{\"match\":{\"line\":\"{{text}}\"}},\"filter\":{{{#line_no}}\"range\":{\"line_no\":{{{#start}}\"gte\":\"{{start}}\"{{#end}},{{/end}}{{/start}}{{#end}}\"lte\":\"{{end}}\"{{/end}}}}{{/line_no}}}}}}"
- --------------------
- // NOTCONSOLE
- [[search-template-encode-urls]]
- ===== Encoding URLs
- The `{{#url}}value{{/url}}` function can be used to encode a string value
- in a HTML encoding form as defined in by the
- https://www.w3.org/TR/html4/[HTML specification].
- As an example, it is useful to encode a URL:
- [source,console]
- ------------------------------------------
- GET _render/template
- {
- "source": {
- "query": {
- "term": {
- "http_access_log": "{{#url}}{{host}}/{{page}}{{/url}}"
- }
- }
- },
- "params": {
- "host": "https://www.elastic.co/",
- "page": "learn"
- }
- }
- ------------------------------------------
- The previous query will be rendered as:
- [source,console-result]
- ------------------------------------------
- {
- "template_output": {
- "query": {
- "term": {
- "http_access_log": "https%3A%2F%2Fwww.elastic.co%2F%2Flearn"
- }
- }
- }
- }
- ------------------------------------------
- [[multi-search-template]]
- === Multi Search Template
- Allows to execute several search template requests.
- [[multi-search-template-api-request]]
- ==== {api-request-title}
- `GET _msearch/template`
- [[multi-search-template-api-desc]]
- ==== {api-description-title}
- Allows to execute several search template requests within the same API using the
- `_msearch/template` endpoint.
- The format of the request is similar to the <<search-multi-search, Multi
- Search API>> format:
- [source,js]
- --------------------------------------------------
- header\n
- body\n
- header\n
- body\n
- --------------------------------------------------
- // NOTCONSOLE
- The header part supports the same `index`, `search_type`, `preference`, and
- `routing` options as the Multi Search API.
- The body includes a search template body request and supports inline, stored and
- file templates.
- [[multi-search-template-api-example]]
- ==== {api-examples-title}
- [source,js]
- --------------------------------------------------
- $ cat requests
- {"index": "test"}
- {"source": {"query": {"match": {"user" : "{{username}}" }}}, "params": {"username": "john"}} <1>
- {"source": {"query": {"{{query_type}}": {"name": "{{name}}" }}}, "params": {"query_type": "match_phrase_prefix", "name": "Smith"}}
- {"index": "_all"}
- {"id": "template_1", "params": {"query_string": "search for these words" }} <2>
- $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo
- --------------------------------------------------
- // NOTCONSOLE
- // Not converting to console because this shows how curl works
- <1> Inline search template request
- <2> Search template request based on a stored template
- The response returns a `responses` array, which includes the search template
- response for each search template request matching its order in the original
- multi search template request. If there was a complete failure for that specific
- search template request, an object with `error` message will be returned in
- place of the actual search response.
|