[Docs] Document Scroll API for Java High Level REST Client #25554
Conversation
| // end::search-scroll-id | ||
|
|
||
| // tag::search-scroll-execute | ||
| SearchResponse searchResponse = client.searchScroll(scrollRequest); // <1> |
There was a problem hiding this comment.
shall we have the scroll execute in a loop instead? for both sync and async, so we have a complete example on how users are supposed to use it?
There was a problem hiding this comment.
I changed things a bit to use a loop in the main example (the sync / async parts remain the same) as I find it useful and easy to understand. But it gets more complex using async and the boilerplate code make things harder to read.
I think I changed to a good compromise, let me know what you think
| -------------------------------------------------- | ||
| include-tagged::{doc-tests}/SearchDocumentationIT.java[scroll-request-scroll] | ||
| -------------------------------------------------- | ||
| <1> Scroll value (ie, the time to keep alive the search context) as a `TimeValue` |
There was a problem hiding this comment.
I didn't realize that the scroll was optional. Maybe we should mention the default value when not specified?
|
|
||
| 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: |
| ==== Providing the scroll identifiers | ||
| The `ClearScrollRequest` allows to clear one or more scroll identifiers in a single request. | ||
|
|
||
| The scroll identifier can be added to the request one by one: |
| -------------------------------------------------- | ||
| include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-response] | ||
| -------------------------------------------------- | ||
| <1> Return true if the request succeed |
| SearchResponse searchResponse = client.searchScroll(scrollRequest); // <1> | ||
| SearchHits searchHits = searchResponse.getHits(); // <2> | ||
| String nextScrollId = searchResponse.getScrollId(); // <3> | ||
| while (true) { |
There was a problem hiding this comment.
how about having a complete example with the initial search response too? Maybe leave a separate search scroll snippet, then move to the complete example where you reuse the SearchHits from the initial SearchResponse and you could do while(searchHits != null && searchHits.length > 0) instead of while(true)? Would that work or would it be too complicated?
There was a problem hiding this comment.
Ok, I updated the doc in 0c2d815, let me know if this is OK or not.
I'm personally fine with the latest version as well as the previous one too, just let me know which one seems better to you.
This commit adds documentation for _search/scroll and clear scroll methods of the high level Java REST client
|
Thanks @javanna |
* master: (42 commits) Harden global checkpoint tracker Remove deprecated created and found from index, delete and bulk (elastic#25516) fix testEnsureVersionCompatibility for 5.5.0 release fix Version.v6_0_0 min compatibility version to 5.5.0 Add bwc indices for 5.5.0 Add v5_5_1 constant [DOCS] revise high level client Search Scroll API docs (elastic#25599) Improve REST error handling when endpoint does not support HTTP verb, add OPTIONS support (elastic#24437) Avoid SecurityException in repository-S3 on DefaultS3OutputStream.flush() (elastic#25254) [Tests] Add tests for CompletionSuggestionBuilder#build() (elastic#25575) Enable cross-setting validation [Docs] Fix typo in bootstrap-checks.asciidoc (elastic#25597) Index ids in binary form. (elastic#25352) bwc checkout should fetch from all remotes IndexingIT should check for global checkpoints regardless of master version [Tests] Add tests for PhraseSuggestionBuilder#build() (elastic#25571) Remove unused class MinimalMap (elastic#25590) [Docs] Document Scroll API for Java High Level REST Client (elastic#25554) Disable date field mapping changing (elastic#25285) Allow BWC Testing against a specific branch (elastic#25510) ...
This PR adds documentation for both search and clear scroll APIs in the high level REST client.