From 0a04365cba152253271a84a5e8abd641f6f50887 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 30 Sep 2019 13:54:45 -0400 Subject: [PATCH] [7.3] [DOCS] Add response body parms to search API docs (#47042) (#47307) --- docs/reference/search/search.asciidoc | 221 +++++++++++++++++++++++--- 1 file changed, 197 insertions(+), 24 deletions(-) diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc index 9e396485e2fa7..4c5f8050c73c4 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -4,9 +4,9 @@ Returns search hits that match the query defined in the request. [source,js] --------------------------------------------------- -GET /twitter/_search?q=user:kimchy --------------------------------------------------- +---- +GET /twitter/_search?q=tag:wow +---- // CONSOLE // TEST[setup:twitter] @@ -14,9 +14,13 @@ GET /twitter/_search?q=user:kimchy [[search-search-api-request]] ==== {api-request-title} -`GET //_search` + +`GET //_search` + +`POST //_search` + +`GET /_search` -`GET /all/_search` +`POST /_search` [[search-search-api-desc]] @@ -215,38 +219,207 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=timeout] <>. +[[search-api-response-body]] +==== {api-response-body-title} + +`took`:: ++ +-- +(Integer) +Milliseconds it took {es} to execute the request. + +This value is calculated by measuring the time elapsed +between receipt of a request on the coordinating node +and the time at which the coordinating node is ready to send the response. + +Took time includes: + +* Communication time between the coordinating node and data nodes +* Time the request spends in the `search` <>, + queued for execution +* Actual execution time + +Took time does *not* include: + +* Time needed to send the request to {es} +* Time needed to serialize the JSON response +* Time needed to send the response to a client +-- + + +`timed_out`:: ++ +-- +(Boolean) +If `true`, +the request timed out before completion; +returned results may be partial or empty. +-- + +`_shards`:: ++ +-- +(Object) +Object containing a count of shards used for the request. +Returned parameters include: + +`total`:: +(Integer) +Total number of shards that require querying, +including unallocated shards. + +`successful`:: +(Integer) +Number of shards that executed the request successfully. + +`skipped`:: +(Integer) +Number of shards that skipped the request because a lightweight check +helped realize that no documents could possibly match on this shard. This +typically happens when a search request includes a range filter and the +shard only has values that fall outside of that range. + +`failed`:: +(Integer) +Number of shards that failed to execute the request. Note that shards +that are not allocated will be considered neither successful nor failed. +Having `failed+successful` less than `total` is thus an indication that +some of the shards were not allocated. + +-- + +`hits`:: ++ +-- +(Object) +Contains returned documents and metadata. +Returned parameters include: + +`total`:: +(Object) +Metadata about the number of returned documents. +Returned parameters include: ++ +* `value`: Total number of returned documents. +* `relation`: Indicates whether the number of documents returned. +Returned values are: +** `eq`: Accurate +** `gte`: Lower bound, including returned documents + +`max_score`:: +(Float) +Highest returned document `_score`. ++ +The `_score` parameter is a floating point number +used to determine the relevance of the returned document. ++ +This parameter value is `null` for requests +that do not sort by `_score`. + +`hits`:: +(Array of objects) +Array of returned document objects. +Returned parameters include: ++ +* `_index`: Name of the index containing the returned document. +* `_type`: Document type. + deprecated:[7.0.0, Types are deprecated and are in the process of being removed. See <>.] +* `_id`: Unique identifier for the returned document. + This ID is only unique within the returned index. +* `_score`: Floating point number + used to determine the relevance of the returned document. +* `_source`: Object containing the original JSON body + passed for the document at index time. +-- + + [[search-search-api-example]] ==== {api-examples-title} -["float",id="search-multi-index"] -===== Multi-Index - -All search APIs can be applied across multiple indices with support for -the <>. For -example, we can search on all documents within the twitter index: +[[search-api-specific-ex]] +===== Search a specific index [source,js] --------------------------------------------------- +---- GET /twitter/_search?q=user:kimchy --------------------------------------------------- +---- // CONSOLE -// TEST[setup:twitter] +// TEST[continued] + +The API returns the following response: -We can also search all documents with a certain tag across several indices -(for example, when there is one index per user): +[source,js] +---- +{ + "took" : 5, + "timed_out" : false, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 1, + "relation" : "eq" + }, + "max_score" : 1.3862944, + "hits" : [ + { + "_index" : "twitter", + "_type" : "_doc", + "_id" : "0", + "_score" : 1.3862944, + "_source" : { + "date" : "2009-11-15T14:12:12", + "likes" : 0, + "message" : "trying out Elasticsearch", + "user" : "kimchy" + } + } + ] + } +} +---- +// TESTRESPONSE[s/"took" : 5/"took": $body.took/] + +[[search-multi-index]] +===== Search several indices [source,js] --------------------------------------------------- -GET /kimchy,elasticsearch/_search?q=tag:wow --------------------------------------------------- +---- +GET /kimchy,elasticsearch/_search?q=user:kimchy +---- // CONSOLE // TEST[s/^/PUT kimchy\nPUT elasticsearch\n/] -Or we can search across all available indices using `_all`: +[[search-api-all-ex]] +===== Search all indices + +To search all indices in a cluster, +omit the `` parameter. [source,js] ---------------------------------------------------- -GET /_all/_search?q=tag:wow ---------------------------------------------------- +---- +GET /_search?q=user:kimchy +---- // CONSOLE -// TEST[setup:twitter] +// TEST[continued] + +Alternatively, +you can use the `_all` or `*` value in the `` parameter. + +[source,js] +---- +GET /_all/_search?q=user:kimchy +---- +// CONSOLE +// TEST[continued] + +[source,js] +---- +GET /*/_search?q=user:kimchy +---- +// CONSOLE +// TEST[continued]