OpenSearch/docs/reference/search/explain.asciidoc

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

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

[float]
=== Usage

Imagine having indexed the following document:

[source,js]
----------------------------------------
PUT /twitter/tweet/1?refresh
{
    "user": "kimchy",
    "message": "search"
}
---------------------------------------
// CONSOLE
// TESTSETUP


Full query example:

[source,js]
--------------------------------------
GET /twitter/tweet/1/_explain
{
    "query" : {
        "term" : { "message" : "search" }
    }
}
--------------------------------------
// CONSOLE

This will yield the following result:

[source,js]
--------------------------------------------------
{
   "_index": "twitter",
   "_type": "tweet",
   "_id": "1",
   "matched": true,
   "explanation": {
      "value": 0.2876821,
      "description": "sum of:",
      "details": [
         {
            "value": 0.2876821,
            "description": "weight(message:search in 0) [PerFieldSimilarity], result of:",
            "details": [
               {
                  "value": 0.2876821,
                  "description": "score(doc=0,freq=1.0 = termFreq=1.0\n), product of:",
                  "details": [
                     {
                        "value": 0.2876821,
                        "description": "idf(docFreq=1, docCount=1)",
                        "details": [ ]
                     },
                     {
                        "value": 1.0,
                        "description": "tfNorm, computed 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" : 1.0,
                           "description" : "avgFieldLength",
                           "details" : [ ]
                         },
                         {
                           "value" : 1.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" : "_type:tweet, product of:",
                   "details" : [
                     {
                       "value" : 1.0,
                       "description" : "boost",
                       "details" : [ ]
                     },
                     {
                       "value" : 1.0,
                       "description" : "queryNorm",
                       "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/tweet/1/_explain?q=message:search
--------------------------------------------------
// CONSOLE

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_include` & `_source_exclude` (see <<get-source-filtering,Get API>> for more details)

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

`lowercase_expanded_terms`::
    Should terms be automatically lowercased
    or not. Defaults to true.

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