Validate Query

You can use the Validate Query API to validate a query without running it. The query can be sent as a path parameter or included in the request body.

Path and HTTP methods

The Validate Query API contains the following path:

  1. GET <index>/_validate/query

Path parameters

All path parameters are optional.

ParameterData typeDescription
indexStringThe index to validate the query against. If you don’t specify an index or multiple indexes as part of the URL (or want to override the URL value for an individual search), you can include it here. Examples include “logs-*” and [“my-store”, “sample_data_ecommerce”].
queryQuery objectThe query using Query DSL.

Query parameters

The following table lists the available query parameters. All query parameters are optional.

ParameterData typeDescription
all_shardsBooleanWhen true, validation is run against all shards instead of against one shard per index. Default is false.
allow_no_indicesBooleanWhether to ignore wildcards that don’t match any indexes. Default is true.
allow_partial_search_resultsBooleanWhether to return partial results if the request encounters an error or times out. Default is true.
analyzerStringThe analyzer to use in the query string. This should only be used with the q option.
analyze_wildcardBooleanSpecifies whether to analyze wildcard and prefix queries. Default is false.
default_operatorStringIndicates whether the default operator for a string query should be AND or OR. Default is OR.
dfStringThe default field if a field prefix is not provided in the query string.
expand_wildcardsStringSpecifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indexes), closed (match closed, non-hidden indexes), hidden (match hidden indexes), and none (deny wildcard expressions). Default is open.
explainBooleanWhether to return information about how OpenSearch computed the document’s score. Default is false.
ignore_unavailableBooleanSpecifies whether to include missing or closed indexes in the response and ignores unavailable shards during the search request. Default is false.
lenientBooleanSpecifies whether OpenSearch should ignore format-based query failures (for example, as a result of querying a text field for an integer). Default is false.
rewriteDetermines how OpenSearch rewrites and scores multi-term queries. Valid values are constant_score, scoring_boolean, constant_score_boolean, top_terms_N, top_terms_boost_N, and top_terms_blended_freqs_N. Default is constant_score. 
qStringA query in the Lucene string syntax.

Example request

The following example request uses an index named Hamlet created using a bulk request:

  1. PUT hamlet/_bulk?refresh
  2. {"index":{"_id":1}}
  3. {"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:12", "message" : "To Search or Not To Search"}
  4. {"index":{"_id":2}}
  5. {"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:13", "message" : "My dad says that I'm such a ham."}

copy

You can then use the Validate Query API to validate an index query, as shown in the following example:

  1. GET hamlet/_validate/query?q=user.id:hamlet

copy

The query can also be sent as a request body, as shown in the following example:

  1. GET hamlet/_validate/query
  2. {
  3.   "query" : {
  4.     "bool" : {
  5.       "must" : {
  6.         "query_string" : {
  7.           "query" : "*:*"
  8.         }
  9.       },
  10.       "filter" : {
  11.         "term" : { "user.id" : "hamlet" }
  12.       }
  13.     }
  14.   }
  15. }

copy

Example responses

If the query passes validation, then the response indicates that the query is true, as shown in the following example response, where the valid parameter is true:

  1. {
  2.   "_shards": {
  3.     "total": 1,
  4.     "successful": 1,
  5.     "failed": 0
  6.   },
  7.   "valid": true
  8. }

If the query does not pass validation, then OpenSearch responds that the query is false. The following example request query includes a dynamic mapping not configured in the hamlet index:

  1. GET hamlet/_validate/query
  2. {
  3.   "query": {
  4.     "query_string": {
  5.       "query": "@timestamp:foo",
  6.       "lenient": false
  7.     }
  8.   }
  9. }

OpenSearch responds with the following, where the valid parameter is false:

  1. {
  2.   "_shards": {
  3.     "total": 1,
  4.     "successful": 1,
  5.     "failed": 0
  6.   },
  7.   "valid": false
  8. }

Certain query parameters can also affect what is included in the response. The following examples show how the Explain, Rewrite, and all_shards query options affect the response.

Explain

The explain option returns information about the query failure in the explanations field, as shown in the following example response:

  1. {
  2.   "valid" : false,
  3.   "_shards" : {
  4.     "total" : 1,
  5.     "successful" : 1,
  6.     "failed" : 0
  7.   },
  8.   "explanations" : [ {
  9.     "index" : "_shakespeare",
  10.     "valid" : false,
  11.     "error" : "shakespeare/IAEc2nIXSSunQA_suI0MLw] QueryShardException[failed to create query:...failed to parse date field [foo]"
  12.   } ]
  13. }

Rewrite

When the rewrite option is set to true in the request, the explanations option shows the Lucene query that is executed as a string, as shown in the following response:

  1. {
  2.    "valid": true,
  3.    "_shards": {
  4.       "total": 1,
  5.       "successful": 1,
  6.       "failed": 0
  7.    },
  8.    "explanations": [
  9.       {
  10.          "index": "",
  11.          "valid": true,
  12.          "explanation": "((user:hamlet^4.256753 play:hamlet^6.863601 play:romeo^2.8415773 plot:puck^3.4193945 plot:othello^3.8244398 ... )~4) -ConstantScore(_id:2) #(ConstantScore(_type:_doc))^0.0"
  13.       }
  14.    ]
  15. }

Rewrite and all_shards

When both the rewrite and all_shards options are set to true, the Validate Query API responds with detailed information from all available shards as opposed to only one shard (the default), as shown in the following response:

  1. {
  2.   "valid": true,
  3.   "_shards": {
  4.     "total": 1,
  5.     "successful": 1,
  6.     "failed": 0
  7.   },
  8.   "explanations": [
  9.     {
  10.       "index": "my-index-000001",
  11.       "shard": 0,
  12.       "valid": true,
  13.       "explanation": "(user.id:hamlet)^0.6333333"
  14.     }
  15.   ]
  16. }