Skip to content

Commit

Permalink
[DOCS] Reformats search template and multi search template APIs (#46236)
Browse files Browse the repository at this point in the history 
* [DOCS] Reformats search template and multi search template APIs.
Co-Authored-By: James Rodewig <[email protected]>
  • Loading branch information
@szabosteve
szabosteve committed Sep 4, 2019
1 parent 5066835 commit 0f0b77b
Showing 1 changed file with 134 additions and 55 deletions.
189 changes: 134 additions & 55 deletions docs/reference/search/search-template.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -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]
------------------------------------------
Expand All @@ -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

Expand All @@ -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]
--------------------------------------------------
Expand All @@ -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]
------------------------------------------
Expand All @@ -83,7 +151,7 @@ GET _scripts/<templateid>
// CONSOLE
// TEST[continued]

which is rendered as:
The API returns the following result:

[source,js]
------------------------------------------
Expand All @@ -101,7 +169,8 @@ which is rendered as:
------------------------------------------
// TESTRESPONSE

This template can be deleted by

This template can be deleted by calling

[source,js]
------------------------------------------
Expand All @@ -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]
------------------------------------------
Expand All @@ -145,11 +200,12 @@ GET _search/template
// TEST[catch:missing]
<1> Name of the stored template script.

[float]

[[_validating_templates]]
==== Validate a search template
==== Validating a search template

A template can be rendered in a response with given parameters using
A template can be rendered in a response with given parameters by using the
following request:

[source,js]
------------------------------------------
Expand All @@ -165,7 +221,8 @@ GET _render/template
------------------------------------------
// CONSOLE

This call will return the rendered template:

The API returns the rendered template:

[source,js]
------------------------------------------
Expand All @@ -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]
------------------------------------------
Expand All @@ -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]
------------------------------------------
Expand All @@ -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]
------------------------------------------
Expand All @@ -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]
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Expand All @@ -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]
------------------------------------------
{
Expand All @@ -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]
Expand Down Expand Up @@ -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:

Expand All @@ -583,6 +646,7 @@ GET _render/template
------------------------------------------
// CONSOLE


The previous query will be rendered as:

[source,js]
Expand All @@ -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:
Expand All @@ -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.


The body includes a search template body request and supports inline,
stored and file templates. Here is an example:
[[multi-search-template-api-example]]
==== {api-examples-title}

[source,js]
--------------------------------------------------
Expand All @@ -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.

0 comments on commit 0f0b77b

Please sign in to comment.