Explain a document match result Generally available

POST /{index}/_explain/{id}
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /{index}/_explain/{id}

POST /{index}/_explain/{id}

Get information about why a specific document matches, or doesn't match, a query. It computes a score explanation for a query and a specific document.

Required authorization

  • Index privileges: read

Path parameters

  • index string Required

    Index names that are used to limit the request. Only a single index name can be provided to this parameter.

  • id string Required

    The document identifier.

Query parameters

  • analyzer string

    The analyzer to use for the query string. This parameter can be used only when the q query string parameter is specified.

  • analyze_wildcard boolean

    If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.

  • default_operator string

    The default operator for query string query: AND or OR. This parameter can be used only when the q query string parameter is specified.

    Values are and, AND, or, or OR.

  • df string

    The field to use as default where no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.

  • lenient boolean

    If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the q query string parameter is specified.

  • preference string

    The node or shard the operation should be performed on. It is random by default.

  • routing string

    A custom value used to route operations to a specific shard.

  • _source boolean | string | array[string]

    True or false to return the _source field or not or a list of fields to return.

  • _source_excludes string | array[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 string | array[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.

  • stored_fields string | array[string]

    A comma-separated list of stored fields to return in the response.

  • q string

    The query in the Lucene query string syntax.

application/json

Body

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _index string Required
    • _id string Required
    • matched boolean Required
    • explanation object
      Hide explanation attributes Show explanation attributes object
      • description string Required
      • details array[object]
      • value number Required
    • get object
      Hide get attributes Show get attributes object
      • fields object
        Hide fields attribute Show fields attribute object
        • * object Additional properties
      • found boolean Required
      • _seq_no number
      • _primary_term number
      • _routing string
      • _source object
POST /{index}/_explain/{id} 
GET /my-index-000001/_explain/0
{
  "query" : {
    "match" : { "message" : "elasticsearch" }
  }
}
resp = client.explain(
    index="my-index-000001",
    id="0",
    query={
        "match": {
            "message": "elasticsearch"
        }
    },
)
const response = await client.explain({
  index: "my-index-000001",
  id: 0,
  query: {
    match: {
      message: "elasticsearch",
    },
  },
});
response = client.explain(
  index: "my-index-000001",
  id: "0",
  body: {
    "query": {
      "match": {
        "message": "elasticsearch"
      }
    }
  }
)
$resp = $client->explain([
    "index" => "my-index-000001",
    "id" => "0",
    "body" => [
        "query" => [
            "match" => [
                "message" => "elasticsearch",
            ],
        ],
    ],
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"match":{"message":"elasticsearch"}}}' "$ELASTICSEARCH_URL/my-index-000001/_explain/0"
Request example
Run `GET /my-index-000001/_explain/0` with the request body. Alternatively, run `GET /my-index-000001/_explain/0?q=message:elasticsearch` 
{
  "query" : {
    "match" : { "message" : "elasticsearch" }
  }
}
Response examples (200)
A successful response from `GET /my-index-000001/_explain/0`. 
{
  "_index":"my-index-000001",
  "_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":[]
                    }
                  ]
              }
            ]
        }
      ]
  }
}