[[search-validate]] === Validate API 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] + Defaults to `false`. 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 occurred. Defaults 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] -------------------------------------------------- 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!"} -------------------------------------------------- When sent a valid query: [source,console] -------------------------------------------------- GET twitter/_validate/query?q=user:foo -------------------------------------------------- // 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 twitter/_validate/query { "query" : { "bool" : { "must" : { "query_string" : { "query" : "*:*" } }, "filter" : { "term" : { "user" : "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 twitter/_validate/query { "query": { "query_string": { "query": "post_date: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 twitter/_validate/query?explain=true { "query": { "query_string": { "query": "post_date: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" : "twitter", "valid" : false, "error" : "twitter/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 twitter/_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": "twitter", "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 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 { "query": { "match": { "user": { "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": "twitter", "shard": 0, "valid": true, "explanation": "(user:kimchi)^0.8333333 user:kimchy" } ] } --------------------------------------------------