[DOCS] Add scroll API reference docs (#57153) (#57529)

Changes:

* Adds API reference docs for the scroll API
* Documents several related parameters in the search API docs

docs/reference/search.asciidoc

@@ -156,6 +156,8 @@ include::search/request-body.asciidoc[]
 
 include::search/async-search.asciidoc[]
 
+include::search/scroll-api.asciidoc[]
+
 include::search/search-template.asciidoc[]
 
 include::search/search-shards.asciidoc[]

docs/reference/search/scroll-api.asciidoc

@@ -0,0 +1,142 @@
+[[scroll-api]]
+=== Scroll API
+++++
+<titleabbrev>Scroll</titleabbrev>
+++++
+
+Retrieves the next batch of results for a <<request-body-search-scroll,scrolling
+search>>.
+
+////
+[source,console]
+--------------------------------------------------
+GET /_search?scroll=1m
+{
+  "size": 1,
+  "query": {
+    "match_all": {}
+  }
+}
+--------------------------------------------------
+// TEST[setup:twitter]
+////
+
+[source,console]
+--------------------------------------------------
+GET /_search/scroll
+{
+    "scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
+}
+--------------------------------------------------
+// TEST[continued]
+// TEST[s/DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==/$body._scroll_id/]
+
+[[scroll-api-request]]
+==== {api-request-title}
+
+`GET /_search/scroll/<scroll_id>`
+deprecated:[7.0.0]
+
+`GET /_search/scroll`
+
+`POST /_search/scroll/<scroll_id>`
+deprecated:[7.0.0]
+
+`POST /_search/scroll`
+
+[[scroll-api-desc]]
+==== {api-description-title}
+
+You can use the scroll API to retrieve large sets of results from a single
+<<request-body-search-scroll,scrolling search>> request.
+
+The scroll API requires a scroll ID. To get a scroll ID, submit a
+<<search-search,search API>> request that includes an argument for the
+<<search-api-scroll-query-param,`scroll` query parameter>>. The `scroll`
+parameter indicates how long {es} should retain the
+<<scroll-search-context,search context>> for the request.
+
+The search response returns a scroll ID in the `_scroll_id` response body
+parameter. You can then use the scroll ID with the scroll API to retrieve the
+next batch of results for the request.
+
+You can also use the scroll API to specify a new `scroll` parameter that extends
+or shortens the retention period for the search context.
+
+See <<request-body-search-scroll>>.
+
+IMPORTANT: Results from a scrolling search reflect the state of the index at the
+time of the initial search request. Subsequent indexing or document changes only
+affect later search and scroll requests.
+
+[[scroll-api-path-params]]
+==== {api-path-parms-title}
+
+`<scroll_id>`::
+deprecated:[7.0.0]
+(Optional, string)
+Scroll ID of the search.
++
+IMPORTANT: Scroll IDs can be long. We recommend only specifying scroll IDs using
+the <<scroll-api-scroll-id-param,`scroll_id` request body parameter>>.
+
+[[scroll-api-query-params]]
+==== {api-query-parms-title}
+
+`scroll`::
+(Optional, <<time-units,time value>>)
+Period to retain the <<scroll-search-context,search context>> for scrolling. See
+<<request-body-search-scroll>>.
++
+This value overrides the duration set by the original search API request's
+`scroll` parameter.
++
+By default, this value cannot must be less than `1d` (one day). You can change
+this limit using the `search.max_keep_alive` cluster-level setting.
++
+IMPORTANT: You can also specify this value using the `scroll` request body
+parameter. If both parameters are specified, only the query parameter is used.
+
+`scroll_id`::
+deprecated:[7.0.0]
+(Optional, string)
+Scroll ID for the search.
++
+IMPORTANT: Scroll IDs can be long. We recommend only specifying scroll IDs using
+the <<scroll-api-scroll-id-param,`scroll_id` request body parameter>>.
+
+`rest_total_hits_as_int`::
+(Optional, boolean)
+If `true`, the API response's `hit.total` property is returned as an integer.
+If `false`, the API response's `hit.total` property is returned as an object.
+Defaults to `false`.
+
+[role="child_attributes"]
+[[scroll-api-request-body]]
+==== {api-request-body-title}
+
+`scroll`::
+(Optional, <<time-units,time value>>)
+Period to retain the <<scroll-search-context,search context>> for scrolling. See
+<<request-body-search-scroll>>.
++
+This value overrides the duration set by the original search API request's
+`scroll` parameter.
++
+By default, this value cannot must be less than `1d` (one day). You can change
+this limit using the `search.max_keep_alive` cluster-level setting.
++
+IMPORTANT: You can also specify this value using the `scroll` query
+parameter. If both parameters are specified, only the query parameter is used.
+
+[[scroll-api-scroll-id-param]]
+`scroll_id`::
+(Required, string)
+Scroll ID for the search.
+
+[role="child_attributes"]
+[[scroll-api-response-body]]
+==== {api-response-body-title}
+
+The scroll API returns the same response body as the search API. See the search
+API's <<search-api-response-body,response body parameters>>.

docs/reference/search/search.asciidoc

@@ -165,6 +165,15 @@ level settings.
   (Optional, <<time-units, time units>>) Specifies how long a consistent view of
   the index should be maintained for scrolled search.
 
+[[search-api-scroll-query-param]]
+`scroll`::
+(Optional, <<time-units,time value>>)
+Period to retain the <<scroll-search-context,search context>> for scrolling. See
+<<request-body-search-scroll>>.
++
+By default, this value cannot must be less than `1d` (one day). You can change
+this limit using the `search.max_keep_alive` cluster-level setting.
+
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=search_type]
 
 `seq_no_primary_term`::
@@ -198,6 +207,9 @@ As an alternative to deep paging, we recommend using
 <<request-body-search-scroll,scroll>> or the
 <<request-body-search-search-after,`search_after`>> parameter.
 
+If the <<search-api-scroll-query-param,`scroll` parameter>> is specified, this
+value cannot be zero (`0`).
+
 [IMPORTANT]
 ====
 You can also specify this value using the `size` request body parameter. If
@@ -365,6 +377,9 @@ As an alternative to deep paging, we recommend using
 <<request-body-search-scroll,scroll>> or the
 <<request-body-search-search-after,`search_after`>> parameter.
 
+If the <<search-api-scroll-query-param,`scroll` parameter>> is specified, this
+value cannot be zero (`0`).
+
 [IMPORTANT]
 ====
 You can also specify this value using the `size` query parameter. If both
@@ -417,6 +432,17 @@ parameters are specified, only the query parameter is used.
 [[search-api-response-body]]
 ==== {api-response-body-title}
 
+`_scroll_id`::
+(string)
+Identifier for the search and its <<scroll-search-context,search context>>.
++
+You can use this scroll ID with the <<scroll-api,scroll API>> to retrieve the
+next batch of search results for the request. See
+<<request-body-search-scroll>>.
++
+This parameter is only returned if the <<search-api-scroll-query-param,`scroll`
+query parameter>> is specified in the request.
+
 `took`::
 +
 --