mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 13:08:29 +00:00
075fdc579f
With this new structure supported APIs are ordered and grouped in the same way as they are in the Elasticsearch reference docs
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> 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
|