liveBook · Manning

Explain flag

As explained in Elasticsearch in Action, Second Edition

An Elasticsearch search request option that causes the response to include details about how a document's relevance score was derived.

Use the explain flag when a movie search returns relevance scores and you need to understand why one document ranked above another. Set "explain" to true in the search request body; Elasticsearch then returns the score calculation details. section 8.8.3 section 8.6.1

Listing 8.20 Asking the engine to explain the score
GET movies/_search
{
  "explain": true, 
  "_source": false, 
  "query": {
    "match": {
      "title": "Lord"
    }
  }
}

This focused request searches movie titles for “Lord” and asks Elasticsearch to explain each returned score; "_source": false keeps document fields out of the response. section 8.8.3

The response breaks the relevance score into components and describes how each was evaluated. The calculation includes inverse document frequency (IDF), term frequency (TF), and the boost factor, with details for the formulas’ variables. section 8.8.3

Investigating a missing movie match

Use the _explain endpoint for one document when the question concerns a specific match. A request for document 14 with a title match on “Lord” returns an explanation; when no term matches, the response reports "matched": false, a value of 0.0, and "no matching term". section 8.8.3

How Elasticsearch in Action, Second Edition covers it

How deep it goes
Explains score components, formulas, and variables rather than merely displaying the final relevance value.
Examples
Uses movie-title searches for “Lord,” “Godfather,” “Knight,” and “Shawshank,” including a missing-match response for document 14.
What it assumes
Uses a search query, a relevance score, and a document identifier as the basic context for investigation.
What you can do after
Diagnose/debug with it by inspecting how Elasticsearch calculated a score or why a queried document did not match.
How it connects
Connects search queries with relevance scores, term frequency, inverse document frequency, boost factors, and the _explain API.
Cover of Elasticsearch in Action, Second Edition
liveBookmanning.com
Read Elasticsearch in Action, Second Edition on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Elasticsearch in Action, Second Edition. The section links point to the parts of the book it draws on.