diff --git a/docs/java-rest/high-level/document/multi-get.asciidoc b/docs/java-rest/high-level/document/multi-get.asciidoc index 1cf487dec1399..5d1a62e11451c 100644 --- a/docs/java-rest/high-level/document/multi-get.asciidoc +++ b/docs/java-rest/high-level/document/multi-get.asciidoc @@ -65,7 +65,7 @@ include-tagged::{doc-tests-file}[{api}-request-item-extras] <2> Version <3> Version type -{ref}/search-request-body.html#request-body-search-preference[`preference`], +{ref}/search-your-data.html#search-preference[`preference`], {ref}/docs-get.html#realtime[`realtime`] and {ref}/docs-get.html#get-refresh[`refresh`] can be set on the main request but diff --git a/docs/reference/how-to/recipes/scoring.asciidoc b/docs/reference/how-to/recipes/scoring.asciidoc index d7657879444c2..42c6b6412be18 100644 --- a/docs/reference/how-to/recipes/scoring.asciidoc +++ b/docs/reference/how-to/recipes/scoring.asciidoc @@ -29,7 +29,7 @@ are different too. The recommended way to work around this issue is to use a string that identifies the user that is logged is (a user id or session id for instance) as a -<>. This ensures that all queries of a +<>. This ensures that all queries of a given user are always going to hit the same shards, so scores remain more consistent across queries. diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 44ef7c6c142f3..3470fd503bb67 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -75,7 +75,7 @@ See <>. [role="exclude",id="search-request-index-boost"] === Index boost parameter for request body search API -See <>. +See <>. [role="exclude",id="search-request-inner-hits"] === Inner hits parameter for request body search API @@ -95,7 +95,7 @@ See <>. [role="exclude",id="search-request-preference"] === Preference parameter for request body search API -See <>. +See <>. [role="exclude",id="search-request-query"] === Query parameter for request body search API @@ -103,7 +103,7 @@ See <>. [role="exclude",id="search-request-rescore"] === Rescoring parameter for request body search API -See <>. +See <>. [role="exclude",id="search-request-script-fields"] === Script fields parameter for request body search API @@ -119,11 +119,11 @@ See <>. [role="exclude",id="search-request-search-type"] === Search type parameter for request body search API -See <>. +See <>. [role="exclude",id="search-request-seq-no-primary-term"] === Sequence numbers and primary terms parameter for request body search API -See <>. +See <>. [role="exclude",id="search-request-sort"] === Sort parameter for request body search API @@ -140,7 +140,7 @@ See <>. [role="exclude",id="search-request-track-total-hits"] === Track total hits parameter for request body search API -See <>. +See <>. [role="exclude",id="search-request-version"] === Version parameter for request body search API @@ -974,7 +974,6 @@ See <>. See <>. -//// [role="exclude",id="search-request-body"] === Request body search @@ -982,13 +981,18 @@ This page has been removed. For search API reference documentation, see <>. -For search examples, see <>. +For search examples, see <>. [role="exclude",id="request-body-search-docvalue-fields"] ==== Doc value fields See <>. +[role="exclude",id="_fast_check_for_any_matching_docs"] +==== Fast check for any matching docs + +See <>. + [role="exclude",id="request-body-search-collapse"] ==== Field collapsing @@ -1009,26 +1013,36 @@ See <>. See <>. +[role="exclude",id="request-body-search-index-boost"] +==== Index boost +See <>. + [role="exclude",id="request-body-search-inner-hits"] -=== Inner hits +==== Inner hits See <>. [role="exclude",id="request-body-search-min-score"] -=== `min_score` -See <>. +==== `min_score` + +See the <> parameter. [role="exclude",id="request-body-search-queries-and-filters"] -=== Named queries +==== Named queries -See <. +See <>. [role="exclude",id="request-body-search-post-filter"] -=== Post filter +==== Post filter See <>. +[role="exclude",id="request-body-search-preference"] +==== Preference + +See <>. + [role="exclude",id="request-body-search-rescore"] -=== Rescoring +==== Rescoring See <>. @@ -1043,12 +1057,12 @@ See <>. See <>. [[_clear_scroll_api]] -===== Clear scroll API +==== Clear scroll API See <>. [[sliced-scroll]] -===== Sliced scroll +==== Sliced scroll See <>. @@ -1057,6 +1071,11 @@ See <>. See <>. +[role="exclude",id="request-body-search-search-type"] +==== Search type + +See <>. + [role="exclude",id="request-body-search-sort"] ==== Sort @@ -1071,4 +1090,8 @@ See <>. ==== Stored fields See <>. -//// + +[role="exclude",id="request-body-search-track-total-hits"] +==== Track total hits + +See <>. diff --git a/docs/reference/search.asciidoc b/docs/reference/search.asciidoc index e360e12d4df8d..4e7c4abd58139 100644 --- a/docs/reference/search.asciidoc +++ b/docs/reference/search.asciidoc @@ -154,8 +154,6 @@ high). This default value is `5`. include::search/search.asciidoc[] -include::search/request-body.asciidoc[] - include::search/async-search.asciidoc[] include::search/scroll-api.asciidoc[] diff --git a/docs/reference/search/quickly-check-for-matching-docs.asciidoc b/docs/reference/search/quickly-check-for-matching-docs.asciidoc new file mode 100644 index 0000000000000..2b18f8519f529 --- /dev/null +++ b/docs/reference/search/quickly-check-for-matching-docs.asciidoc @@ -0,0 +1,60 @@ +[discrete] +[[quickly-check-for-matching-docs]] +=== Quickly check for matching docs + +If you only want to know if there are any documents matching a +specific query, you can set the `size` to `0` to indicate that we are not +interested in the search results. You can also set `terminate_after` to `1` +to indicate that the query execution can be terminated whenever the first +matching document was found (per shard). + +[source,console] +-------------------------------------------------- +GET /_search?q=user.id:elkbee&size=0&terminate_after=1 +-------------------------------------------------- +// TEST[setup:my_index] + +NOTE: `terminate_after` is always applied **after** the +<> and stops the query as well as the aggregation +executions when enough hits have been collected on the shard. Though the doc +count on aggregations may not reflect the `hits.total` in the response since +aggregations are applied **before** the post filtering. + +The response will not contain any hits as the `size` was set to `0`. The +`hits.total` will be either equal to `0`, indicating that there were no +matching documents, or greater than `0` meaning that there were at least +as many documents matching the query when it was early terminated. +Also if the query was terminated early, the `terminated_early` flag will +be set to `true` in the response. + +[source,console-result] +-------------------------------------------------- +{ + "took": 3, + "timed_out": false, + "terminated_early": true, + "_shards": { + "total": 1, + "successful": 1, + "skipped" : 0, + "failed": 0 + }, + "hits": { + "total" : { + "value": 1, + "relation": "eq" + }, + "max_score": null, + "hits": [] + } +} +-------------------------------------------------- +// TESTRESPONSE[s/"took": 3/"took": $body.took/] + + +The `took` time in the response contains the milliseconds that this request +took for processing, beginning quickly after the node received the query, up +until all search related work is done and before the above JSON is returned +to the client. This means it includes the time spent waiting in thread pools, +executing a distributed search across the whole cluster and gathering all the +results. \ No newline at end of file diff --git a/docs/reference/search/request-body.asciidoc b/docs/reference/search/request-body.asciidoc deleted file mode 100644 index 330036cbf7655..0000000000000 --- a/docs/reference/search/request-body.asciidoc +++ /dev/null @@ -1,197 +0,0 @@ -[[search-request-body]] -=== Request Body Search - -Specifies search criteria as request body parameters. - -[source,console] --------------------------------------------------- -GET /my-index-000001/_search -{ - "query" : { - "term" : { "user.id" : "kimchy" } - } -} --------------------------------------------------- -// TEST[setup:my_index] - - -[[search-request-body-api-request]] -==== {api-request-title} - -`GET //_search -{ - "query": {} -}` - - -[[search-request-body-api-desc]] -==== {api-description-title} - -The search request can be executed with a search DSL, which includes the -<>, within its body. - - -[[search-request-body-api-path-params]] -==== {api-path-parms-title} - -``:: -(Optional, string) -Comma-separated list of data streams, indices, and index aliases to search. -Wildcard (`*`) expressions are supported. -+ -To search all data streams and indices in a cluster, omit this parameter or use -`_all` or `*`. - -[[search-request-body-api-request-body]] -==== {api-request-body-title} - -See the search API's <>. - -==== Fast check for any matching docs - -NOTE: `terminate_after` is always applied **after** the `post_filter` and stops - the query as well as the aggregation executions when enough hits have been - collected on the shard. Though the doc count on aggregations may not reflect - the `hits.total` in the response since aggregations are applied **before** the - post filtering. - -In case we only want to know if there are any documents matching a -specific query, we can set the `size` to `0` to indicate that we are not -interested in the search results. Also we can set `terminate_after` to `1` -to indicate that the query execution can be terminated whenever the first -matching document was found (per shard). - -[source,console] --------------------------------------------------- -GET /_search?q=user.id:elkbee&size=0&terminate_after=1 --------------------------------------------------- -// TEST[setup:my_index] - - -The response will not contain any hits as the `size` was set to `0`. The -`hits.total` will be either equal to `0`, indicating that there were no -matching documents, or greater than `0` meaning that there were at least -as many documents matching the query when it was early terminated. -Also if the query was terminated early, the `terminated_early` flag will -be set to `true` in the response. - -[source,console-result] --------------------------------------------------- -{ - "took": 3, - "timed_out": false, - "terminated_early": true, - "_shards": { - "total": 1, - "successful": 1, - "skipped" : 0, - "failed": 0 - }, - "hits": { - "total" : { - "value": 1, - "relation": "eq" - }, - "max_score": null, - "hits": [] - } -} --------------------------------------------------- -// TESTRESPONSE[s/"took": 3/"took": $body.took/] - - -The `took` time in the response contains the milliseconds that this request -took for processing, beginning quickly after the node received the query, up -until all search related work is done and before the above JSON is returned -to the client. This means it includes the time spent waiting in thread pools, -executing a distributed search across the whole cluster and gathering all the -results. - - -[[request-body-search-docvalue-fields]] -==== Doc value fields - -See <>. - -[[request-body-search-collapse]] -==== Field collapsing - -See <>. - -[[request-body-search-highlighting]] -==== Highlighting - -See <>. - -include::request/index-boost.asciidoc[] - -[[request-body-search-inner-hits]] -==== Inner hits - -See <>. - -[[request-body-search-min-score]] -==== `min_score` - -See <>. - -[[request-body-search-queries-and-filters]] -==== Named queries - -See <>. - -[[request-body-search-post-filter]] -==== Post filter - -See <>. - -include::request/preference.asciidoc[] - -[[request-body-search-rescore]] -==== Rescoring - -See <>. - -[[request-body-search-script-fields]] -==== Script fields - -See <>. - -[[request-body-search-scroll]] -==== Scroll - -See <>. - -[[_clear_scroll_api]] -===== Clear scroll API - -See <>. - -[[sliced-scroll]] -===== Sliced scroll - -See <>. - -[[request-body-search-search-after]] -==== Search After - -See <>. - -include::request/search-type.asciidoc[] - -[[request-body-search-sort]] -==== Sort - -See <>. - -[[request-body-search-source-filtering]] -==== Source filtering - -See <>. - -[[request-body-search-stored-fields]] -==== Stored fields - -See <>. - -include::request/track-total-hits.asciidoc[] diff --git a/docs/reference/search/request/collapse.asciidoc b/docs/reference/search/request/collapse.asciidoc index 4bf501042380a..e4f8c8b100e0a 100644 --- a/docs/reference/search/request/collapse.asciidoc +++ b/docs/reference/search/request/collapse.asciidoc @@ -119,7 +119,7 @@ the maximum number of concurrent searches allowed in this phase. The default is based on the number of data nodes and the default search thread pool size. WARNING: `collapse` cannot be used in conjunction with <>, -<> or <>. +<> or <>. [discrete] [[second-level-of-collapsing]] diff --git a/docs/reference/search/request/index-boost.asciidoc b/docs/reference/search/request/index-boost.asciidoc index 85442ca8c75e2..381cb75b254aa 100644 --- a/docs/reference/search/request/index-boost.asciidoc +++ b/docs/reference/search/request/index-boost.asciidoc @@ -1,12 +1,11 @@ -[[request-body-search-index-boost]] -==== Index Boost +[discrete] +[[index-boost]] +=== Index boost -Allows to configure different boost level per index when searching -across more than one indices. This is very handy when hits coming from -one index matter more than hits coming from another index (think social -graph where each user has an index). +When searching multiple indices, you can use the `indices_boost` parameter to +boost results from one or more specified indices. This is useful when hits +coming from one index matter more than hits coming from another index. -deprecated[5.2.0, This format is deprecated. Please use array format instead.] [source,console] -------------------------------------------------- GET /_search diff --git a/docs/reference/search/request/preference.asciidoc b/docs/reference/search/request/preference.asciidoc index 78cbfb67a2dd6..2264002226f87 100644 --- a/docs/reference/search/request/preference.asciidoc +++ b/docs/reference/search/request/preference.asciidoc @@ -1,7 +1,8 @@ -[[request-body-search-preference]] -==== Preference +[discrete] +[[search-preference]] +=== Preference -Controls a `preference` of the shard copies on which to execute the search. By +You can use the `preference` parameter to control the shard copies on which a search runs. By default, Elasticsearch selects from the available shard copies in an unspecified order, taking the <> and <> configuration into diff --git a/docs/reference/search/request/scroll.asciidoc b/docs/reference/search/request/scroll.asciidoc index 2a45addcdd72f..a199110585cc0 100644 --- a/docs/reference/search/request/scroll.asciidoc +++ b/docs/reference/search/request/scroll.asciidoc @@ -202,7 +202,7 @@ DELETE /_search/scroll/DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMN [discrete] [[slice-scroll]] -==== Sliced Scroll +==== Sliced scroll For scroll queries that return a lot of documents it is possible to split the scroll in multiple slices which can be consumed independently: diff --git a/docs/reference/search/request/search-type.asciidoc b/docs/reference/search/request/search-type.asciidoc index a1a4cea43f7c6..2c03ae9fc1221 100644 --- a/docs/reference/search/request/search-type.asciidoc +++ b/docs/reference/search/request/search-type.asciidoc @@ -1,5 +1,6 @@ -[[request-body-search-search-type]] -==== Search Type +[discrete] +[[search-type]] +=== Search type There are different execution paths that can be done when executing a distributed search. The distributed search operation needs to be @@ -34,8 +35,9 @@ to execute on a *per search request* basis. The type can be configured by setting the *search_type* parameter in the query string. The types are: +[discrete] [[query-then-fetch]] -===== Query Then Fetch +==== Query Then Fetch Parameter value: *query_then_fetch*. @@ -59,8 +61,9 @@ GET my-index-000001/_search?search_type=query_then_fetch NOTE: This is the default setting, if you do not specify a `search_type` in your request. +[discrete] [[dfs-query-then-fetch]] -===== Dfs, Query Then Fetch +==== Dfs, Query Then Fetch Parameter value: *dfs_query_then_fetch*. diff --git a/docs/reference/search/request/track-total-hits.asciidoc b/docs/reference/search/request/track-total-hits.asciidoc index e13b2d5069cf6..d225c03ac6df9 100644 --- a/docs/reference/search/request/track-total-hits.asciidoc +++ b/docs/reference/search/request/track-total-hits.asciidoc @@ -1,5 +1,6 @@ -[[request-body-search-track-total-hits]] -==== Track total hits +[discrete] +[[track-total-hits]] +=== Track total hits Generally the total hit count can't be computed accurately without visiting all matches, which is costly for queries that match lots of documents. The diff --git a/docs/reference/search/search-your-data.asciidoc b/docs/reference/search/search-your-data.asciidoc index 19de6c9dcc9ff..3d0858fac61ae 100644 --- a/docs/reference/search/search-your-data.asciidoc +++ b/docs/reference/search/search-your-data.asciidoc @@ -228,6 +228,12 @@ GET /*/_search ---- // TEST[setup:my_index] +include::request/index-boost.asciidoc[] +include::request/preference.asciidoc[] +include::request/search-type.asciidoc[] +include::request/track-total-hits.asciidoc[] +include::quickly-check-for-matching-docs.asciidoc[] + include::request/collapse.asciidoc[] include::filter-search-results.asciidoc[] include::request/highlighting.asciidoc[] diff --git a/x-pack/docs/en/watcher/customizing-watches.asciidoc b/x-pack/docs/en/watcher/customizing-watches.asciidoc index 716da9676c80a..2c22b7bd07008 100644 --- a/x-pack/docs/en/watcher/customizing-watches.asciidoc +++ b/x-pack/docs/en/watcher/customizing-watches.asciidoc @@ -49,7 +49,7 @@ You can use the `search` input to load Elasticsearch search results as the watch initial payload. A <> input contains a `request` object that specifies the -indices you want to search, the <>, +indices you want to search, the <>, and the search request body. The `body` field of a search input is the same as the body of an Elasticsearch `_search` request, making the full Elasticsearch Query DSL available for you to use. diff --git a/x-pack/docs/en/watcher/input/search.asciidoc b/x-pack/docs/en/watcher/input/search.asciidoc index 7abef248f371a..2fffe18f3a18c 100644 --- a/x-pack/docs/en/watcher/input/search.asciidoc +++ b/x-pack/docs/en/watcher/input/search.asciidoc @@ -9,7 +9,7 @@ into the execution context when the watch is triggered. See In the search input's `request` object, you specify: * The indices you want to search -* The <> +* The <> * The search request body The search request body supports the full Elasticsearch Query DSL--it's the @@ -163,7 +163,7 @@ accurately. |====== | Name |Required | Default | Description -| `request.search_type` | no | `query_then_fetch` | The <> +| `request.search_type` | no | `query_then_fetch` | The <> of search request to perform. Valid values are: `dfs_query_and_fetch`, `dfs_query_then_fetch`, `query_and_fetch`, and `query_then_fetch`. The Elasticsearch default is `query_then_fetch`. diff --git a/x-pack/docs/en/watcher/transform/search.asciidoc b/x-pack/docs/en/watcher/transform/search.asciidoc index 902fe5b37804a..7b4e9c7277391 100644 --- a/x-pack/docs/en/watcher/transform/search.asciidoc +++ b/x-pack/docs/en/watcher/transform/search.asciidoc @@ -55,7 +55,7 @@ The following table lists all available settings for the search |====== | Name |Required | Default | Description -| `request.search_type` | no | query_then_fetch | The search <>. +| `request.search_type` | no | query_then_fetch | The search <>. | `request.indices` | no | all indices | One or more indices to search on.