[[search-explain]]
=== Explain API

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

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


[[sample-api-request]]
==== {api-request-title}

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

[[sample-api-desc]]
==== {api-description-title}

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.


[[sample-api-path-params]]
==== {api-path-parms-title}

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


[[sample-api-query-params]]
==== {api-query-parms-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer]

include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]

include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator]

include::{docdir}/rest-api/common-parms.asciidoc[tag=df]

include::{docdir}/rest-api/common-parms.asciidoc[tag=lenient]

include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]

include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q]

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

include::{docdir}/rest-api/common-parms.asciidoc[tag=index-routing]

include::{docdir}/rest-api/common-parms.asciidoc[tag=source]

include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]

include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]


[[sample-api-request-body]]
==== {api-request-body-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=query]


[[sample-api-example]]
==== {api-examples-title}

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


The API returns the following response:

[source,console-result]
--------------------------------------------------
{
   "_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":"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.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":[]
                     }
                  ]
               }
            ]
         }
      ]
   }
}
--------------------------------------------------


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,console]
--------------------------------------------------
GET /twitter/_explain/0?q=message:search
--------------------------------------------------
// TEST[setup:twitter]


The API returns the same result as the previous request.