New

The executive guide to generative AI

Read more
About usPartnersSupport|Login

WARNING: Version 5.1 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Validate API Profile API »
Elastic Docs ›Elasticsearch Guide [5.1] ›Search APIs

Explain API

edit

Explain API

edit

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.

Usage

edit

Full query example:

GET /twitter/tweet/0/_explain
{
      "query" : {
        "match" : { "message" : "elasticsearch" }
      }
}
Copy as curlTry in Elastic 

This will yield the following result:

{
  "_index" : "twitter",
  "_type" : "tweet",
  "_id" : "0",
  "matched" : true,
  "explanation" : {
    "value" : 1.55077,
    "description" : "sum of:",
    "details" : [ {
      "value" : 1.55077,
      "description" : "weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
      "details" : [ {
        "value" : 1.55077,
        "description" : "score(doc=0,freq=1.0 = termFreq=1.0\n), product of:",
        "details" : [ {
          "value" : 1.3862944,
          "description" : "idf(docFreq=1, docCount=5)",
          "details" : [ ]
        }, {
          "value" : 1.1186441,
          "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" : 5.4, "description" : "avgFieldLength", "details" : [ ] },
            { "value" : 4.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" : "*:*, product of:",
        "details" : [
          { "value" : 1.0, "description" : "boost", "details" : [ ] },
          { "value" : 1.0, "description" : "queryNorm", "details" : [ ] }
        ]
      } ]
    } ]
  }
}

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:

GET /twitter/tweet/0/_explain?q=message:search
Copy as curlTry in Elastic 

This will yield the same result as the previous request.

All parameters:

edit

_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 API for more details)

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

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.

« Validate API Profile API »

On this page

Was this helpful?
Feedback