Search Template
editSearch Template
editAllows 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 } }
Request
editGET _search/template
Description
editThe /_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.
The mustache language is implemented in Elasticsearch 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.
Path parameters
edit-
<index>
- (Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.
Query parameters
edit-
allow_no_indices
-
(Optional, Boolean) If
false
, the request returns an error when a wildcard expression, index alias, or_all
value targets only missing or closed indices.Defaults to
true
. -
ccs_minimize_roundtrips
-
(Optional, Boolean) If
true
, network round-trips are minimized for cross-cluster search requests. Defaults totrue
. -
expand_wildcards
-
(Optional, string) Controls what kind of indices that wildcard expressions can expand to. Multiple values are accepted when separated by a comma, as in
open,hidden
. Valid values are:-
all
- Expand to open and closed indices, including hidden indices.
-
open
- Expand only to open indices.
-
closed
- Expand only to closed indices.
-
hidden
-
Expansion of wildcards will include hidden indices.
Must be combined with
open
,closed
, or both. -
none
- Wildcard expressions are not accepted.
-
-
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
. -
ignore_unavailable
-
(Optional, Boolean) If
false
, the request returns an error if it targets a missing or closed index. Defaults tofalse
. -
preference
- (Optional, string) Specifies the node or shard the operation should be performed on. Random by default.
-
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
. -
routing
- (Optional, string) Target the specified primary shard.
-
scroll
- (Optional, time units) Specifies how long a consistent view of the index should be maintained for scrolled search.
-
search_type
-
(Optional, string) The type of the search operation. Available options:
-
query_then_fetch
-
dfs_query_then_fetch
-
-
typed_keys
-
(Optional, Boolean) If
true
, aggregation and suggester names are prefixed by their respective types in the response. Defaults tofalse
.
Request body
editThe API request body must contain the search definition template and its parameters.
Response codes
editStore a search template
editYou 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>
Using a stored search template
editTo use a stored template at search time send the following request:
Validating a search template
editA 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:
Stored templates can also be rendered by calling the following request:
GET _render/template/<template_name> { "params": { "..." } }
Using the explain parameter
editYou can use the explain
parameter when running a template:
GET _search/template { "id": "my_template", "params": { "status": [ "pending", "published" ] }, "explain": true }
Profiling
editYou can use the profile
parameter when running a template:
GET _search/template { "id": "my_template", "params": { "status": [ "pending", "published" ] }, "profile": true }
Filling in a query string with a single value
editGET _search/template { "source": { "query": { "term": { "message": "{{query_string}}" } } }, "params": { "query_string": "search for these words" } }
Converting parameters to JSON
editThe {{#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" } } ] } } }
Concatenating array of values
editThe {{#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" } } } }
Default values
editA 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
editConditional 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:
When written as a query, the template would include invalid JSON, such as
section markers like {{#line_no}}
:
{ "query": { "bool": { "must": { "match": { "line": "{{text}}" } }, "filter": { {{#line_no}} "range": { "line_no": { {{#start}} "gte": "{{start}}" {{#end}},{{/end}} {{/start}} {{#end}} "lte": "{{end}}" {{/end}} } } {{/line_no}} } } } }
Fill in the value of param |
|
Include the |
|
Include the |
|
Fill in the value of param |
|
Add a comma after the |
|
Include the |
|
Fill in the value of param |
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}}}}}}"
Encoding URLs
editThe {{#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" } } } }