296 lines
7.9 KiB
Plaintext
296 lines
7.9 KiB
Plaintext
[[search-validate]]
|
|
=== Validate API
|
|
|
|
Validates a potentially expensive query without executing it.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET my-index-000001/_validate/query?q=user.id:kimchy
|
|
--------------------------------------------------
|
|
// TEST[setup:my_index]
|
|
|
|
|
|
[[search-validate-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /<target>/_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}
|
|
|
|
`<target>`::
|
|
(Optional, string)
|
|
Comma-separated list of data streams, indices, and index aliases to search.
|
|
Wildcard (`*`) expressions are supported.
|
|
+
|
|
To search all data streams or indices in a cluster, omit this parameter or use
|
|
`_all` or `*`.
|
|
|
|
include::{es-repo-dir}/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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
|
|
+
|
|
Defaults to `false`.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=analyzer]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=default_operator]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=df]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
|
|
|
|
`explain`::
|
|
(Optional, Boolean) If `true`, the response returns detailed information if an
|
|
error has occurred. Defaults to `false`.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
|
|
|
include::{es-repo-dir}/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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=search-q]
|
|
|
|
|
|
[[search-validate-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT my-index-000001/_bulk?refresh
|
|
{"index":{"_id":1}}
|
|
{"user" : { "id": "kimchy" }, "@timestamp" : "2099-11-15T14:12:12", "message" : "trying out Elasticsearch"}
|
|
{"index":{"_id":2}}
|
|
{"user" : { "id": "kimchi" }, "@timestamp" : "2099-11-15T14:12:13", "message" : "My user ID is similar to kimchy!"}
|
|
--------------------------------------------------
|
|
|
|
|
|
When sent a valid query:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET my-index-000001/_validate/query?q=user.id:kimchy
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
|
|
The response contains `valid:true`:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{"valid":true,"_shards":{"total":1,"successful":1,"failed":0}}
|
|
--------------------------------------------------
|
|
|
|
|
|
The query may also be sent in the request body:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET my-index-000001/_validate/query
|
|
{
|
|
"query" : {
|
|
"bool" : {
|
|
"must" : {
|
|
"query_string" : {
|
|
"query" : "*:*"
|
|
}
|
|
},
|
|
"filter" : {
|
|
"term" : { "user.id" : "kimchy" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// 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 {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]
|
|
--------------------------------------------------
|
|
GET my-index-000001/_validate/query
|
|
{
|
|
"query": {
|
|
"query_string": {
|
|
"query": "@timestamp:foo",
|
|
"lenient": false
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{"valid":false,"_shards":{"total":1,"successful":1,"failed":0}}
|
|
--------------------------------------------------
|
|
|
|
===== The explain parameter
|
|
|
|
An `explain` parameter can be specified to get more detailed information about
|
|
why a query failed:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET my-index-000001/_validate/query?explain=true
|
|
{
|
|
"query": {
|
|
"query_string": {
|
|
"query": "@timestamp:foo",
|
|
"lenient": false
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"valid" : false,
|
|
"_shards" : {
|
|
"total" : 1,
|
|
"successful" : 1,
|
|
"failed" : 0
|
|
},
|
|
"explanations" : [ {
|
|
"index" : "my-index-000001",
|
|
"valid" : false,
|
|
"error" : "my-index-000001/IAEc2nIXSSunQA_suI0MLw] QueryShardException[failed to create query:...failed to parse date field [foo]"
|
|
} ]
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"error" : "[^\"]+"/"error": "$body.explanations.0.error"/]
|
|
|
|
===== The rewrite parameter
|
|
|
|
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]
|
|
--------------------------------------------------
|
|
GET my-index-000001/_validate/query?rewrite=true
|
|
{
|
|
"query": {
|
|
"more_like_this": {
|
|
"like": {
|
|
"_id": "2"
|
|
},
|
|
"boost_terms": 1
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[skip:the output is randomized depending on which shard we hit]
|
|
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"valid": true,
|
|
"_shards": {
|
|
"total": 1,
|
|
"successful": 1,
|
|
"failed": 0
|
|
},
|
|
"explanations": [
|
|
{
|
|
"index": "my-index-000001",
|
|
"valid": true,
|
|
"explanation": "((user:terminator^3.71334 plot:future^2.763601 plot:human^2.8415773 plot:sarah^3.4193945 plot:kyle^3.8244398 plot:cyborg^3.9177752 plot:connor^4.040236 plot:reese^4.7133346 ... )~6) -ConstantScore(_id:2)) #(ConstantScore(_type:_doc))^0.0"
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
|
|
===== 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.
|
|
|
|
////
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT my-index-000001/_bulk?refresh
|
|
{"index":{"_id":1}}
|
|
{"user" : { "id": "kimchy" }, "@timestamp" : "2099-11-15T14:12:12", "message" : "trying out Elasticsearch"}
|
|
{"index":{"_id":2}}
|
|
{"user" : { "id": "kimchi" }, "@timestamp" : "2099-11-15T14:12:13", "message" : "My user ID is similar to kimchy!"}
|
|
--------------------------------------------------
|
|
////
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET my-index-000001/_validate/query?rewrite=true&all_shards=true
|
|
{
|
|
"query": {
|
|
"match": {
|
|
"user.id": {
|
|
"query": "kimchy",
|
|
"fuzziness": "auto"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"valid": true,
|
|
"_shards": {
|
|
"total": 1,
|
|
"successful": 1,
|
|
"failed": 0
|
|
},
|
|
"explanations": [
|
|
{
|
|
"index": "my-index-000001",
|
|
"shard": 0,
|
|
"valid": true,
|
|
"explanation": "(user.id:kimchi)^0.8333333 user.id:kimchy"
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|