mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-11 15:35:05 +00:00
7ad71f906a
The main benefit of the upgrade for users is the search optimization for top scored documents when the total hit count is not needed. However this optimization is not activated in this change, there is another issue opened to discuss how it should be integrated smoothly. Some comments about the change: * Tests that can produce negative scores have been adapted but we need to forbid them completely: #33309 Closes #32899
168 lines
4.8 KiB
Plaintext
168 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.
|
|
|
|
The `index` and `type` parameters expect a single index and a single
|
|
type respectively.
|
|
|
|
[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_include` & `_source_exclude` (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.
|