From dea4335f6e44c16358c00b8a97aba3e801aa374c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 4 Sep 2019 15:12:49 +0200 Subject: [PATCH] [DOCS] Reformats search template and multi search template APIs (#46236) * [DOCS] Reformats search template and multi search template APIs. Co-Authored-By: James Rodewig --- .../reference/search/search-template.asciidoc | 189 +++++++++++++----- 1 file changed, 134 insertions(+), 55 deletions(-) diff --git a/docs/reference/search/search-template.asciidoc b/docs/reference/search/search-template.asciidoc index 950477aa7d320..fb6fe4d41a257 100644 --- a/docs/reference/search/search-template.asciidoc +++ b/docs/reference/search/search-template.asciidoc @@ -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 -<> +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 +<>. + + +[[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/ ////////////////////////// -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/ // 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/ // 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 +==== 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] ------------------------------------------ @@ -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/ ------------------------------------------ // 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 <> 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. + -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] -------------------------------------------------- @@ -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.