[DOCS] Add search pagination docs (#56785) (#57478)

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 <[email protected]>

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

docs/reference/redirects.asciidoc

@@ -66,7 +66,7 @@ See <<request-body-search-collapse>>.
 
 [role="exclude",id="search-request-from-size"]
 === From and size parameters for request body search API
-See <<request-body-search-from-size>>.
+See <<paginate-search-results>>.
 
 [role="exclude",id="search-request-highlighting"]
 === Highlight parameter for request body search API
@@ -723,7 +723,7 @@ See <<ilm-actions>>.
 See <<ilm-index-lifecycle>>.
 
 [role="exclude",id="search-uri-request"]
-=== URI Search
+=== URI search
 
 See <<search-search>>.
 
@@ -880,3 +880,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 <<search-search>>.
+
+For search examples, see <<run-a-search>>.
+
+[role="exclude",id="request-body-search-from-size"]
+==== From / size
+
+See <<paginate-search-results>>.
+////

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[]

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-max-result-window,`index.max_result_window`>> 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
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> 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 <<request-body-search-scroll,Scroll>> or 
-<<request-body-search-search-after,Search After>> APIs.
+sort values are not ordered consistently.

docs/reference/search/run-a-search.asciidoc

@@ -287,3 +287,5 @@ GET /*/_search
 ----
 // TEST[continued]
 ====
+
+include::request/from-size.asciidoc[]

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-max-result-window,`index.max_result_window`>> 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
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> 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-max-result-window,`index.max_result_window`>> 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
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> 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-max-result-window,`index.max_result_window`>> 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
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> 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-max-result-window,`index.max_result_window`>> 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
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> APIs.
+
 [IMPORTANT]
 ====
 You can also specify this value using the `size` query parameter. If both