From 22454cc79b11456cfa4444f2953dd59a8f9f9266 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Thu, 5 Sep 2019 16:05:06 +0200 Subject: [PATCH 1/8] [DOCS] Reformats validate API. --- docs/reference/search/validate.asciidoc | 130 ++++++++++++++++-------- 1 file changed, 90 insertions(+), 40 deletions(-) diff --git a/docs/reference/search/validate.asciidoc b/docs/reference/search/validate.asciidoc index 94853c49e323d..470a49785b587 100644 --- a/docs/reference/search/validate.asciidoc +++ b/docs/reference/search/validate.asciidoc @@ -1,8 +1,74 @@ [[search-validate]] === Validate API -The validate API allows a user to validate a potentially expensive query -without executing it. We'll use the following test data to explain _validate: +Validates a potentially expensive query without executing it. + +[source,console] +-------------------------------------------------- +GET twitter/_validate/query?q=user:foo +-------------------------------------------------- + + +[[search-validate-api-request]] +==== {api-request-title} + +`GET //_validate/` + + +[[search-validate-api-desc]] +==== {api-description-title} + +The validate API allows you to validate a potentially expensive query +without executing it. The query can be sent either as a path parameter or in the +request body. + + +[[search-validate-api-path-params]] +==== {api-path-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] + +`query`:: + (Required, <>) Defines the search definition using the + <>. + + +[[search-validate-api-query-params]] +==== {api-query-parms-title} + +`all_shards`:: + (Optional, boolean) If `true`, the validation is executed on all shards + instead of one random shard per index. Defaults to `false`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=df] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] + +`explain`:: + (Optional, boolean) If `true`, the response returns detailed information if an + error has occured. Defautls to `false`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=lenient] + +`rewrite`:: + (Optional, boolean) If `true`, returns a more detailed explanation showing the + actual Lucene query that will be executed. Defaults to `false`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q] + + +[[search-validate-api-example]] +==== {api-examples-title} [source,console] -------------------------------------------------- @@ -14,6 +80,7 @@ PUT twitter/_bulk?refresh -------------------------------------------------- // TESTSETUP + When sent a valid query: [source,console] @@ -21,6 +88,7 @@ When sent a valid query: GET twitter/_validate/query?q=user:foo -------------------------------------------------- + The response contains `valid:true`: [source,js] @@ -29,30 +97,6 @@ The response contains `valid:true`: -------------------------------------------------- // TESTRESPONSE -[float] -=== Request Parameters - -When executing exists using the query parameter `q`, the query passed is -a query string using Lucene query parser. There are additional -parameters that can be passed: - -[cols="<,<",options="header",] -|======================================================================= -|Name |Description -|`df` |The default field to use when no field prefix is defined within the -query. - -|`analyzer` |The analyzer name to be used when analyzing the query string. - -|`default_operator` |The default operator to be used, can be `AND` or -`OR`. Defaults to `OR`. - -|`lenient` |If set to true will cause format based failures (like -providing text to a numeric field) to be ignored. Defaults to false. - -|`analyze_wildcard` |Should wildcard and prefix queries be analyzed or -not. Defaults to `false`. -|======================================================================= The query may also be sent in the request body: @@ -78,9 +122,9 @@ GET twitter/_validate/query NOTE: The query being sent in the body must be nested in a `query` key, same as the <> works -If the query is invalid, `valid` will be `false`. Here the query is -invalid because Elasticsearch knows the post_date field should be a date -due to dynamic mapping, and 'foo' does not correctly parse into a date: +If the query is invalid, `valid` will be `false`. Here the query is invalid +because {es} knows the `post_date` field should be a date due to dynamic +mapping, and 'foo' does not correctly parse into a date: [source,console] -------------------------------------------------- @@ -101,8 +145,10 @@ GET twitter/_validate/query -------------------------------------------------- // TESTRESPONSE -An `explain` parameter can be specified to get more detailed information -about why a query failed: +===== The explain parameter + +An `explain` parameter can be specified to get more detailed information about +why a query failed: [source,console] -------------------------------------------------- @@ -117,7 +163,8 @@ GET twitter/_validate/query?explain=true } -------------------------------------------------- -responds with: + +The API returns the following response: [source,js] -------------------------------------------------- @@ -137,11 +184,11 @@ responds with: -------------------------------------------------- // TESTRESPONSE[s/"error" : "[^\"]+"/"error": "$body.explanations.0.error"/] -When the query is valid, the explanation defaults to the string -representation of that query. With `rewrite` set to `true`, the explanation -is more detailed showing the actual Lucene query that will be executed. +===== The rewrite parameter -For More Like This: +When the query is valid, the explanation defaults to the string representation +of that query. With `rewrite` set to `true`, the explanation is more detailed +showing the actual Lucene query that will be executed. [source,console] -------------------------------------------------- @@ -159,7 +206,8 @@ GET twitter/_validate/query?rewrite=true -------------------------------------------------- // TEST[skip:the output is randomized depending on which shard we hit] -Response: + +The API returns the following response: [source,js] -------------------------------------------------- @@ -181,14 +229,15 @@ Response: -------------------------------------------------- // TESTRESPONSE + +===== Rewrite and all_shards parameters + By default, the request is executed on a single shard only, which is randomly selected. The detailed explanation of the query may depend on which shard is being hit, and therefore may vary from one request to another. So, in case of query rewrite the `all_shards` parameter should be used to get response from all available shards. -For Fuzzy Queries: - [source,console] -------------------------------------------------- GET twitter/_validate/query?rewrite=true&all_shards=true @@ -204,7 +253,8 @@ GET twitter/_validate/query?rewrite=true&all_shards=true } -------------------------------------------------- -Response: + +The API returns the following response: [source,js] -------------------------------------------------- From f8c76e5169119e7fc969acf3928bdcaebc69efc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 16 Sep 2019 17:48:45 +0200 Subject: [PATCH 2/8] Update docs/reference/search/validate.asciidoc Co-Authored-By: James Rodewig --- docs/reference/search/validate.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/search/validate.asciidoc b/docs/reference/search/validate.asciidoc index 470a49785b587..e789f066dedf3 100644 --- a/docs/reference/search/validate.asciidoc +++ b/docs/reference/search/validate.asciidoc @@ -7,6 +7,7 @@ Validates a potentially expensive query without executing it. -------------------------------------------------- GET twitter/_validate/query?q=user:foo -------------------------------------------------- +// TEST[setup:twitter] [[search-validate-api-request]] From 4b7ffbcce38c0df7529289f5f085e920fb2d04b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 16 Sep 2019 17:49:05 +0200 Subject: [PATCH 3/8] Update docs/reference/search/validate.asciidoc Co-Authored-By: James Rodewig --- docs/reference/search/validate.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/search/validate.asciidoc b/docs/reference/search/validate.asciidoc index e789f066dedf3..ef4807f446196 100644 --- a/docs/reference/search/validate.asciidoc +++ b/docs/reference/search/validate.asciidoc @@ -79,7 +79,6 @@ PUT twitter/_bulk?refresh {"index":{"_id":2}} {"user" : "kimchi", "post_date" : "2009-11-15T14:12:13", "message" : "My username is similar to @kimchy!"} -------------------------------------------------- -// TESTSETUP When sent a valid query: From 51d270838dc3c658aeb02a7c88866761884b44b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 16 Sep 2019 17:49:16 +0200 Subject: [PATCH 4/8] Update docs/reference/search/validate.asciidoc Co-Authored-By: James Rodewig --- docs/reference/search/validate.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/search/validate.asciidoc b/docs/reference/search/validate.asciidoc index ef4807f446196..a0e79e04e28eb 100644 --- a/docs/reference/search/validate.asciidoc +++ b/docs/reference/search/validate.asciidoc @@ -87,6 +87,7 @@ When sent a valid query: -------------------------------------------------- GET twitter/_validate/query?q=user:foo -------------------------------------------------- +// TEST[continued] The response contains `valid:true`: From 52bc432c4d693e2b762472eb6ea433da4fce5461 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 16 Sep 2019 17:57:47 +0200 Subject: [PATCH 5/8] [DOCS] Adds test comments to fix CI tests. --- docs/reference/search/validate.asciidoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/reference/search/validate.asciidoc b/docs/reference/search/validate.asciidoc index a0e79e04e28eb..dffa4965e79a2 100644 --- a/docs/reference/search/validate.asciidoc +++ b/docs/reference/search/validate.asciidoc @@ -119,6 +119,7 @@ GET twitter/_validate/query } } -------------------------------------------------- +// TEST[continued] NOTE: The query being sent in the body must be nested in a `query` key, same as the <> works @@ -139,6 +140,7 @@ GET twitter/_validate/query } } -------------------------------------------------- +// TEST[continued] [source,js] -------------------------------------------------- @@ -163,6 +165,7 @@ GET twitter/_validate/query?explain=true } } -------------------------------------------------- +// TEST[continued] The API returns the following response: @@ -239,6 +242,16 @@ being hit, and therefore may vary from one request to another. So, in case of query rewrite the `all_shards` parameter should be used to get response from all available shards. +//// +[source,console] +-------------------------------------------------- +PUT twitter/_bulk?refresh +{"index":{"_id":1}} +{"user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch"} +{"index":{"_id":2}} +{"user" : "kimchi", "post_date" : "2009-11-15T14:12:13", "message" : "My username is similar to @kimchy!"} +-------------------------------------------------- +//// [source,console] -------------------------------------------------- GET twitter/_validate/query?rewrite=true&all_shards=true From a4cab7696e4a80d889a7b63dd98e2f0eae0c2526 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 16 Sep 2019 18:16:28 +0200 Subject: [PATCH 6/8] [DOCS] Changes query parameter description to a common param reference. --- docs/reference/search/validate.asciidoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/reference/search/validate.asciidoc b/docs/reference/search/validate.asciidoc index dffa4965e79a2..1c076c3b53fae 100644 --- a/docs/reference/search/validate.asciidoc +++ b/docs/reference/search/validate.asciidoc @@ -29,9 +29,7 @@ request body. include::{docdir}/rest-api/common-parms.asciidoc[tag=index] -`query`:: - (Required, <>) Defines the search definition using the - <>. +include::{docdir}/rest-api/common-parms.asciidoc[tag=query] [[search-validate-api-query-params]] From cbc34c4eecda87392e6c62b809a8125869084287 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 17 Sep 2019 15:38:09 +0200 Subject: [PATCH 7/8] [DOCS] Changes snippet comments. --- docs/reference/search/validate.asciidoc | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/docs/reference/search/validate.asciidoc b/docs/reference/search/validate.asciidoc index 1c076c3b53fae..1081ad87a9792 100644 --- a/docs/reference/search/validate.asciidoc +++ b/docs/reference/search/validate.asciidoc @@ -90,11 +90,10 @@ GET twitter/_validate/query?q=user:foo The response contains `valid:true`: -[source,js] +[source,console-result] -------------------------------------------------- {"valid":true,"_shards":{"total":1,"successful":1,"failed":0}} -------------------------------------------------- -// TESTRESPONSE The query may also be sent in the request body: @@ -140,11 +139,10 @@ GET twitter/_validate/query -------------------------------------------------- // TEST[continued] -[source,js] +[source,console-result] -------------------------------------------------- {"valid":false,"_shards":{"total":1,"successful":1,"failed":0}} -------------------------------------------------- -// TESTRESPONSE ===== The explain parameter @@ -168,7 +166,7 @@ GET twitter/_validate/query?explain=true The API returns the following response: -[source,js] +[source,console-result] -------------------------------------------------- { "valid" : false, @@ -211,7 +209,7 @@ GET twitter/_validate/query?rewrite=true The API returns the following response: -[source,js] +[source,console-result] -------------------------------------------------- { "valid": true, @@ -229,7 +227,6 @@ The API returns the following response: ] } -------------------------------------------------- -// TESTRESPONSE ===== Rewrite and all_shards parameters @@ -250,6 +247,7 @@ PUT twitter/_bulk?refresh {"user" : "kimchi", "post_date" : "2009-11-15T14:12:13", "message" : "My username is similar to @kimchy!"} -------------------------------------------------- //// + [source,console] -------------------------------------------------- GET twitter/_validate/query?rewrite=true&all_shards=true @@ -268,7 +266,7 @@ GET twitter/_validate/query?rewrite=true&all_shards=true The API returns the following response: -[source,js] +[source,console-result] -------------------------------------------------- { "valid": true, @@ -287,4 +285,3 @@ The API returns the following response: ] } -------------------------------------------------- -// TESTRESPONSE From d056d14679dd30e56265cf6a7cd66fcc1de41a0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 18 Sep 2019 09:44:48 +0200 Subject: [PATCH 8/8] [DOCS] Adds test comment to an examplle snippet. --- docs/reference/search/validate.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/search/validate.asciidoc b/docs/reference/search/validate.asciidoc index 1081ad87a9792..9ec81279f3df6 100644 --- a/docs/reference/search/validate.asciidoc +++ b/docs/reference/search/validate.asciidoc @@ -262,7 +262,7 @@ GET twitter/_validate/query?rewrite=true&all_shards=true } } -------------------------------------------------- - +// TEST[continued] The API returns the following response: