From 994781ff36160b0467aaf092c463fbed7d1da50d Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 1 Jun 2020 16:43:06 -0400 Subject: [PATCH] [DOCS] Add search pagination docs (#56785) (#57477) Reworks the `from / size` content to `Paginate search results`. Moves those docs from the request body search API page (slated for deletion) to the `Run a search` tutorial docs. Also adds some notes to the `from` and `size` param docs. Co-authored-by: debadair --- docs/reference/index-modules.asciidoc | 1 + docs/reference/redirects.asciidoc | 20 ++++++- docs/reference/search/request-body.asciidoc | 2 - .../search/request/from-size.asciidoc | 58 ++++++++++++------- docs/reference/search/run-a-search.asciidoc | 2 + docs/reference/search/search.asciidoc | 56 ++++++++++++++++++ 6 files changed, 115 insertions(+), 24 deletions(-) diff --git a/docs/reference/index-modules.asciidoc b/docs/reference/index-modules.asciidoc index f9c0f7e8615..2ff5d50cba2 100644 --- a/docs/reference/index-modules.asciidoc +++ b/docs/reference/index-modules.asciidoc @@ -128,6 +128,7 @@ specific index module: out of this behavior an explicit value of `1s` should set as the refresh interval. +[[index-max-result-window]] `index.max_result_window`:: The maximum value of `from + size` for searches to this index. Defaults to diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 127eef879a4..52adf6cbbf3 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -66,7 +66,7 @@ See <>. [role="exclude",id="search-request-from-size"] === From and size parameters for request body search API -See <>. +See <>. [role="exclude",id="search-request-highlighting"] === Highlight parameter for request body search API @@ -724,7 +724,7 @@ See <>. See <>. [role="exclude",id="search-uri-request"] -=== URI Search +=== URI search See <>. @@ -881,3 +881,19 @@ We have stopped adding new customers to our {esms}. If you are interested in similar capabilities, contact https://support.elastic.co[Elastic Support] to discuss available options. + +//// +[role="exclude",id="search-request-body"] +=== Request body search + +This page has been removed. + +For search API reference documentation, see <>. + +For search examples, see <>. + +[role="exclude",id="request-body-search-from-size"] +==== From / size + +See <>. +//// \ No newline at end of file diff --git a/docs/reference/search/request-body.asciidoc b/docs/reference/search/request-body.asciidoc index ca3dbca3ad1..b901bb2c058 100644 --- a/docs/reference/search/request-body.asciidoc +++ b/docs/reference/search/request-body.asciidoc @@ -106,8 +106,6 @@ include::request/docvalue-fields.asciidoc[] include::request/collapse.asciidoc[] -include::request/from-size.asciidoc[] - include::request/highlighting.asciidoc[] include::request/index-boost.asciidoc[] diff --git a/docs/reference/search/request/from-size.asciidoc b/docs/reference/search/request/from-size.asciidoc index bf156a774fb..a8ff36e3ef2 100644 --- a/docs/reference/search/request/from-size.asciidoc +++ b/docs/reference/search/request/from-size.asciidoc @@ -1,33 +1,51 @@ -[[request-body-search-from-size]] -==== From / Size +[discrete] +[[paginate-search-results]] +=== Paginate search results -Pagination of results can be done by using the `from` and `size` -parameters. The `from` parameter defines the offset from the first -result you want to fetch. The `size` parameter allows you to configure -the maximum amount of hits to be returned. +By default, the search API returns the top 10 matching documents. -Though `from` and `size` can be set as request parameters, they can also -be set within the search body. `from` defaults to `0`, and `size` -defaults to `10`. +To paginate through a larger set of results, you can use the search API's `size` +and `from` parameters. The `size` parameter is the number of matching documents +to return. The `from` parameter is a zero-indexed offset from the beginning of +the complete result set that indicates the document you want to start with. + +.*Example* +[%collapsible] +==== +The following search API request sets the `from` offset to `5`, meaning the +request offsets, or skips, the first five matching documents. + +The `size` parameter is `20`, meaning the request can return up to 20 documents, +starting at the offset. [source,console] --------------------------------------------------- +---- GET /_search { - "from" : 0, "size" : 10, - "query" : { - "term" : { "user" : "kimchy" } - } + "from": 5, + "size": 20, + "query": { + "term": { "user": "kimchy" } + } } --------------------------------------------------- +---- +==== +By default, you cannot page through more than 10,000 documents using the `from` +and `size` parameters. This limit is set using the +<> index setting. -Note that `from` + `size` can not be more than the `index.max_result_window` -index setting, which defaults to 10,000. +Deep paging or requesting many results at once can result in slow searches. +Results are sorted before being returned. Because search requests usually span +multiple shards, each shard must generate its own sorted results. These separate +results must then be combined and sorted to ensure that the overall sort order +is correct. + +As an alternative to deep paging, we recommend using the +<> or +<> APIs. WARNING: {es} uses Lucene's internal doc IDs as tie-breakers. These internal doc IDs can be completely different across replicas of the same data. When paginating, you might occasionally see that documents with the same -sort values are not ordered consistently. For deep scrolling, it is more -efficient to use the <> or -<> APIs. +sort values are not ordered consistently. diff --git a/docs/reference/search/run-a-search.asciidoc b/docs/reference/search/run-a-search.asciidoc index f6242c56927..aa8524a2321 100644 --- a/docs/reference/search/run-a-search.asciidoc +++ b/docs/reference/search/run-a-search.asciidoc @@ -287,3 +287,5 @@ GET /*/_search ---- // TEST[continued] ==== + +include::request/from-size.asciidoc[] diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc index 36302f05c75..4c89c2bf905 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -89,6 +89,20 @@ both parameters are specified, only the query parameter is used. include::{docdir}/rest-api/common-parms.asciidoc[tag=from] + -- +By default, you cannot page through more than 10,000 documents using the `from` +and `size` parameters. This limit is set using the +<> index setting. + +Deep paging or requesting many results at once can result in slow searches. +Results are sorted before being returned. Because search requests usually span +multiple shards, each shard must generate its own sorted results. These separate +results must then be combined and sorted to ensure that the overall order is +correct. + +As an alternative to deep paging, we recommend using the +<> or +<> APIs. + [IMPORTANT] ==== You can also specify this value using the `from` request body parameter. If @@ -172,6 +186,20 @@ parameter. If both parameters are specified, only the query parameter is used. (Optional, integer) Defines the number of hits to return. Defaults to `10`. + -- +By default, you cannot page through more than 10,000 documents using the `from` +and `size` parameters. This limit is set using the +<> index setting. + +Deep paging or requesting many results at once can result in slow searches. +Results are sorted before being returned. Because search requests usually span +multiple shards, each shard must generate its own sorted results. These separate +results must then be combined and sorted to ensure that the overall order is +correct. + +As an alternative to deep paging, we recommend using the +<> or +<> APIs. + [IMPORTANT] ==== You can also specify this value using the `size` request body parameter. If @@ -281,6 +309,20 @@ both parameters are specified, only the query parameter is used. include::{docdir}/rest-api/common-parms.asciidoc[tag=from] + -- +By default, you cannot page through more than 10,000 documents using the `from` +and `size` parameters. This limit is set using the +<> index setting. + +Deep paging or requesting many results at once can result in slow searches. +Results are sorted before being returned. Because search requests usually span +multiple shards, each shard must generate its own sorted results. These separate +results must then be combined and sorted to ensure that the overall order is +correct. + +As an alternative to deep paging, we recommend using the +<> or +<> APIs. + [IMPORTANT] ==== You can also specify this value using the `from` query parameter. If both @@ -311,6 +353,20 @@ If both parameters are specified, only the query parameter is used. (Optional, integer) The number of hits to return. Defaults to `10`. + -- +By default, you cannot page through more than 10,000 documents using the `from` +and `size` parameters. This limit is set using the +<> index setting. + +Deep paging or requesting many results at once can result in slow searches. +Results are sorted before being returned. Because search requests usually span +multiple shards, each shard must generate its own sorted results. These separate +results must then be combined and sorted to ensure that the overall order is +correct. + +As an alternative to deep paging, we recommend using the +<> or +<> APIs. + [IMPORTANT] ==== You can also specify this value using the `size` query parameter. If both