diff --git a/docs/reference/index-modules.asciidoc b/docs/reference/index-modules.asciidoc index 45817515312a7..7280c3735ea39 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 28c69125e127a..3a9ae7a894c8a 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -561,4 +561,20 @@ For other information, see: [role="exclude",id="modules-discovery-adding-removing-nodes"] === Adding and removing nodes -See <>. \ No newline at end of file +See <>. + +//// +[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 <>. +//// diff --git a/docs/reference/search/request-body.asciidoc b/docs/reference/search/request-body.asciidoc index ca3dbca3ad185..b901bb2c058b9 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 bf156a774fb4b..a8ff36e3ef2f4 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 8dad21a5803d6..9f4c961a996c0 100644 --- a/docs/reference/search/run-a-search.asciidoc +++ b/docs/reference/search/run-a-search.asciidoc @@ -283,3 +283,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 807478f1908d5..c9bd330ab3390 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -87,6 +87,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 @@ -170,6 +184,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 @@ -279,6 +307,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 @@ -309,6 +351,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