221 lines
9.0 KiB
Plaintext
221 lines
9.0 KiB
Plaintext
[[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> 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
|