elasticsearch-definitive-guide-en

=== Validating Queries

Queries can become quite complex and, especially((("validate query API")))((("queries", "validating"))) when combined with different analyzers and field mappings, can become a bit difficult to follow. The validate-query API can be used to check whether a query is valid.

[source,js]

GET /gb/tweet/_validate/query { "query": { "tweet" : { "match" : "really powerful" } }

}

// SENSE: 054_Query_DSL/80_Validate_query.json

The response to the preceding validate request tells us that the query is invalid:

[source,js]

{ "valid" : false, "_shards" : { "total" : 1, "successful" : 1, "failed" : 0 }

}

==== Understanding Errors

To find out ((("validate query API", "understqnding errors")))why it is invalid, add the explain parameter((("explain parameter"))) to the query string:

[source,js]

GET /gb/tweet/_validate/query?explain <1> { "query": { "tweet" : { "match" : "really powerful" } }

}

// SENSE: 054_Query_DSL/80_Validate_query.json

<1> The explain flag provides more information about why a query is invalid.

Apparently, we've mixed up the type of query (match) with the name of the field (tweet):

[source,js]

{ "valid" : false, "_shards" : { ... }, "explanations" : [ { "index" : "gb", "valid" : false, "error" : "org.elasticsearch.index.query.QueryParsingException: [gb] No query registered for [tweet]" } ]

}

==== Understanding Queries

Using the explain parameter has the added advantage of returning a human-readable description of the (valid) query, which can be useful for understanding exactly how your query has been interpreted by Elasticsearch:

[source,js]

GET /_validate/query?explain { "query": { "match" : { "tweet" : "really powerful" } }

}

// SENSE: 054_Query_DSL/80_Understanding_queries.json

An explanation is returned for each index ((("indices", "explanation for each index queried")))that we query, because each index can have different mappings and analyzers:

[source,js]

{ "valid" : true, "_shards" : { ... }, "explanations" : [ { "index" : "us", "valid" : true, "explanation" : "tweet:really tweet:powerful" }, { "index" : "gb", "valid" : true, "explanation" : "tweet:realli tweet:power" } ]

}

From the explanation, you can see how the match query for the query string really powerful has been rewritten as two single-term queries against the tweet field, one for each term.

Also, for the us index, the two terms are really and powerful, while for the gb index, the terms are realli and power. The reason for this is that we changed the tweet field in the gb index to use the english analyzer.