When executing searches, it's very common to have documents that don't match the query as expected. To easily debug these scenarios, Elasticsearch provides the explain query call.
You will need an up-and-running Elasticsearch installation as used in the Downloading and installing Elasticsearch recipe in Chapter 2, Downloading and Setup.
To execute curl via a command line, you need to install curl for your operating system.
To correctly execute the following commands, you will need an index populated with the chapter_05/populate_query.sh script available in the online code.
The steps required to execute the explain query call are as follows:
- From the command line, we will execute an explain query against a document as follows:
curl -XGET 'http://127.0.0.1:9200/test-index/test- type/1/_explain?pretty' -d '{ "query": { "term": { "uuid": "11111" } } }' - The result returned by Elasticsearch, if everything works, should be as follows:
{ "_index" : "test-index", "_type" : "test-type", "_id" : "1", "matched" : true, "explanation" : { "value" : 0.2876821, "description" : "sum of:", "details" : [ { "value" : 0.2876821, "description" : "weight(uuid:11111 in 0) [PerFieldSimilarity], result of:", "details" : [ { "value" : 0.2876821, "description" : "score(doc=0,freq=1.0 = termFreq=1.0 ), product of:", "details" : [ { "value" : 0.2876821, "description" : "idf(docFreq=1, docCount=1)", "details" : [ ] }, .... } ] }, { "value" : 0.0, "description" : "match on required clause,product of:", "details" : [ { "value" : 0.0, "description" : "# clause", "details" : [ ] }, { "value" : 1.0, "description" : "_type:test-type, product of:", "details" : [....] } ] } ] } }
The important parts of the result are the following:
matched: Whether the documents match or not in the queryexplanation: This section is composed of objects made of:value: A double score of that query sectiondescription: A string representation of the matching token (in case of wildcards or multi-terms, it can give information about the matched token)details: An optional list of explanation objects
In this case, the details show two query parts:
- The first is the query that we have provided.
- The second one is automatically added by Elasticsearch to filter the document type (in Elasticsearch, there is no physical separation of document types, they are all stored in the same index and are filtered out at the time of the query). The score for this filter query is 0.0 to prevent changing the relevance.
The explain call is a view of how Lucene computes the results. In the description section of the explain object, there are the Lucene representations of that part of the query.
A user doesn't need to be a Lucene expert to understand the explain descriptions, but they provide a highlight of how the query is executed and the terms are matched.