OpenSearch/docs/reference/search/validate.asciidoc

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