Allows you to use the mustache language to pre render search requests.
GET _search/template
{
"source" : {
"query": { "match" : { "{{my_field}}" : "{{my_value}}" } },
"size" : "{{my_size}}"
},
"params" : {
"my_field" : "message",
"my_value" : "foo",
"my_size" : 5
}
}
-
If the {es} {security-features} are enabled, you must have the
read
index privilege for the target data stream, index, or index alias. For cross-cluster search, see [cross-cluster-configuring].
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 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 scripting docs. |
+
Defaults to true
.
ccs_minimize_roundtrips
-
(Optional, Boolean) If
true
, network round-trips are minimized for cross-cluster search requests. Defaults totrue
.
explain
-
(Optional, Boolean) If
true
, the response includes additional details about score computation as part of a hit. Defaults tofalse
. ignore_throttled
-
(Optional, Boolean) If
true
, specified concrete, expanded or aliased indices are not included in the response when throttled. Defaults totrue
.
profile
-
(Optional, Boolean) If
true
, the query execution is profiled. Defaults tofalse
. rest_total_hits_as_int
-
(Optional, Boolean) If
true
,hits.total
are rendered as an integer in the response. Defaults tofalse
.
typed_keys
-
(Optional, Boolean) If
true
, aggregation and suggester names are prefixed by their respective types in the response. Defaults tofalse
.
The API request body must contain the search definition template and its parameters.
You can store a search template using the stored scripts API.
POST _scripts/<templateid>
{
"script": {
"lang": "mustache",
"source": {
"query": {
"match": {
"title": "{{query_string}}"
}
}
}
}
}
The template can be retrieved by calling
GET _scripts/<templateid>
The API returns the following 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
DELETE _scripts/<templateid>
A template can be rendered in a response with given parameters by using the following request:
GET _render/template
{
"source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
"params": {
"statuses" : {
"status": [ "pending", "published" ]
}
}
}
The API returns the rendered template:
{
"template_output": {
"query": {
"terms": {
"status": [ (1)
"pending",
"published"
]
}
}
}
}
-
status
array has been populated with values from theparams
object.
Stored templates can also be rendered by calling the following request:
GET _render/template/<template_name>
{
"params": {
"..."
}
}
You can use the explain
parameter when running a template:
GET _search/template
{
"id": "my_template",
"params": {
"status": [ "pending", "published" ]
},
"explain": true
}
You can use the profile
parameter when running a template:
GET _search/template
{
"id": "my_template",
"params": {
"status": [ "pending", "published" ]
},
"profile": true
}
GET _search/template
{
"source": {
"query": {
"term": {
"message": "{{query_string}}"
}
}
},
"params": {
"query_string": "search for these words"
}
}
The {{#toJson}}parameter{{/toJson}}
function can be used to convert parameters
like maps and array to their JSON representation:
GET _search/template
{
"source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
"params": {
"statuses" : {
"status": [ "pending", "published" ]
}
}
}
which is rendered as:
{
"query": {
"terms": {
"status": [
"pending",
"published"
]
}
}
}
A more complex example substitutes an array of JSON objects:
GET _search/template
{
"source": "{\"query\":{\"bool\":{\"must\": {{#toJson}}clauses{{/toJson}} }}}",
"params": {
"clauses": [
{ "term": { "user" : "foo" } },
{ "term": { "user" : "bar" } }
]
}
}
which is rendered as:
{
"query": {
"bool": {
"must": [
{
"term": {
"user": "foo"
}
},
{
"term": {
"user": "bar"
}
}
]
}
}
}
The {{#join}}array{{/join}}
function can be used to concatenate the
values of an array as a comma delimited string:
GET _search/template
{
"source": {
"query": {
"match": {
"emails": "{{#join}}emails{{/join}}"
}
}
},
"params": {
"emails": [ "username@email.com", "lastname@email.com" ]
}
}
which is rendered as:
{
"query" : {
"match" : {
"emails" : "username@email.com,lastname@email.com"
}
}
}
The function also accepts a custom delimiter:
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:
{
"query": {
"range": {
"born": {
"gte": "2016",
"lte": "31/12/2017",
"format": "dd/MM/yyyy||yyyy"
}
}
}
}
A default value is written as {{var}}{{^var}}default{{/var}}
for instance:
{
"source": {
"query": {
"range": {
"line_no": {
"gte": "{{start}}",
"lte": "{{end}}{{^end}}20{{/end}}"
}
}
}
},
"params": { ... }
}
When params
is { "start": 10, "end": 15 }
this query would be rendered as:
{
"range": {
"line_no": {
"gte": "10",
"lte": "15"
}
}
}
But when params
is { "start": 10 }
this query would use the default value
for end
:
{
"range": {
"line_no": {
"gte": "10",
"lte": "20"
}
}
}
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:
{
"params": {
"text": "words to search for",
"line_no": { (1)
"start": 10,
"end": 20
}
}
}
-
The
line_no
,start
, andend
parameters are optional.
When written as a query, the template would include invalid JSON, such as
section markers like {{#line_no}}
:
{
"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}}
}
}
}
}
-
Fill in the value of param
text
-
Include the
range
filter only ifline_no
is specified -
Include the
gte
clause only ifline_no.start
is specified -
Fill in the value of param
line_no.start
-
Add a comma after the
gte
clause only ifline_no.start
ANDline_no.end
are specified -
Include the
lte
clause only ifline_no.end
is specified -
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": "{\"query\":{\"bool\":{\"must\":{\"match\":{\"line\":\"{{text}}\"}},\"filter\":{{{#line_no}}\"range\":{\"line_no\":{{{#start}}\"gte\":\"{{start}}\"{{#end}},{{/end}}{{/start}}{{#end}}\"lte\":\"{{end}}\"{{/end}}}}{{/line_no}}}}}}"
The {{#url}}value{{/url}}
function can be used to encode a string value
in a HTML encoding form as defined in by the
HTML specification.
As an example, it is useful to encode a URL:
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:
{
"template_output": {
"query": {
"term": {
"http_access_log": "https%3A%2F%2Fwww.elastic.co%2F%2Flearn"
}
}
}
}
Allows to execute several search template requests.
-
If the {es} {security-features} are enabled, you must have the
read
index privilege for the target data stream, index, or index alias. For cross-cluster search, see [cross-cluster-configuring].
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 Multi Search API format:
header\n
body\n
header\n
body\n
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.
$ 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
-
Inline search template request
-
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.