[DOCS] Reformats validate API (#46389)
* [DOCS] Reformats validate API. Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
This commit is contained in:
István Zoltán Szabó
parent
142b10604e
commit
e59be0354a
|
|
@ -1,8 +1,73 @@
|
|||
[[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
|
||||
--------------------------------------------------
|
||||
// TEST[setup:twitter]
|
||||
|
||||
|
||||
[[search-validate-api-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /<index>/_validate/<query>`
|
||||
|
||||
|
||||
[[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]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=query]
|
||||
|
||||
|
||||
[[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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -12,7 +77,7 @@ 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:
|
||||
|
||||
|
|
@ -20,6 +85,8 @@ When sent a valid query:
|
|||
--------------------------------------------------
|
||||
GET twitter/_validate/query?q=user:foo
|
||||
--------------------------------------------------
|
||||
// TEST[continued]
|
||||
|
||||
|
||||
The response contains `valid:true`:
|
||||
|
||||
|
|
@ -29,31 +96,6 @@ The response contains `valid:true`:
|
|||
--------------------------------------------------
|
||||
|
||||
|
||||
[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:
|
||||
|
||||
[source,console]
|
||||
|
|
@ -74,13 +116,14 @@ GET twitter/_validate/query
|
|||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TEST[continued]
|
||||
|
||||
NOTE: The query being sent in the body must be nested in a `query` key, same as
|
||||
the <<search-search,search api>> 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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -94,14 +137,17 @@ GET twitter/_validate/query
|
|||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TEST[continued]
|
||||
|
||||
[source,console-result]
|
||||
--------------------------------------------------
|
||||
{"valid":false,"_shards":{"total":1,"successful":1,"failed":0}}
|
||||
--------------------------------------------------
|
||||
|
||||
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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -115,8 +161,10 @@ GET twitter/_validate/query?explain=true
|
|||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TEST[continued]
|
||||
|
||||
responds with:
|
||||
|
||||
The API returns the following response:
|
||||
|
||||
[source,console-result]
|
||||
--------------------------------------------------
|
||||
|
|
@ -136,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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -158,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,console-result]
|
||||
--------------------------------------------------
|
||||
|
|
@ -179,13 +228,25 @@ Response:
|
|||
}
|
||||
--------------------------------------------------
|
||||
|
||||
|
||||
===== 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]
|
||||
--------------------------------------------------
|
||||
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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -201,8 +262,9 @@ GET twitter/_validate/query?rewrite=true&all_shards=true
|
|||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TEST[continued]
|
||||
|
||||
Response:
|
||||
The API returns the following response:
|
||||
|
||||
[source,console-result]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue