167 lines
4.8 KiB
Plaintext
167 lines
4.8 KiB
Plaintext
[[search-explain]]
|
|
== Explain API
|
|
|
|
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.
|
|
|
|
Note that a single index must be provided to the `index` parameter.
|
|
|
|
[float]
|
|
=== Usage
|
|
|
|
Full query example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /twitter/_doc/0/_explain
|
|
{
|
|
"query" : {
|
|
"match" : { "message" : "elasticsearch" }
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:twitter]
|
|
|
|
This will yield the following result:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"_index":"twitter",
|
|
"_type":"_doc",
|
|
"_id":"0",
|
|
"matched":true,
|
|
"explanation":{
|
|
"value":1.6943597,
|
|
"description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
|
|
"details":[
|
|
{
|
|
"value":1.6943597,
|
|
"description":"score(freq=1.0), product of:",
|
|
"details":[
|
|
{
|
|
"value":2.2,
|
|
"description":"scaling factor, k1 + 1",
|
|
"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.5555555,
|
|
"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":[]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE
|
|
|
|
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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /twitter/_doc/0/_explain?q=message:search
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:twitter]
|
|
|
|
This will yield the same result as the previous request.
|
|
|
|
[float]
|
|
=== All parameters:
|
|
|
|
[horizontal]
|
|
`_source`::
|
|
|
|
Set to `true` to retrieve the `_source` of the document explained. You can also
|
|
retrieve part of the document by using `_source_includes` & `_source_excludes` (see <<get-source-filtering,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.
|
|
|
|
`analyzer`::
|
|
The analyzer name to be used when analyzing the query
|
|
string. Defaults to the default search analyzer.
|
|
|
|
`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.
|