mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-28 17:34:17 -04:00
33a71e3289
* Remove `es-test-dir` book-scoped variable * Remove `plugins-examples-dir` book-scoped variable * Remove `:dependencies-dir:` and `:xes-repo-dir:` book-scoped variables - In `index.asciidoc`, two variables (`:dependencies-dir:` and `:xes-repo-dir:`) were removed. - In `sql/index.asciidoc`, the `:sql-tests:` path was updated to fuller path - In `esql/index.asciidoc`, the `:esql-tests:` path was updated idem * Replace `es-repo-dir` with `es-ref-dir` * Move `:include-xpack: true` to few files that use it, remove from index.asciidoc
198 lines
5.5 KiB
Text
198 lines
5.5 KiB
Text
[[search-explain]]
|
|
=== Explain API
|
|
++++
|
|
<titleabbrev>Explain</titleabbrev>
|
|
++++
|
|
|
|
Returns information about why a specific document matches (or doesn't match) a
|
|
query.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /my-index-000001/_explain/0
|
|
{
|
|
"query" : {
|
|
"match" : { "message" : "elasticsearch" }
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[setup:messages]
|
|
|
|
|
|
[[search-explain-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /<index>/_explain/<id>`
|
|
|
|
`POST /<index>/_explain/<id>`
|
|
|
|
[[search-explain-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the `read`
|
|
<<privileges-list-indices,index privilege>> for the target index.
|
|
|
|
[[search-explain-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
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.
|
|
|
|
|
|
[[search-explain-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<id>`::
|
|
(Required, integer) Defines the document ID.
|
|
|
|
`<index>`::
|
|
+
|
|
--
|
|
(Required, string)
|
|
Index names used to limit the request.
|
|
|
|
Only a single index name can be provided to this parameter.
|
|
--
|
|
|
|
|
|
[[search-explain-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=analyzer]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=default_operator]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=df]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=lenient]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=preference]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=search-q]
|
|
|
|
`stored_fields`::
|
|
(Optional, string) A comma-separated list of stored fields to return in the
|
|
response.
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=routing]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=source]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=source_excludes]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=source_includes]
|
|
|
|
|
|
[[search-explain-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=query]
|
|
|
|
|
|
[[search-explain-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /my-index-000001/_explain/0
|
|
{
|
|
"query" : {
|
|
"match" : { "message" : "elasticsearch" }
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[setup:messages]
|
|
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"_index":"my-index-000001",
|
|
"_id":"0",
|
|
"matched":true,
|
|
"explanation":{
|
|
"value":1.6943598,
|
|
"description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
|
|
"details":[
|
|
{
|
|
"value":1.6943598,
|
|
"description":"score(freq=1.0), computed as boost * idf * tf from:",
|
|
"details":[
|
|
{
|
|
"value":2.2,
|
|
"description":"boost",
|
|
"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.5555556,
|
|
"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":[]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
|
|
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,console]
|
|
--------------------------------------------------
|
|
GET /my-index-000001/_explain/0?q=message:search
|
|
--------------------------------------------------
|
|
// TEST[setup:messages]
|
|
|
|
|
|
The API returns the same result as the previous request.
|