OpenSearch/docs/reference/search/validate.asciidoc

[[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]

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]
--------------------------------------------------
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"
    }
  ]
}
--------------------------------------------------