[[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 <>. 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 <> 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> Process the returned search results <4> Create a new `SearchScrollRequest` holding the last returned scroll identifier and the scroll interval <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