OpenSearch/docs/java-rest/high-level/search/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, the following steps need to be executed in the
given order.


==== Initialize the search scroll context

An initial search request with a `scroll` parameter must be executed to
initialize the scroll session through the <<java-rest-high-search>>.
When processing this `SearchRequest`, Elasticsearch detects the presence of
the `scroll` parameter and keeps the search context alive for the
corresponding time interval.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-init]
--------------------------------------------------
<1> Create the `SearchRequest` and its corresponding `SearchSourceBuilder`.
Also optionally set the `size` to control how many results to retrieve at
a time.
<2> Set the scroll interval
<3> Read the returned scroll id, which points to the search context that's
being kept alive and will be needed in the following search scroll call
<4> Retrieve the first batch of search hits

==== Retrieve all the relevant documents

As a second step, the received scroll identifier must be set to a
`SearchScrollRequest` along with a new scroll interval and sent through the
`searchScroll` method. Elasticsearch returns another batch of results with
a new scroll identifier. This new scroll identifier can then be used in a
subsequent `SearchScrollRequest` to retrieve the next batch of results,
and so on. This process should be repeated in a loop until no more results are
returned, meaning that the scroll has been exhausted and all the matching
documents have been retrieved.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll2]
--------------------------------------------------
<1> Create the `SearchScrollRequest` by setting the required scroll id and
the scroll interval
<2> Read the new scroll id, which points to the search context that's
being kept alive and will be needed in the following search scroll call
<3> Retrieve another batch of search hits
<4>

==== Clear the scroll context

Finally, the last scroll identifier can be deleted using the <<java-rest-high-clear-scroll>>
in order to release the search context. This happens automatically when the
scroll expires, but it's good practice to do it as soon as the scroll session
is completed.

==== Optional arguments

The following arguments can optionally be provided when constructing
the `SearchScrollRequest`:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[scroll-request-arguments]
--------------------------------------------------
<1> Scroll interval as a `TimeValue`
<2> Scroll interval as a `String`

If no `scroll` value is set for the `SearchScrollRequest`, 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

The asynchronous execution of a search scroll request requires both the `SearchScrollRequest`
instance and an `ActionListener` instance to be passed to the asynchronous
method:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-async]
--------------------------------------------------
<1> The `SearchScrollRequest` to execute and the `ActionListener` to use when
the execution completes

The asynchronous method does not block and returns immediately. Once it is
completed the `ActionListener` is called back using the `onResponse` method
if the execution successfully completed or using the `onFailure` method if
it failed.

A typical listener for `SearchResponse` looks like:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-listener]
--------------------------------------------------
<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-search-scroll-response]]
==== Response

The search scroll API returns a `SearchResponse` object, same as the
Search API.

[[java-rest-high-search-scroll-example]]
==== Full example

The following is a complete example of a scrolled search.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-example]
--------------------------------------------------
<1> Initialize the search context by sending the initial `SearchRequest`
<2> Retrieve all the search hits by calling the Search Scroll api in a loop
until no documents are returned
<3> Create a new `SearchScrollRequest` holding the last returned scroll
identifier and the scroll interval
<4> Process the returned search results
<5> Clear the scroll context once the scroll is completed

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

The search contexts used by the Search 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

The asynchronous execution of a clear scroll request requires both the `ClearScrollRequest`
instance and an `ActionListener` instance to be passed to the asynchronous
method:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute-async]
--------------------------------------------------
<1> The `ClearScrollRequest` to execute and the `ActionListener` to use when
the execution completes

The asynchronous method does not block and returns immediately. Once it is
completed the `ActionListener` is called back using the `onResponse` method
if the execution successfully completed or using the `onFailure` method if
it failed.

A typical listener for `ClearScrollResponse` looks like:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute-listener]
--------------------------------------------------
<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