Skip to content

[Docs] Document Scroll API for Java High Level REST Client #25554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 7, 2017
Merged

[Docs] Document Scroll API for Java High Level REST Client #25554

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e6b8eeb
[Docs] Document Scroll API for Java High Level REST Client
tlrx Jul 5, 2017
c86b5c0
Apply feedback
tlrx Jul 6, 2017
0c2d815
Apply feedback
tlrx Jul 6, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 19 additions & 19 deletions ...igh-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
import org.elasticsearch.common.unit.TimeValue;
import org.elasticsearch.common.xcontent.XContentType;
import org.elasticsearch.rest.RestStatus;
import org.elasticsearch.search.SearchHit;
import org.elasticsearch.search.SearchHits;
import org.elasticsearch.search.builder.SearchSourceBuilder;

Expand Down Expand Up @@ -100,24 +101,26 @@ public void testScroll() throws IOException {
}
{
String scrollId = lastScrollId;

// tag::search-scroll-id
SearchScrollRequest scrollRequest = new SearchScrollRequest(); // <1>
scrollRequest.scroll(TimeValue.timeValueMinutes(1L)); // <2>
scrollRequest.scrollId(scrollId); // <3>
// end::search-scroll-id

// tag::search-scroll-execute
SearchResponse searchResponse = client.searchScroll(scrollRequest); // <1>
SearchHits searchHits = searchResponse.getHits(); // <2>
String nextScrollId = searchResponse.getScrollId(); // <3>
while (true) {
Copy link
Member

@javanna javanna Jul 6, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member Author

@tlrx tlrx Jul 6, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

SearchScrollRequest scrollRequest = new SearchScrollRequest() // <1>
.scroll("60s") // <2>
.scrollId(scrollId); // <3>

SearchResponse searchResponse = client.searchScroll(scrollRequest); // <4>
scrollId = searchResponse.getScrollId(); // <5>

SearchHit[] searchHits = searchResponse.getHits().getHits(); // <6>
if (searchHits != null && searchHits.length > 0) {
// <7>
} else {
// <8>
break;
}
}
// end::search-scroll-execute

assertEquals(0, searchResponse.getFailedShards());
assertEquals(3L, searchResponse.getHits().getTotalHits());
assertEquals(1L, searchHits.getHits().length);
assertNotNull(nextScrollId);
lastScrollId = nextScrollId;
assertNotNull(scrollId);
lastScrollId = scrollId;
}
{
SearchScrollRequest scrollRequest = new SearchScrollRequest();
Expand All @@ -134,9 +137,6 @@ public void testScroll() throws IOException {

assertEquals(0, searchResponse.getFailedShards());
assertEquals(3L, searchResponse.getHits().getTotalHits());
assertEquals(1L, searchResponse.getHits().getHits().length);
assertNotNull(searchResponse.getScrollId());
lastScrollId = searchResponse.getScrollId();

// tag::search-scroll-execute-async
client.searchScrollAsync(scrollRequest, new ActionListener<SearchResponse>() {
Expand Down
41 changes: 19 additions & 22 deletions docs/java-rest/high-level/apis/scroll.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,37 +29,30 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[search-response-scroll-id
<2> Retrieve the search hits
<3> Retrieve the scroll id

This scroll id should be passed to a `SearchScrollRequest`:
This scroll id should be passed to a `SearchScrollRequest` which can be executed
using the Search Scroll API in order to retrieve the next batch of results. Then
the same process can be repeated over and over until no more results are returned.
The initial search request as well as all subsequent scroll requests return a
scroll id that can be passed to the next scroll request until results are exhausted.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-id]
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute]
--------------------------------------------------
<1> Create a new `SearchScrollRequest`
<2> Set the `scroll` parameter again to tell Elasticsearch to keep the search context
alive for another minute
<3> Set the scroll id

And the `SearchScrollRequest` can be executed using the Search Scroll API in order
to retrieve the next batch of results:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute]
--------------------------------------------------
<1> Execute the `SearchScrollRequest`
<2> Retrieve the next batch of search hits
<3> Retrieve the next scroll id to use in upcoming requests

Then the same process can be repeated over and over until no more results are
returned. The initial search request as well as all subsequent scroll requests
return a scroll id that can be passed to the next scroll request until results
are exhausted.
<4> Execute the `SearchScrollRequest`
<5> Retrieve the next scroll id to use in upcoming requests
<6> Retrieve the next batch of search hits
<7> The request returned search hits that can be processed
<8> There are no more search hits to process, the scrolling is terminated

Finally, the scroll id can be deleted using the <<java-rest-high-clear-scroll>>.

==== Optional arguments
The following arguments can optionally be provided:
The following argument can optionally be provided:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
Expand All @@ -68,6 +61,10 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[scroll-request-scroll]
<1> Scroll value (ie, the time to keep alive the search context) as a `TimeValue`
Copy link
Member

@javanna javanna Jul 6, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't realize that the scroll was optional. Maybe we should mention the default value when not specified?

<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

Expand All @@ -93,7 +90,7 @@ provided as an argument

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:
necessary anymore using the Clear Scroll API.

[[java-rest-high-clear-scroll-request]]
==== Clear Scroll Request
Expand All @@ -110,7 +107,7 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-request]
==== 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:
The scroll identifiers can be added to the request one by one:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
Expand Down Expand Up @@ -153,5 +150,5 @@ The returned `ClearScrollResponse` allows to retrieve information about the rele
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-response]
--------------------------------------------------
<1> Return true if the request succeed
<1> Return true if the request succeeded
<2> Return the number of released search contexts