163 lines
4.6 KiB
Plaintext
163 lines
4.6 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/tweet/0/_explain
|
|
{
|
|
"query" : {
|
|
"match" : { "message" : "elasticsearch" }
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:twitter]
|
|
|
|
This will yield the following result:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"_index": "twitter",
|
|
"_type": "tweet",
|
|
"_id": "0",
|
|
"matched": true,
|
|
"explanation": {
|
|
"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, computed as log(1 + (docCount - docFreq + 0.5) / (docFreq + 0.5)) from:",
|
|
"details": [
|
|
{
|
|
"value": 1.0,
|
|
"description": "docFreq",
|
|
"details": []
|
|
},
|
|
{
|
|
"value": 5.0,
|
|
"description": "docCount",
|
|
"details": []
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"value": 1.1186441,
|
|
"description": "tfNorm, computed as (freq * (k1 + 1)) / (freq + k1 * (1 - b + b * fieldLength / avgFieldLength)) 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": []
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// 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/tweet/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. 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.
|