[[search-explain]]
== Explain API

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.

Note that a single index must be provided to the `index` parameter.

[float]
=== Usage

Full query example:

[source,js]
--------------------------------------------------
GET /twitter/_doc/0/_explain
{
      "query" : {
        "match" : { "message" : "elasticsearch" }
      }
}
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

This will yield the following result:

[source,js]
--------------------------------------------------
{
   "_index":"twitter",
   "_type":"_doc",
   "_id":"0",
   "matched":true,
   "explanation":{
      "value":1.6943597,
      "description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
      "details":[
         {
            "value":1.6943597,
            "description":"score(freq=1.0), product of:",
            "details":[
               {
                  "value":2.2,
                  "description":"scaling factor, k1 + 1",
                  "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.5555555,
                  "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":[]
                     }
                  ]
               }
            ]
         }
      ]
   }
}
--------------------------------------------------
// TESTRESPONSE

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:

[source,js]
--------------------------------------------------
GET /twitter/_doc/0/_explain?q=message:search
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

This will yield the same result as the previous request.

[float]
=== All parameters:

[horizontal]
`_source`::

    Set to `true` to retrieve the `_source` of the document explained. You can also
    retrieve part of the document by using `_source_includes` & `_source_excludes` (see <<get-source-filtering,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.

`analyzer`::
    The analyzer name to be used when analyzing the query
    string. Defaults to the default search analyzer.

`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.