150 lines
4.2 KiB
Plaintext
150 lines
4.2 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" : "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" : [ ] }
|
|
]
|
|
} ]
|
|
} ]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// 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.
|
|
|
|
`lowercase_expanded_terms`::
|
|
Should terms be automatically lowercased
|
|
or not. Defaults to true.
|
|
|
|
`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.
|