Explain a document match result

POST also GET /{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

Authentication

Authorization: <value>

Elasticsearch APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

For more information about where to find API keys for the Elasticsearch endpoint (${ES_URL}) for a project, go to Get started with Elasticsearch Serverless.

Path parameters

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 · default: false: If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.
default_operator enum · default: or: 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: and AND 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 · default: false: 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 union oneOf: A custom value used to route operations to a specific shard. Not allowed when index.slice.enabled is true for the target index; use _slice instead.; One of: string[] or string
_source union oneOf: True or false to return the _source field or not or a list of fields to return.; One of: boolean or string
_source_excludes union oneOf: 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.; One of: string[] or string
_source_includes union oneOf: 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.; One of: string[] or string
stored_fields union oneOf: A comma-separated list of stored fields to return in the response.; One of: string[] or string
q string: The query in the Lucene query string syntax.

Request body

Response

application/json

Examples

Request Console 1 / 8 languages

Run POST /my-index-000001/_explain/0 with the request body. Alternatively, run GET /my-index-000001/_explain/0?q=message:elasticsearch

Console Kibana Dev Tools

POST /my-index-000001/_explain/0
{
  "query" : {
    "match" : { "message" : "elasticsearch" }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.explain({
  index: "my-index-000001",
  id: 0,
  query: {
    match: {
      message: "elasticsearch",
    },
  },
});

Python Elasticsearch Python Client

resp = client.explain(
    index="my-index-000001",
    id="0",
    query={
        "match": {
            "message": "elasticsearch"
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/my-index-000001/_explain/0" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "message": "elasticsearch"
      }
    }
  }'

Java Elasticsearch Java Client

client.explain(e -> e
    .id("0")
    .index("my-index-000001")
    .query(q -> q
        .match(m -> m
            .field("message")
            .query(FieldValue.of("elasticsearch"))
        )
    )
);

C# Elasticsearch .NET Client

var response = await client
    .ExplainAsync<MyDocument>(index: "my-index-000001", id: "0", d1 => d1
        .Query(d2 => d2
            .Match(d3 => d3
                .Field(x => x.Message)
                .Query("elasticsearch")
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->explain([
    "index" => "my-index-000001",
    "id" => "0",
    "body" => [
        "query" => [
            "match" => [
                "message" => "elasticsearch",
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.explain(
  index: "my-index-000001",
  id: "0",
  body: {
    "query": {
      "match": {
        "message": "elasticsearch"
      }
    }
  }
)

Response

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

Required authorization

Authentication

Path parameters

Query parameters

Request body { }

Response

Request body