2014-03-24 05:33:13 -04:00
|
|
|
[[search-template]]
|
2019-07-19 14:35:36 -04:00
|
|
|
=== Search Template
|
2014-03-24 05:33:13 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
Allows you to use the mustache language to pre render search requests.
|
2014-03-24 05:33:13 -04:00
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2014-03-24 05:33:13 -04:00
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
GET _search/template
|
2014-03-24 05:33:13 -04:00
|
|
|
{
|
2017-06-09 11:29:25 -04:00
|
|
|
"source" : {
|
2014-03-24 05:33:13 -04:00
|
|
|
"query": { "match" : { "{{my_field}}" : "{{my_value}}" } },
|
2014-03-25 10:24:31 -04:00
|
|
|
"size" : "{{my_size}}"
|
2014-03-24 05:33:13 -04:00
|
|
|
},
|
|
|
|
"params" : {
|
2017-02-08 11:05:22 -05:00
|
|
|
"my_field" : "message",
|
|
|
|
"my_value" : "some message",
|
2014-03-24 05:33:13 -04:00
|
|
|
"my_size" : 5
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// TEST[setup:twitter]
|
2014-03-24 05:33:13 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
[[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.
|
|
|
|
|
2014-03-24 05:33:13 -04:00
|
|
|
For more information on how Mustache templating and what kind of templating you
|
|
|
|
can do with it check out the http://mustache.github.io/mustache.5.html[online
|
|
|
|
documentation of the mustache project].
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
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::{docdir}/rest-api/common-parms.asciidoc[tag=index]
|
|
|
|
|
|
|
|
|
|
|
|
[[search-template-api-query-params]]
|
|
|
|
==== {api-query-parms-title}
|
|
|
|
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
|
|
|
|
|
|
|
|
`ccs_minimize_roundtrips`::
|
|
|
|
(Optional, boolean) If `true`, network round-trips are minimized for
|
|
|
|
cross-cluster search requests. Defaults to `true`.
|
|
|
|
|
|
|
|
include::{docdir}/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 `false`.
|
|
|
|
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
|
|
|
|
|
|
|
include::{docdir}/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::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
|
|
|
|
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=scroll]
|
|
|
|
|
|
|
|
include::{docdir}/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}
|
Scripting: add support for fine-grained settings
Allow to on/off scripting based on their source (where they get loaded from), the operation that executes them and their language.
The settings cover the following combinations:
- mode: on, off, sandbox
- source: indexed, dynamic, file
- engine: groovy, expressions, mustache, etc
- operation: update, search, aggs, mapping
The following settings are supported for every engine:
script.engine.groovy.indexed.update: sandbox/on/off
script.engine.groovy.indexed.search: sandbox/on/off
script.engine.groovy.indexed.aggs: sandbox/on/off
script.engine.groovy.indexed.mapping: sandbox/on/off
script.engine.groovy.dynamic.update: sandbox/on/off
script.engine.groovy.dynamic.search: sandbox/on/off
script.engine.groovy.dynamic.aggs: sandbox/on/off
script.engine.groovy.dynamic.mapping: sandbox/on/off
script.engine.groovy.file.update: sandbox/on/off
script.engine.groovy.file.search: sandbox/on/off
script.engine.groovy.file.aggs: sandbox/on/off
script.engine.groovy.file.mapping: sandbox/on/off
For ease of use, the following more generic settings are supported too:
script.indexed: sandbox/on/off
script.dynamic: sandbox/on/off
script.file: sandbox/on/off
script.update: sandbox/on/off
script.search: sandbox/on/off
script.aggs: sandbox/on/off
script.mapping: sandbox/on/off
These will be used to calculate the more specific settings, using the stricter setting of each combination. Operation based settings have precedence over conflicting source based ones.
Note that the `mustache` engine is affected by generic settings applied to any language, while native scripts aren't as they are static by definition.
Also, the previous `script.disable_dynamic` setting can now be deprecated.
Closes #6418
Closes #10116
Closes #10274
2015-03-06 12:38:11 -05:00
|
|
|
|
2019-08-22 08:40:09 -04:00
|
|
|
|
|
|
|
[[pre-registered-templates]]
|
|
|
|
===== Store a search template
|
|
|
|
|
|
|
|
You can store a search template using the stored scripts API.
|
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2019-08-22 08:40:09 -04:00
|
|
|
------------------------------------------
|
|
|
|
POST _scripts/<templateid>
|
|
|
|
{
|
|
|
|
"script": {
|
|
|
|
"lang": "mustache",
|
|
|
|
"source": {
|
|
|
|
"query": {
|
|
|
|
"match": {
|
|
|
|
"title": "{{query_string}}"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
// TEST[continued]
|
|
|
|
|
|
|
|
//////////////////////////
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
The API returns the following result if the template has been successfully
|
|
|
|
created:
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-06 09:22:08 -04:00
|
|
|
[source,console-result]
|
2019-08-22 08:40:09 -04:00
|
|
|
--------------------------------------------------
|
|
|
|
{
|
|
|
|
"acknowledged" : true
|
|
|
|
}
|
|
|
|
--------------------------------------------------
|
|
|
|
|
|
|
|
//////////////////////////
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
|
|
|
|
The template can be retrieved by calling
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2019-08-22 08:40:09 -04:00
|
|
|
------------------------------------------
|
|
|
|
GET _scripts/<templateid>
|
|
|
|
------------------------------------------
|
|
|
|
// TEST[continued]
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
The API returns the following result:
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-06 09:22:08 -04:00
|
|
|
[source,console-result]
|
2019-08-22 08:40:09 -04:00
|
|
|
------------------------------------------
|
|
|
|
{
|
|
|
|
"script" : {
|
|
|
|
"lang" : "mustache",
|
|
|
|
"source" : "{\"query\":{\"match\":{\"title\":\"{{query_string}}\"}}}",
|
|
|
|
"options": {
|
|
|
|
"content_type" : "application/json; charset=UTF-8"
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"_id": "<templateid>",
|
|
|
|
"found": true
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
|
|
|
|
This template can be deleted by calling
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2019-08-22 08:40:09 -04:00
|
|
|
------------------------------------------
|
|
|
|
DELETE _scripts/<templateid>
|
|
|
|
------------------------------------------
|
|
|
|
// TEST[continued]
|
|
|
|
|
|
|
|
|
|
|
|
[[use-registered-templates]]
|
2019-09-04 09:12:49 -04:00
|
|
|
===== Using a stored search template
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
To use a stored template at search time send the following request:
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2019-08-22 08:40:09 -04:00
|
|
|
------------------------------------------
|
|
|
|
GET _search/template
|
|
|
|
{
|
|
|
|
"id": "<templateid>", <1>
|
|
|
|
"params": {
|
|
|
|
"query_string": "search for these words"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
// TEST[catch:missing]
|
|
|
|
<1> Name of the stored template script.
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
|
2019-08-22 08:40:09 -04:00
|
|
|
[[_validating_templates]]
|
2019-09-04 09:12:49 -04:00
|
|
|
==== Validating a search template
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
A template can be rendered in a response with given parameters by using the
|
|
|
|
following request:
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2019-08-22 08:40:09 -04:00
|
|
|
------------------------------------------
|
|
|
|
GET _render/template
|
|
|
|
{
|
|
|
|
"source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
|
|
|
|
"params": {
|
|
|
|
"statuses" : {
|
|
|
|
"status": [ "pending", "published" ]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
|
|
|
|
The API returns the rendered template:
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-06 09:22:08 -04:00
|
|
|
[source,console-result]
|
2019-08-22 08:40:09 -04:00
|
|
|
------------------------------------------
|
|
|
|
{
|
|
|
|
"template_output": {
|
|
|
|
"query": {
|
|
|
|
"terms": {
|
|
|
|
"status": [ <1>
|
|
|
|
"pending",
|
|
|
|
"published"
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2019-09-06 09:22:08 -04:00
|
|
|
|
2019-08-22 08:40:09 -04:00
|
|
|
<1> `status` array has been populated with values from the `params` object.
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
|
|
|
|
Stored templates can also be rendered by calling the following request:
|
2019-08-22 08:40:09 -04:00
|
|
|
|
|
|
|
[source,js]
|
|
|
|
------------------------------------------
|
|
|
|
GET _render/template/<template_name>
|
|
|
|
{
|
|
|
|
"params": {
|
|
|
|
"..."
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
// NOTCONSOLE
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
[[search-template-explain-parameter]]
|
|
|
|
===== Using the explain parameter
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
You can use the `explain` parameter when running a template:
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2019-08-22 08:40:09 -04:00
|
|
|
------------------------------------------
|
|
|
|
GET _search/template
|
|
|
|
{
|
|
|
|
"id": "my_template",
|
|
|
|
"params": {
|
|
|
|
"status": [ "pending", "published" ]
|
|
|
|
},
|
|
|
|
"explain": true
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
// TEST[catch:missing]
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
|
|
|
|
[[search-template-profile-parameter]]
|
2019-08-22 08:40:09 -04:00
|
|
|
===== Profiling
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
You can use the `profile` parameter when running a template:
|
2019-08-22 08:40:09 -04:00
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2019-08-22 08:40:09 -04:00
|
|
|
------------------------------------------
|
|
|
|
GET _search/template
|
|
|
|
{
|
|
|
|
"id": "my_template",
|
|
|
|
"params": {
|
|
|
|
"status": [ "pending", "published" ]
|
|
|
|
},
|
|
|
|
"profile": true
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
// TEST[catch:missing]
|
2014-03-24 05:33:13 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
|
|
|
|
[[search-template-query-string-single]]
|
2014-03-24 05:33:13 -04:00
|
|
|
===== Filling in a query string with a single value
|
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2014-03-24 05:33:13 -04:00
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
GET _search/template
|
2014-03-24 05:33:13 -04:00
|
|
|
{
|
2017-06-09 11:29:25 -04:00
|
|
|
"source": {
|
2014-03-24 05:33:13 -04:00
|
|
|
"query": {
|
2017-02-08 11:05:22 -05:00
|
|
|
"term": {
|
|
|
|
"message": "{{query_string}}"
|
2014-03-24 05:33:13 -04:00
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"params": {
|
|
|
|
"query_string": "search for these words"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// TEST[setup:twitter]
|
2014-03-24 05:33:13 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
[[search-template-converting-to-json]]
|
2016-07-28 07:49:53 -04:00
|
|
|
===== Converting parameters to JSON
|
|
|
|
|
2016-09-09 07:06:32 -04:00
|
|
|
The `{{#toJson}}parameter{{/toJson}}` function can be used to convert parameters
|
2016-07-28 07:49:53 -04:00
|
|
|
like maps and array to their JSON representation:
|
2014-03-24 05:33:13 -04:00
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2014-03-24 05:33:13 -04:00
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
GET _search/template
|
2014-03-24 05:33:13 -04:00
|
|
|
{
|
2017-06-09 11:29:25 -04:00
|
|
|
"source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
|
2014-03-24 05:33:13 -04:00
|
|
|
"params": {
|
2017-02-08 11:05:22 -05:00
|
|
|
"statuses" : {
|
|
|
|
"status": [ "pending", "published" ]
|
|
|
|
}
|
2014-03-24 05:33:13 -04:00
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
|
|
|
|
which is rendered as:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
------------------------------------------
|
|
|
|
{
|
2016-07-28 07:49:53 -04:00
|
|
|
"query": {
|
|
|
|
"terms": {
|
|
|
|
"status": [
|
|
|
|
"pending",
|
|
|
|
"published"
|
|
|
|
]
|
|
|
|
}
|
2014-03-24 05:33:13 -04:00
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2014-03-24 05:33:13 -04:00
|
|
|
|
2016-07-28 07:49:53 -04:00
|
|
|
A more complex example substitutes an array of JSON objects:
|
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2016-07-28 07:49:53 -04:00
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
GET _search/template
|
2016-07-28 07:49:53 -04:00
|
|
|
{
|
2017-06-09 11:29:25 -04:00
|
|
|
"source": "{\"query\":{\"bool\":{\"must\": {{#toJson}}clauses{{/toJson}} }}}",
|
2016-07-28 07:49:53 -04:00
|
|
|
"params": {
|
|
|
|
"clauses": [
|
2017-02-08 11:05:22 -05:00
|
|
|
{ "term": { "user" : "foo" } },
|
|
|
|
{ "term": { "user" : "bar" } }
|
2016-07-28 07:49:53 -04:00
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
|
|
|
|
which is rendered as:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
------------------------------------------
|
|
|
|
{
|
|
|
|
"query" : {
|
|
|
|
"bool" : {
|
|
|
|
"must" : [
|
|
|
|
{
|
2017-02-08 11:05:22 -05:00
|
|
|
"term" : {
|
|
|
|
"user" : "foo"
|
|
|
|
}
|
2016-07-28 07:49:53 -04:00
|
|
|
},
|
|
|
|
{
|
2017-02-08 11:05:22 -05:00
|
|
|
"term" : {
|
|
|
|
"user" : "bar"
|
|
|
|
}
|
2016-07-28 07:49:53 -04:00
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2016-06-14 09:14:54 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
[[search-template-concatenate-array]]
|
2016-06-14 09:14:54 -04:00
|
|
|
===== Concatenating array of values
|
|
|
|
|
|
|
|
The `{{#join}}array{{/join}}` function can be used to concatenate the
|
|
|
|
values of an array as a comma delimited string:
|
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2016-06-14 09:14:54 -04:00
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
GET _search/template
|
2016-06-14 09:14:54 -04:00
|
|
|
{
|
2017-06-09 11:29:25 -04:00
|
|
|
"source": {
|
2016-06-14 09:14:54 -04:00
|
|
|
"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"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2016-06-14 09:14:54 -04:00
|
|
|
|
|
|
|
The function also accepts a custom delimiter:
|
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2016-06-14 09:14:54 -04:00
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
GET _search/template
|
2016-06-14 09:14:54 -04:00
|
|
|
{
|
2017-06-09 11:29:25 -04:00
|
|
|
"source": {
|
2016-06-14 09:14:54 -04:00
|
|
|
"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"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2016-06-14 09:14:54 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
[[search-template-default-values]]
|
2014-03-24 05:33:13 -04:00
|
|
|
===== Default values
|
|
|
|
|
|
|
|
A default value is written as `{{var}}{{^var}}default{{/var}}` for instance:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
------------------------------------------
|
|
|
|
{
|
2017-06-09 11:29:25 -04:00
|
|
|
"source": {
|
2014-03-24 05:33:13 -04:00
|
|
|
"query": {
|
|
|
|
"range": {
|
|
|
|
"line_no": {
|
|
|
|
"gte": "{{start}}",
|
|
|
|
"lte": "{{end}}{{^end}}20{{/end}}"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"params": { ... }
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2014-03-24 05:33:13 -04:00
|
|
|
|
|
|
|
When `params` is `{ "start": 10, "end": 15 }` this query would be rendered as:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
------------------------------------------
|
|
|
|
{
|
|
|
|
"range": {
|
|
|
|
"line_no": {
|
|
|
|
"gte": "10",
|
|
|
|
"lte": "15"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2014-03-24 05:33:13 -04:00
|
|
|
|
|
|
|
But when `params` is `{ "start": 10 }` this query would use the default value
|
|
|
|
for `end`:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
------------------------------------------
|
|
|
|
{
|
|
|
|
"range": {
|
|
|
|
"line_no": {
|
|
|
|
"gte": "10",
|
|
|
|
"lte": "20"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2016-06-14 09:14:54 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
[[search-template-conditional-clauses]]
|
2014-03-24 05:33:13 -04:00
|
|
|
===== 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:
|
2019-09-04 09:12:49 -04:00
|
|
|
|
2014-03-24 05:33:13 -04:00
|
|
|
[source,js]
|
|
|
|
------------------------------------------
|
|
|
|
{
|
|
|
|
"params": {
|
|
|
|
"text": "words to search for",
|
|
|
|
"line_no": { <1>
|
|
|
|
"start": 10, <1>
|
|
|
|
"end": 20 <1>
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2014-03-24 05:33:13 -04:00
|
|
|
<1> All three of these elements are optional.
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
|
2014-03-24 05:33:13 -04:00
|
|
|
We could write the query as:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
------------------------------------------
|
|
|
|
{
|
2014-10-31 10:27:57 -04:00
|
|
|
"query": {
|
2015-09-11 04:35:56 -04:00
|
|
|
"bool": {
|
|
|
|
"must": {
|
2014-03-24 05:33:13 -04:00
|
|
|
"match": {
|
|
|
|
"line": "{{text}}" <1>
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"filter": {
|
|
|
|
{{#line_no}} <2>
|
|
|
|
"range": {
|
|
|
|
"line_no": {
|
|
|
|
{{#start}} <3>
|
|
|
|
"gte": "{{start}}" <4>
|
|
|
|
{{#end}},{{/end}} <5>
|
|
|
|
{{/start}} <3>
|
|
|
|
{{#end}} <6>
|
|
|
|
"lte": "{{end}}" <7>
|
2014-10-31 09:39:24 -04:00
|
|
|
{{/end}} <6>
|
2014-03-24 05:33:13 -04:00
|
|
|
}
|
|
|
|
}
|
|
|
|
{{/line_no}} <2>
|
|
|
|
}
|
|
|
|
}
|
2014-10-31 10:27:57 -04:00
|
|
|
}
|
2014-03-24 05:33:13 -04:00
|
|
|
}
|
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2014-03-24 05:33:13 -04:00
|
|
|
<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`
|
|
|
|
|
2014-10-31 10:27:57 -04:00
|
|
|
[NOTE]
|
|
|
|
==================================
|
2014-03-24 05:33:13 -04:00
|
|
|
As written above, this template is not valid JSON because it includes the
|
2014-10-31 10:27:57 -04:00
|
|
|
_section_ markers like `{{#line_no}}`. For this reason, the template should
|
2016-07-28 07:49:53 -04:00
|
|
|
either be stored in a file (see <<pre-registered-templates>>) or, when used
|
2014-10-31 10:27:57 -04:00
|
|
|
via the REST API, should be written as a string:
|
|
|
|
|
2015-07-14 12:14:09 -04:00
|
|
|
[source,js]
|
2014-10-31 10:27:57 -04:00
|
|
|
--------------------
|
2017-06-09 11:29:25 -04:00
|
|
|
"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}}}}}}"
|
2014-10-31 10:27:57 -04:00
|
|
|
--------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2014-10-31 10:27:57 -04:00
|
|
|
==================================
|
2014-03-24 05:33:13 -04:00
|
|
|
|
2017-01-12 08:57:03 -05:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
[[search-template-encode-urls]]
|
2017-01-12 08:57:03 -05:00
|
|
|
===== Encoding URLs
|
|
|
|
|
|
|
|
The `{{#url}}value{{/url}}` function can be used to encode a string value
|
2019-09-04 09:12:49 -04:00
|
|
|
in a HTML encoding form as defined in by the
|
|
|
|
http://www.w3.org/TR/html4/[HTML specification].
|
2017-01-12 08:57:03 -05:00
|
|
|
|
|
|
|
As an example, it is useful to encode a URL:
|
|
|
|
|
2019-09-09 12:35:50 -04:00
|
|
|
[source,console]
|
2017-01-12 08:57:03 -05:00
|
|
|
------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
GET _render/template
|
2017-01-12 08:57:03 -05:00
|
|
|
{
|
2017-06-09 11:29:25 -04:00
|
|
|
"source" : {
|
2017-01-12 08:57:03 -05:00
|
|
|
"query" : {
|
|
|
|
"term": {
|
|
|
|
"http_access_log": "{{#url}}{{host}}/{{page}}{{/url}}"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"params": {
|
|
|
|
"host": "https://www.elastic.co/",
|
|
|
|
"page": "learn"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
|
2017-01-12 08:57:03 -05:00
|
|
|
The previous query will be rendered as:
|
|
|
|
|
2019-09-06 09:22:08 -04:00
|
|
|
[source,console-result]
|
2017-01-12 08:57:03 -05:00
|
|
|
------------------------------------------
|
|
|
|
{
|
|
|
|
"template_output" : {
|
|
|
|
"query" : {
|
|
|
|
"term" : {
|
|
|
|
"http_access_log" : "https%3A%2F%2Fwww.elastic.co%2F%2Flearn"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
------------------------------------------
|
2019-09-06 09:22:08 -04:00
|
|
|
|
2017-01-12 08:57:03 -05:00
|
|
|
|
2016-06-07 11:45:05 -04:00
|
|
|
[[multi-search-template]]
|
2019-07-19 14:35:36 -04:00
|
|
|
=== Multi Search Template
|
2016-06-07 11:45:05 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
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.
|
2016-06-07 11:45:05 -04:00
|
|
|
|
|
|
|
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
|
|
|
|
--------------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
2016-06-07 11:45:05 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
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.
|
|
|
|
|
2016-06-07 11:45:05 -04:00
|
|
|
|
2019-09-04 09:12:49 -04:00
|
|
|
[[multi-search-template-api-example]]
|
|
|
|
==== {api-examples-title}
|
2016-06-07 11:45:05 -04:00
|
|
|
|
|
|
|
[source,js]
|
|
|
|
--------------------------------------------------
|
|
|
|
$ cat requests
|
|
|
|
{"index": "test"}
|
2017-06-09 11:29:25 -04:00
|
|
|
{"source": {"query": {"match": {"user" : "{{username}}" }}}, "params": {"username": "john"}} <1>
|
|
|
|
{"source": {"query": {"{{query_type}}": {"name": "{{name}}" }}}, "params": {"query_type": "match_phrase_prefix", "name": "Smith"}}
|
2016-06-07 11:45:05 -04:00
|
|
|
{"index": "_all"}
|
|
|
|
{"id": "template_1", "params": {"query_string": "search for these words" }} <2>
|
|
|
|
|
2017-02-08 11:05:22 -05:00
|
|
|
$ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo
|
2016-06-07 11:45:05 -04:00
|
|
|
--------------------------------------------------
|
2017-02-08 11:05:22 -05:00
|
|
|
// NOTCONSOLE
|
|
|
|
// Not converting to console because this shows how curl works
|
2016-06-07 11:45:05 -04:00
|
|
|
<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
|
2019-09-04 09:12:49 -04:00
|
|
|
search template request, an object with `error` message will be returned in
|
|
|
|
place of the actual search response.
|