Validate APIedit
The validate API allows a user to validate a potentially expensive query without executing it. The following example shows how it can be used:
curl -XPUT 'http://localhost:9200/twitter/tweet/1' -d '{
"user" : "kimchy",
"post_date" : "2009-11-15T14:12:12",
"message" : "trying out Elasticsearch"
}'When the query is valid, the response contains valid:true:
curl -XGET 'http://localhost:9200/twitter/_validate/query?q=user:foo'
{"valid":true,"_shards":{"total":1,"successful":1,"failed":0}}Request Parametersedit
When executing exists using the query parameter q, the query passed is
a query string using Lucene query parser. There are additional
parameters that can be passed:
| Name | Description |
|---|---|
| The default field to use when no field prefix is defined within the query. |
| The analyzer name to be used when analyzing the query string. |
| The default operator to be used, can be |
| If set to true will cause format based failures (like providing text to a numeric field) to be ignored. Defaults to false. |
| Should terms be automatically lowercased or
not. Defaults to |
| Should wildcard and prefix queries be analyzed or
not. Defaults to |
Or, with a request body:
curl -XGET 'http://localhost:9200/twitter/tweet/_validate/query' -d '{
"query" : {
"filtered" : {
"query" : {
"query_string" : {
"query" : "*:*"
}
},
"filter" : {
"term" : { "user" : "kimchy" }
}
}
}
}'
{"valid":true,"_shards":{"total":1,"successful":1,"failed":0}}
The query being sent in the body must be nested in a query key, same as
the search api works
If the query is invalid, valid will be false. Here the query is
invalid because Elasticsearch knows the post_date field should be a date
due to dynamic mapping, and foo does not correctly parse into a date:
curl -XGET 'http://localhost:9200/twitter/tweet/_validate/query?q=post_date:foo'
{"valid":false,"_shards":{"total":1,"successful":1,"failed":0}}An explain parameter can be specified to get more detailed information
about why a query failed:
curl -XGET 'http://localhost:9200/twitter/tweet/_validate/query?q=post_date:foo&pretty=true&explain=true'
{
"valid" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"failed" : 0
},
"explanations" : [ {
"index" : "twitter",
"valid" : false,
"error" : "org.elasticsearch.index.query.QueryParsingException: [twitter] Failed to parse; org.elasticsearch.ElasticsearchParseException: failed to parse date field [foo], tried both date format [dateOptionalTime], and timestamp number; java.lang.IllegalArgumentException: Invalid format: \"foo\""
} ]
}
[1.6.0]
Added in 1.6.0. 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.
For Fuzzy Queries:
curl -XGET 'http://localhost:9200/imdb/movies/_validate/query?rewrite=true'
{
"query": {
"fuzzy": {
"actors": "kyle"
}
}
}Response:
{
"valid": true,
"_shards": {
"total": 1,
"successful": 1,
"failed": 0
},
"explanations": [
{
"index": "imdb",
"valid": true,
"explanation": "filtered(plot:kyle plot:kylie^0.75 plot:kyne^0.75 plot:lyle^0.75 plot:pyle^0.75)->cache(_type:movies)"
}
]
}For More Like This:
curl -XGET 'http://localhost:9200/imdb/movies/_validate/query?rewrite=true'
{
"query": {
"more_like_this": {
"like": {
"_id": "88247"
},
"boost_terms": 1
}
}
}Response:
{
"valid": true,
"_shards": {
"total": 1,
"successful": 1,
"failed": 0
},
"explanations": [
{
"index": "imdb",
"valid": true,
"explanation": "filtered(((title: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(_uid:movies#88247))->cache(_type:movies)"
}
]
}
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.