--- type: api title: Explain a document match result description: **All methods and paths for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-explain resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-explain products: - Elasticsearch --- # Explain a document match result Availability: ## Paths - `POST` (also `GET`) `/{index}/_explain/{id}` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth) #### Path Parameters - `index` (string IndexName) Index names that are used to limit the request. Only a single index name can be provided to this parameter. - `id` (string Id) The document identifier. ## Description 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` ## Query String 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 Operator · 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 Routing) 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 SourceConfigParam) `True` or `false` to return the `_source` field or not or a list of fields to return. One of: `boolean` or `Fields` - `_source_excludes` (union Fields) 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: `Field` or `Field[]` - `_source_includes` (union Fields) 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: `Field` or `Field[]` - `stored_fields` (union Fields) A comma-separated list of stored fields to return in the response. One of: `Field` or `Field[]` - `q` (string) The query in the Lucene query string syntax. ## Request Body `application/json` - `query` ({} QueryContainer) — optional Defines the search definition using the Query DSL. See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) ## Response `application/json` - `_index` (string IndexName) - `_id` (string Id) - `matched` (boolean) - `explanation` ({} ExplanationDetail) - `description` (string) - `details` ([] ExplanationDetail) — recursive Same fields as `explanation` - `value` (number) - `get` ({} InlineGet) - `fields` (map string to object) - `found` (boolean) - `_seq_no` (number SequenceNumber) - `_primary_term` (number) - `_routing` (string Routing) - `_source` (object) ## Code Examples #### Console ```console POST /my-index-000001/_explain/0 { "query" : { "match" : { "message" : "elasticsearch" } } } ``` #### JavaScript ```javascript const response = await client.explain({ index: "my-index-000001", id: 0, query: { match: { message: "elasticsearch", }, }, }); ``` #### Python ```python resp = client.explain( index="my-index-000001", id="0", query={ "match": { "message": "elasticsearch" } }, ) ``` #### curl ```curl 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 ```java client.explain(e -> e .id("0") .index("my-index-000001") .query(q -> q .match(m -> m .field("message") .query(FieldValue.of("elasticsearch")) ) ) ); ``` #### C# ```c# var response = await client .ExplainAsync(index: "my-index-000001", id: "0", d1 => d1 .Query(d2 => d2 .Match(d3 => d3 .Field(x => x.Message) .Query("elasticsearch") ) ) ); ``` #### PHP ```php $resp = $client->explain([ "index" => "my-index-000001", "id" => "0", "body" => [ "query" => [ "match" => [ "message" => "elasticsearch", ], ], ], ]); ``` #### Ruby ```ruby response = client.explain( index: "my-index-000001", id: "0", body: { "query": { "match": { "message": "elasticsearch" } } } ) ``` ## Response Examples #### Explain response example1 A successful response from `GET /my-index-000001/_explain/0`. ```json { "_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":[] } ] } ] } ] } } ```