201 lines
5.6 KiB
Plaintext
201 lines
5.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
|
|
|
|
Imagine having indexed the following document:
|
|
|
|
[source,js]
|
|
----------------------------------------
|
|
PUT /twitter/tweet/1?refresh
|
|
{
|
|
"user": "kimchy",
|
|
"message": "search"
|
|
}
|
|
---------------------------------------
|
|
// CONSOLE
|
|
// TESTSETUP
|
|
|
|
|
|
Full query example:
|
|
|
|
[source,js]
|
|
--------------------------------------
|
|
GET /twitter/tweet/1/_explain
|
|
{
|
|
"query" : {
|
|
"term" : { "message" : "search" }
|
|
}
|
|
}
|
|
--------------------------------------
|
|
// CONSOLE
|
|
|
|
This will yield the following result:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"_index": "twitter",
|
|
"_type": "tweet",
|
|
"_id": "1",
|
|
"matched": true,
|
|
"explanation": {
|
|
"value": 0.2876821,
|
|
"description": "sum of:",
|
|
"details": [
|
|
{
|
|
"value": 0.2876821,
|
|
"description": "weight(message:search in 0) [PerFieldSimilarity], result of:",
|
|
"details": [
|
|
{
|
|
"value": 0.2876821,
|
|
"description": "score(doc=0,freq=1.0 = termFreq=1.0\n), product of:",
|
|
"details": [
|
|
{
|
|
"value": 0.2876821,
|
|
"description": "idf(docFreq=1, docCount=1)",
|
|
"details": [ ]
|
|
},
|
|
{
|
|
"value": 1.0,
|
|
"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" : 1.0,
|
|
"description" : "avgFieldLength",
|
|
"details" : [ ]
|
|
},
|
|
{
|
|
"value" : 1.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" : "_type:tweet, 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/1/_explain?q=message:search
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
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)
|
|
|
|
`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.
|