From a1d3c9f3feea679293b2c62158e597b0bbc6426c Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 15 May 2020 08:25:01 -0400 Subject: [PATCH] review feedback --- .../search/request/from-size.asciidoc | 33 ++++---- docs/reference/search/search.asciidoc | 80 ++++++++++++------- 2 files changed, 71 insertions(+), 42 deletions(-) diff --git a/docs/reference/search/request/from-size.asciidoc b/docs/reference/search/request/from-size.asciidoc index 17c505d33cf21..3eaba34ca83ad 100644 --- a/docs/reference/search/request/from-size.asciidoc +++ b/docs/reference/search/request/from-size.asciidoc @@ -2,19 +2,12 @@ [[paginate-search-results]] === Paginate search results -By default, the search API returns the top 10 matching documents, -starting with the most-relevant document. +By default, the search API returns the top 10 matching documents. 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. - -[IMPORTANT] -==== -The combined document count, including offset and and returned documents, for -the `from` and `size` parameters cannot exceed the -<> index setting, which -defaults to 10,000 documents. -==== +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] @@ -39,9 +32,21 @@ GET /_search ---- ==== +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. + +Paging deeply 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/search.asciidoc b/docs/reference/search/search.asciidoc index c4d8bda6e5434..6eac7e59eab40 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -87,13 +87,19 @@ both parameters are specified, only the query parameter is used. include::{docdir}/rest-api/common-parms.asciidoc[tag=from] + -- -[IMPORTANT] -==== -The combined document count, including offset and and returned documents, for -the `from` and `size` parameters cannot exceed the -<> index setting, which -defaults to 10,000 documents. -==== +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. + +Paging deeply 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] ==== @@ -178,13 +184,19 @@ parameter. If both parameters are specified, only the query parameter is used. (Optional, integer) Defines the number of hits to return. Defaults to `10`. + -- -[IMPORTANT] -==== -The combined document count, including offset and and returned documents, for -the `from` and `size` parameters cannot exceed the -<> index setting, which -defaults to 10,000 documents. -==== +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. + +Paging deeply 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] ==== @@ -295,13 +307,19 @@ both parameters are specified, only the query parameter is used. include::{docdir}/rest-api/common-parms.asciidoc[tag=from] + -- -[IMPORTANT] -==== -The combined document count, including offset and and returned documents, for -the `from` and `size` parameters cannot exceed the -<> index setting, which -defaults to 10,000 documents. -==== +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. + +Paging deeply 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] ==== @@ -333,13 +351,19 @@ If both parameters are specified, only the query parameter is used. (Optional, integer) The number of hits to return. Defaults to `10`. + -- -[IMPORTANT] -==== -The combined document count, including offset and and returned documents, for -the `from` and `size` parameters cannot exceed the -<> index setting, which -defaults to 10,000 documents. -==== +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. + +Paging deeply 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] ====