IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› ›

Explain API

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Explain API

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.

The index and type parameters expect a single index and a single type respectively.

Usage

edit

Full query example:

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

This will yield the following result:

{
   "_index": "twitter",
   "_type": "tweet",
   "_id": "0",
   "matched": true,
   "explanation": {
      "value": 1.55077,
      "description": "sum of:",
      "details": [
         {
            "value": 1.55077,
            "description": "weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
            "details": [
               {
                  "value": 1.55077,
                  "description": "score(doc=0,freq=1.0 = termFreq=1.0\n), product of:",
                  "details": [
                     {
                        "value": 1.3862944,
                        "description": "idf, computed as log(1 + (docCount - docFreq + 0.5) / (docFreq + 0.5)) from:",
                        "details": [
                           {
                              "value": 1.0,
                              "description": "docFreq",
                              "details": []
                           },
                           {
                              "value": 5.0,
                              "description": "docCount",
                              "details": []
                           }
                        ]
                     },
                     {
                        "value": 1.1186441,
                        "description": "tfNorm, computed as (freq * (k1 + 1)) / (freq + k1 * (1 - b + b * fieldLength / avgFieldLength)) from:",
                        "details": [
                           {
                              "value": 1.0,
                              "description": "termFreq=1.0",
                              "details": []
                           },
                           {
                              "value": 1.2,
                              "description": "parameter k1",
                              "details": []
                           },
                           {
                              "value": 0.75,
                              "description": "parameter b",
                              "details": []
                           },
                           {
                              "value": 5.4,
                              "description": "avgFieldLength",
                              "details": []
                           },
                           {
                              "value": 4.0,
                              "description": "fieldLength",
                              "details": []
                           }
                        ]
                     }
                  ]
               }
            ]
         },
         {
            "value": 0.0,
            "description": "match on required clause, product of:",
            "details": [
               {
                  "value": 0.0,
                  "description": "# clause",
                  "details": []
               },
               {
                  "value": 1.0,
                  "description": "*:*, product of:",
                  "details": [
                     {
                        "value": 1.0,
                        "description": "boost",
                        "details": []
                     },
                     {
                        "value": 1.0,
                        "description": "queryNorm",
                        "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/tweet/0/_explain?q=message:search

This will yield the same result as the previous request.

All parameters:

edit

`_source`	Set to `true` to retrieve the `_source` of the document explained. You can also retrieve part of the document by using `_source_include` & `_source_exclude` (see Get API for more details)
`stored_fields`	Allows to control which stored fields to return as part of the document explained.
`routing`	Controls the routing in the case the routing was used during indexing.
`parent`	Same effect as setting the routing parameter.
`preference`	Controls on which shard the explain is executed.
`source`	Allows the data of the request to be put in the query string of the url.
`q`	The query string (maps to the query_string query).
`df`	The default field to use when no field prefix is defined within the query. Defaults to _all field.
`analyzer`	The analyzer name to be used when analyzing the query string. Defaults to the analyzer of the _all field.
`analyze_wildcard`	Should wildcard and prefix queries be analyzed or not. Defaults to false.
`lenient`	If set to true will cause format based failures (like providing text to a numeric field) to be ignored. Defaults to false.
`default_operator`	The default operator to be used, can be AND or OR. Defaults to OR.

« Validate API Profile API »