Explain API

edit

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

GET /twitter/_explain/0
{
      "query" : {
        "match" : { "message" : "elasticsearch" }
      }
}

Request

edit

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

Description

edit

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

edit
<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

edit
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

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

Examples

edit
GET /twitter/_explain/0
{
      "query" : {
        "match" : { "message" : "elasticsearch" }
      }
}

The API returns the following response:

{
   "_index":"twitter",
   "_type":"_doc",
   "_id":"0",
   "matched":true,
   "explanation":{
      "value":1.6943598,
      "description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
      "details":[
         {
            "value":1.6943598,
            "description":"score(freq=1.0), computed as boost * idf * tf from:",
            "details":[
               {
                  "value":2.2,
                  "description":"boost",
                  "details":[]
               },
               {
                  "value":1.3862944,
                  "description":"idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
                  "details":[
                     {
                        "value":1,
                        "description":"n, number of documents containing term",
                        "details":[]
                     },
                     {
                        "value":5,
                        "description":"N, total number of documents with field",
                        "details":[]
                     }
                  ]
               },
               {
                  "value":0.5555556,
                  "description":"tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
                  "details":[
                     {
                        "value":1.0,
                        "description":"freq, occurrences of term within document",
                        "details":[]
                     },
                     {
                        "value":1.2,
                        "description":"k1, term saturation parameter",
                        "details":[]
                     },
                     {
                        "value":0.75,
                        "description":"b, length normalization parameter",
                        "details":[]
                     },
                     {
                        "value":3.0,
                        "description":"dl, length of field",
                        "details":[]
                     },
                     {
                        "value":5.4,
                        "description":"avgdl, average length of field",
                        "details":[]
                     }
                  ]
               }
            ]
         }
      ]
   }
}

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:

GET /twitter/_explain/0?q=message:search

The API returns the same result as the previous request.