Explain a document match result Generally available

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

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
GET /{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":[] } ] } ] } ] } }