[[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 <> 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 <> 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 <>. ==== 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