Explain APIedit
Returns information about why a specific document matches (or doesn’t match) a query.
GET /twitter/_explain/0
{
"query" : {
"match" : { "message" : "elasticsearch" }
}
}
Requestedit
GET /<index>/_explain/<id>
POST /<index>/_explain/<id>
Descriptionedit
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.
Path parametersedit
-
<id> - (Required, integer) Defines the document ID.
-
<index> -
(Required, string) Index names used to limit the request.
Only a single index name can be provided to this parameter.
Query parametersedit
-
analyzer - (Optional, string) Analyzer to use for the query string.
-
analyze_wildcard -
(Optional, boolean) If
true, wildcard and prefix queries are analyzed. Defaults tofalse. -
default_operator -
(Optional, string) The default operator for query string query: AND or OR.
Defaults to
OR. -
df - (Optional, string) Field to use as default where no field prefix is given in the query string.
-
lenient -
(Optional, boolean) If
true, format-based query failures (such as providing text to a numeric field) will be ignored. Defaults tofalse. -
preference - (Optional, string) Specifies the node or shard the operation should be performed on. Random by default.
-
q - (Optional, string) Query in the Lucene query string syntax.
-
stored_fields - (Optional, string) A comma-separated list of stored fields to return in the response.
-
routing - (Optional, string) Custom routing value used to route operations to a specific shard.
-
_source -
(Optional, string) True or false to return the
_sourcefield or not, or a list of fields to return. -
_source_excludes -
(Optional, 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_includesquery parameter.If the
_sourceparameter isfalse, this parameter is ignored. -
_source_includes -
(Optional, 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_excludesquery parameter.If the
_sourceparameter isfalse, this parameter is ignored.
Request bodyedit
-
query - (Optional, query object) Defines the search definition using the Query DSL.
Examplesedit
GET /twitter/_explain/0
{
"query" : {
"match" : { "message" : "elasticsearch" }
}
}
The API returns the following response:
{
"_index":"twitter",
"_type":"_doc",
"_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":[]
}
]
}
]
}
]
}
}
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/_explain/0?q=message:search
The API returns the same result as the previous request.