Explain API

Returns information about why a specific document matches (or doesn’t match) a query.

  1. GET /my-index-000001/_explain/0
  2. {
  3.   "query" : {
  4.     "match" : { "message" : "elasticsearch" }
  5.   }
  6. }

Request

GET /<index>/_explain/<id> POST /<index>/_explain/<id>

Description

The explain API computes a score explanation for a query and a specific document. This can give useful feedback whether a document matches or didn’t match a specific query.

Path parameters

<id>

(Required, integer) Defines the document ID.

<index>

(Required, string) Index names used to limit the request.

Only a single index name can be provided to this parameter.

Query parameters

analyzer

(Optional, string) Analyzer to use for the query string.

analyze_wildcard

(Optional, boolean) If true, wildcard and prefix queries are analyzed. Defaults to false.

default_operator

(Optional, string) The default operator for query string query: AND or OR. Defaults to OR.

df

(Optional, string) Field to use as default where no field prefix is given in the query string.

lenient

(Optional, boolean) If true, format-based query failures (such as providing text to a numeric field) will be ignored. Defaults to false.

preference

(Optional, string) Specifies the node or shard the operation should be performed on. Random by default.

q

(Optional, string) Query in the Lucene query string syntax.

stored_fields

(Optional, string) A comma-separated list of stored fields to return in the response.

routing

(Optional, string) Custom routing value used to route operations to a specific shard.

_source

(Optional, string) True or false to return the _source field or not, or a list of fields to return.

_source_excludes

(Optional, string) A comma-separated list of source fields to exclude from the response.

You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.

If the _source parameter is false, this parameter is ignored.

_source_includes

(Optional, string) A comma-separated list of source fields to include in the response.

If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter.

If the _source parameter is false, this parameter is ignored.

Request body

query

(Optional, query object) Defines the search definition using the Query DSL.

Examples

  1. GET /my-index-000001/_explain/0
  2. {
  3.   "query" : {
  4.     "match" : { "message" : "elasticsearch" }
  5.   }
  6. }

The API returns the following response:

  1. {
  2.    "_index":"my-index-000001",
  3.    "_type":"_doc",
  4.    "_id":"0",
  5.    "matched":true,
  6.    "explanation":{
  7.       "value":1.6943598,
  8.       "description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
  9.       "details":[
  10.          {
  11.             "value":1.6943598,
  12.             "description":"score(freq=1.0), computed as boost * idf * tf from:",
  13.             "details":[
  14.                {
  15.                   "value":2.2,
  16.                   "description":"boost",
  17.                   "details":[]
  18.                },
  19.                {
  20.                   "value":1.3862944,
  21.                   "description":"idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
  22.                   "details":[
  23.                      {
  24.                         "value":1,
  25.                         "description":"n, number of documents containing term",
  26.                         "details":[]
  27.                      },
  28.                      {
  29.                         "value":5,
  30.                         "description":"N, total number of documents with field",
  31.                         "details":[]
  32.                      }
  33.                   ]
  34.                },
  35.                {
  36.                   "value":0.5555556,
  37.                   "description":"tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
  38.                   "details":[
  39.                      {
  40.                         "value":1.0,
  41.                         "description":"freq, occurrences of term within document",
  42.                         "details":[]
  43.                      },
  44.                      {
  45.                         "value":1.2,
  46.                         "description":"k1, term saturation parameter",
  47.                         "details":[]
  48.                      },
  49.                      {
  50.                         "value":0.75,
  51.                         "description":"b, length normalization parameter",
  52.                         "details":[]
  53.                      },
  54.                      {
  55.                         "value":3.0,
  56.                         "description":"dl, length of field",
  57.                         "details":[]
  58.                      },
  59.                      {
  60.                         "value":5.4,
  61.                         "description":"avgdl, average length of field",
  62.                         "details":[]
  63.                      }
  64.                   ]
  65.                }
  66.             ]
  67.          }
  68.       ]
  69.    }
  70. }

There is also a simpler way of specifying the query via the q parameter. The specified q parameter value is then parsed as if the query_string query was used. Example usage of the q parameter in the explain API:

  1. GET /my-index-000001/_explain/0?q=message:search

The API returns the same result as the previous request.