[DOCS] Reformats search template and multi search template APIs (#46236)
* [DOCS] Reformats search template and multi search template APIs. Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
This commit is contained in:
István Zoltán Szabó
parent
5066835569
commit
0f0b77b263
|
|
@ -1,8 +1,7 @@
|
|||
[[search-template]]
|
||||
=== Search Template
|
||||
|
||||
The `/_search/template` endpoint allows to use the mustache language to pre render search requests,
|
||||
before they are executed and fill existing templates with template parameters.
|
||||
Allows you to use the mustache language to pre render search requests.
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -22,19 +21,87 @@ GET _search/template
|
|||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
|
||||
[[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 http://mustache.github.io/mustache.5.html[online
|
||||
documentation of the mustache project].
|
||||
|
||||
NOTE: 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
|
||||
<<allowed-script-types-setting, scripting docs>>
|
||||
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}
|
||||
|
||||
[float]
|
||||
==== Examples
|
||||
|
||||
[float]
|
||||
[[pre-registered-templates]]
|
||||
===== Store a search template
|
||||
|
||||
|
|
@ -61,8 +128,8 @@ POST _scripts/<templateid>
|
|||
|
||||
//////////////////////////
|
||||
|
||||
We want to be sure that the template has been created,
|
||||
because we'll use it later.
|
||||
The API returns the following result if the template has been successfully
|
||||
created:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -74,7 +141,8 @@ because we'll use it later.
|
|||
|
||||
//////////////////////////
|
||||
|
||||
This template can be retrieved by
|
||||
|
||||
The template can be retrieved by calling
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -83,7 +151,7 @@ GET _scripts/<templateid>
|
|||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
which is rendered as:
|
||||
The API returns the following result:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -101,7 +169,8 @@ which is rendered as:
|
|||
------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
This template can be deleted by
|
||||
|
||||
This template can be deleted by calling
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -110,26 +179,12 @@ DELETE _scripts/<templateid>
|
|||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
//////////////////////////
|
||||
|
||||
We want to be sure that the template has been created,
|
||||
because we'll use it later.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"acknowledged" : true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
//////////////////////////
|
||||
|
||||
[float]
|
||||
[[use-registered-templates]]
|
||||
===== Use a stored search template
|
||||
===== Using a stored search template
|
||||
|
||||
To use a stored template at search time use:
|
||||
To use a stored template at search time send the following request:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -145,11 +200,12 @@ GET _search/template
|
|||
// TEST[catch:missing]
|
||||
<1> Name of the stored template script.
|
||||
|
||||
[float]
|
||||
[[_validating_templates]]
|
||||
==== Validate a search template
|
||||
|
||||
A template can be rendered in a response with given parameters using
|
||||
[[_validating_templates]]
|
||||
==== Validating a search template
|
||||
|
||||
A template can be rendered in a response with given parameters by using the
|
||||
following request:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -165,7 +221,8 @@ GET _render/template
|
|||
------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
This call will return the rendered template:
|
||||
|
||||
The API returns the rendered template:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -185,7 +242,8 @@ This call will return the rendered template:
|
|||
// TESTRESPONSE
|
||||
<1> `status` array has been populated with values from the `params` object.
|
||||
|
||||
Stored templates can also be rendered using
|
||||
|
||||
Stored templates can also be rendered by calling the following request:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -198,10 +256,10 @@ GET _render/template/<template_name>
|
|||
------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
[float]
|
||||
===== Explain
|
||||
[[search-template-explain-parameter]]
|
||||
===== Using the explain parameter
|
||||
|
||||
You can use `explain` parameter when running a template:
|
||||
You can use the `explain` parameter when running a template:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -217,10 +275,11 @@ GET _search/template
|
|||
// CONSOLE
|
||||
// TEST[catch:missing]
|
||||
|
||||
[float]
|
||||
|
||||
[[search-template-profile-parameter]]
|
||||
===== Profiling
|
||||
|
||||
You can use `profile` parameter when running a template:
|
||||
You can use the `profile` parameter when running a template:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
|
|
@ -236,7 +295,8 @@ GET _search/template
|
|||
// CONSOLE
|
||||
// TEST[catch:missing]
|
||||
|
||||
[float]
|
||||
|
||||
[[search-template-query-string-single]]
|
||||
===== Filling in a query string with a single value
|
||||
|
||||
[source,js]
|
||||
|
|
@ -258,7 +318,7 @@ GET _search/template
|
|||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
|
||||
[float]
|
||||
[[search-template-converting-to-json]]
|
||||
===== Converting parameters to JSON
|
||||
|
||||
The `{{#toJson}}parameter{{/toJson}}` function can be used to convert parameters
|
||||
|
|
@ -337,7 +397,7 @@ which is rendered as:
|
|||
------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
[float]
|
||||
[[search-template-concatenate-array]]
|
||||
===== Concatenating array of values
|
||||
|
||||
The `{{#join}}array{{/join}}` function can be used to concatenate the
|
||||
|
|
@ -422,7 +482,7 @@ which is rendered as:
|
|||
------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
[float]
|
||||
[[search-template-default-values]]
|
||||
===== Default values
|
||||
|
||||
A default value is written as `{{var}}{{^var}}default{{/var}}` for instance:
|
||||
|
|
@ -476,7 +536,7 @@ for `end`:
|
|||
------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
[float]
|
||||
[[search-template-conditional-clauses]]
|
||||
===== Conditional clauses
|
||||
|
||||
Conditional clauses cannot be expressed using the JSON form of the template.
|
||||
|
|
@ -485,6 +545,7 @@ 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]
|
||||
------------------------------------------
|
||||
{
|
||||
|
|
@ -500,6 +561,7 @@ The `params` would look like:
|
|||
// NOTCONSOLE
|
||||
<1> All three of these elements are optional.
|
||||
|
||||
|
||||
We could write the query as:
|
||||
|
||||
[source,js]
|
||||
|
|
@ -556,11 +618,12 @@ via the REST API, should be written as a string:
|
|||
==================================
|
||||
|
||||
|
||||
[float]
|
||||
[[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 http://www.w3.org/TR/html4/[HTML specification].
|
||||
in a HTML encoding form as defined in by the
|
||||
http://www.w3.org/TR/html4/[HTML specification].
|
||||
|
||||
As an example, it is useful to encode a URL:
|
||||
|
||||
|
|
@ -583,6 +646,7 @@ GET _render/template
|
|||
------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
|
||||
The previous query will be rendered as:
|
||||
|
||||
[source,js]
|
||||
|
|
@ -602,8 +666,19 @@ The previous query will be rendered as:
|
|||
[[multi-search-template]]
|
||||
=== Multi Search Template
|
||||
|
||||
The multi search template API allows to execute several search template
|
||||
requests within the same API using the `_msearch/template` endpoint.
|
||||
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:
|
||||
|
|
@ -617,11 +692,15 @@ body\n
|
|||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
The header part supports the same `index`, `search_type`,
|
||||
`preference`, and `routing` options as the usual Multi Search API.
|
||||
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. Here is an example:
|
||||
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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -643,5 +722,5 @@ $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/tem
|
|||
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.
|
||||
search template request, an object with `error` message will be returned in
|
||||
place of the actual search response.
|
||||
|
|
|
|||
Loading…
Reference in New Issue