OpenSearch/docs/java-rest/high-level/apis/scroll.asciidoc

[[java-rest-high-search-scroll]]
=== Search Scroll API

The Scroll API can be used to retrieve a large number of results from
a search request.

In order to use scrolling, several steps need to be executed in a given order:

* At first, an initial search request with a non-null `scroll` parameter must
be executed. When processing this `SearchRequest`, Elasticsearch detects the
presence of the `scroll` parameter and keeps the search context alive during
the time defined by the parameter. Elasticsearch generates a scroll identifier
associated to this search context and returns it with the first batch of search
results in a `SearchResponse`.

* As a second step, the initial scroll parameter and the new scroll identifier
are set in a `SearchScrollRequest`. This request is executed using the Search
Scroll API and Elasticsearch returns the second batch of results with a new
 scroll identifier. This new scroll id can then be used in another `SearchScrollRequest`
 to retrieve the next batch of results. This process can be repeated over and
  over until no more results are returned.

* Finally, the last scroll identifier can be deleted using the <<java-rest-high-clear-scroll>>
in order to release the search context.

[[java-rest-high-search-scroll-example]]
==== Example of Execution

Here is an example of a scrolled search:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-example]
--------------------------------------------------
<1> Define a scroll parameter as a `TimeValue` corresponding to one minute
<2> Create a new `SearchRequest`. See <<java-rest-high-search>>
for more information on how to build `SearchRequest`.
<3> Set the `scroll` parameter to the `SearchRequest`
<4> Execute the `SearchRequest`
<5> Retrieve the first scroll id
<6> Retrieve the first batch of search hits
<7> Iterate until there are no more search hits to process
<8> Create a new `SearchScrollRequest`
<9> Set the `scroll` parameter again to tell Elasticsearch to keep the search context
alive for another minute
<10> Set the scroll id
<11> Execute the `SearchScrollRequest` using the Search Scroll API
<12> Retrieve the next scroll id to use in upcoming requests
<13> Retrieve the next batch of search hits
<14> Clear the scroll id using the <<java-rest-high-clear-scroll>>.

==== Optional arguments
The following argument can optionally be provided:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[scroll-request-scroll]
--------------------------------------------------
<1> Scroll value (ie, the time to keep alive the search context) as a `TimeValue`
<2> Scroll value (ie, the time to keep alive the search context) as a `String`

If no `scroll` value is set for the `SearchScrollRequest`, then the search context
will expire once the initial scroll time expired (ie, the scroll time set in the
initial search request).

[[java-rest-high-search-scroll-sync]]
==== Synchronous Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-sync]
--------------------------------------------------

[[java-rest-high-search-scroll-async]]
==== Asynchronous Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-async]
--------------------------------------------------
<1> Called when the execution is successfully completed. The response is
provided as an argument
<2> Called in case of failure. The raised exception is provided as an argument


[[java-rest-high-clear-scroll]]
=== Clear Scroll API

The search contexts used by the Scroll API are automatically deleted when the scroll
times out. But it is advised to release search contexts as soon as they are not
necessary anymore using the Clear Scroll API.

[[java-rest-high-clear-scroll-request]]
==== Clear Scroll Request

A `ClearScrollRequest` can be created as follows:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-request]
--------------------------------------------------
<1> Create a new `ClearScrollRequest`
<2> Adds a scroll id to the list of scroll identifiers to clear

==== Providing the scroll identifiers
The `ClearScrollRequest` allows to clear one or more scroll identifiers in a single request.

The scroll identifiers can be added to the request one by one:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-add-scroll-id]
--------------------------------------------------

Or all together using:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-add-scroll-ids]
--------------------------------------------------

[[java-rest-high-clear-scroll-sync]]
==== Synchronous Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute]
--------------------------------------------------

[[java-rest-high-clear-scroll-async]]
==== Asynchronous Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute-async]
--------------------------------------------------
<1> Called when the execution is successfully completed. The response is
provided as an argument
<2> Called in case of failure. The raised exception is provided as an argument

[[java-rest-high-clear-scroll-response]]
==== Clear Scroll Response

The returned `ClearScrollResponse` allows to retrieve information about the released
 search contexts:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-response]
--------------------------------------------------
<1> Return true if the request succeeded
<2> Return the number of released search contexts