Skip to content

Commit 0c2d815

Browse files
tlrxtlrx
committed
Apply feedback
1 parent c86b5c0 commit 0c2d815

File tree

2 files changed

+64
-81
lines changed

2 files changed

+64
-81
lines changed

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java‎

Lines changed: 30 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -34,14 +34,15 @@
3434
import org.elasticsearch.common.unit.TimeValue;
3535
import org.elasticsearch.common.xcontent.XContentType;
3636
import org.elasticsearch.rest.RestStatus;
37+
import org.elasticsearch.search.Scroll;
3738
import org.elasticsearch.search.SearchHit;
38-
import org.elasticsearch.search.SearchHits;
3939
import org.elasticsearch.search.builder.SearchSourceBuilder;
4040

4141
import java.io.IOException;
4242
import java.util.Arrays;
4343
import java.util.List;
4444

45+
import static org.elasticsearch.index.query.QueryBuilders.matchQuery;
4546
import static org.hamcrest.Matchers.greaterThan;
4647

4748
/**
@@ -76,55 +77,42 @@ public void testScroll() throws IOException {
7677
assertSame(bulkResponse.status(), RestStatus.OK);
7778
assertFalse(bulkResponse.hasFailures());
7879
}
79-
80-
String lastScrollId = null;
81-
8280
{
83-
// tag::search-scroll-request
84-
SearchRequest searchRequest = new SearchRequest("posts"); // <1>
85-
searchRequest.scroll(TimeValue.timeValueMinutes(1L)); // <2>
86-
// end::search-scroll-request
81+
// tag::search-scroll-example
82+
final Scroll scroll = new Scroll(TimeValue.timeValueMinutes(1L)); // <1>
8783

88-
searchRequest.source(new SearchSourceBuilder().size(1));
84+
SearchRequest searchRequest = new SearchRequest("posts"); // <2>
85+
searchRequest.source(new SearchSourceBuilder().query(matchQuery("title", "Elasticsearch")));
86+
searchRequest.scroll(scroll); // <3>
8987

90-
// tag::search-response-scroll-id
91-
SearchResponse searchResponse = client.search(searchRequest); // <1>
92-
SearchHits searchHits = searchResponse.getHits(); // <2>
93-
String scrollId = searchResponse.getScrollId(); // <3>
94-
// end::search-response-scroll-id
88+
SearchResponse searchResponse = client.search(searchRequest); // <4>
89+
String scrollId = searchResponse.getScrollId(); // <5>
9590

96-
assertEquals(0, searchResponse.getFailedShards());
97-
assertEquals(3L, searchResponse.getHits().getTotalHits());
98-
assertEquals(1L, searchHits.getHits().length);
99-
assertNotNull(scrollId);
100-
lastScrollId = scrollId;
101-
}
102-
{
103-
String scrollId = lastScrollId;
104-
// tag::search-scroll-execute
105-
while (true) {
106-
SearchScrollRequest scrollRequest = new SearchScrollRequest() // <1>
107-
.scroll("60s") // <2>
108-
.scrollId(scrollId); // <3>
109-
110-
SearchResponse searchResponse = client.searchScroll(scrollRequest); // <4>
111-
scrollId = searchResponse.getScrollId(); // <5>
112-
113-
SearchHit[] searchHits = searchResponse.getHits().getHits(); // <6>
114-
if (searchHits != null && searchHits.length > 0) {
115-
// <7>
116-
} else {
117-
// <8>
118-
break;
119-
}
91+
SearchHit[] searchHits = searchResponse.getHits().getHits(); // <6>
92+
while (searchHits != null && searchHits.length > 0) { // <7>
93+
SearchScrollRequest scrollRequest = new SearchScrollRequest() // <8>
94+
.scroll(scroll) // <9>
95+
.scrollId(scrollId); // <10>
96+
97+
searchResponse = client.searchScroll(scrollRequest); // <11>
98+
scrollId = searchResponse.getScrollId(); // <12>
99+
searchHits = searchResponse.getHits().getHits(); // <13>
120100
}
121-
// end::search-scroll-execute
122-
assertNotNull(scrollId);
123-
lastScrollId = scrollId;
101+
102+
ClearScrollRequest clearScrollRequest = new ClearScrollRequest(); // <14>
103+
clearScrollRequest.addScrollId(scrollId);
104+
client.clearScroll(clearScrollRequest);
105+
// end::search-scroll-example
124106
}
125107
{
108+
SearchRequest searchRequest = new SearchRequest();
109+
searchRequest.scroll("60s");
110+
111+
SearchResponse initialSearchResponse = client.search(searchRequest);
112+
String scrollId = initialSearchResponse.getScrollId();
113+
126114
SearchScrollRequest scrollRequest = new SearchScrollRequest();
127-
scrollRequest.scrollId(lastScrollId);
115+
scrollRequest.scrollId(scrollId);
128116

129117
// tag::scroll-request-scroll
130118
scrollRequest.scroll(TimeValue.timeValueSeconds(60L)); // <1>
@@ -151,9 +139,6 @@ public void onFailure(Exception e) {
151139
}
152140
});
153141
// end::search-scroll-execute-async
154-
}
155-
{
156-
String scrollId = lastScrollId;
157142

158143
// tag::clear-scroll-request
159144
ClearScrollRequest request = new ClearScrollRequest(); // <1>

‎docs/java-rest/high-level/apis/scroll.asciidoc‎

Lines changed: 34 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -4,52 +4,50 @@
44
The Scroll API can be used to retrieve a large number of results from
55
a search request.
66

7-
In order to use scrolling, the initial search request must define
8-
a value for the scroll parameter:
7+
In order to use scrolling, several steps need to be executed in a given order:
98

10-
["source","java",subs="attributes,callouts,macros"]
11-
--------------------------------------------------
12-
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-request]
13-
--------------------------------------------------
14-
<1> Create a new `SearchRequest`. See <<java-rest-high-search>>
15-
for more information on how to build `SearchRequest`.
16-
<2> Set the `scroll` parameter as a `TimeValue` corresponding to one minute
9+
* At first, an initial search request with a non-null `scroll` parameter must
10+
be executed. When processing this `SearchRequest`, Elasticsearch detects the
11+
presence of the `scroll` parameter and keeps the search context alive during
12+
the time defined by the parameter. Elasticsearch generates a scroll identifier
13+
associated to this search context and returns it with the first batch of search
14+
results in a `SearchResponse`.
1715

18-
When executing the `SearchRequest`, Elasticsearch detects the presence
19-
of the `scroll` parameter and keeps the search context alive during the time
20-
defined by the parameter.
16+
* As a second step, the initial scroll parameter and the new scroll identifier
17+
are set in a `SearchScrollRequest`. This request is executed using the Search
18+
Scroll API and Elasticsearch returns the second batch of results with a new
19+
scroll identifier. This new scroll id can then be used in another `SearchScrollRequest`
20+
to retrieve the next batch of results. This process can be repeated over and
21+
over until no more results are returned.
2122

22-
It then returns a `SearchResponse` that includes a scroll id:
23+
* Finally, the last scroll identifier can be deleted using the <<java-rest-high-clear-scroll>>
24+
in order to release the search context.
2325

24-
["source","java",subs="attributes,callouts,macros"]
25-
--------------------------------------------------
26-
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-response-scroll-id]
27-
--------------------------------------------------
28-
<1> Execute the `SearchRequest`
29-
<2> Retrieve the search hits
30-
<3> Retrieve the scroll id
26+
[[java-rest-high-search-scroll-example]]
27+
==== Example of Execution
3128

32-
This scroll id should be passed to a `SearchScrollRequest` which can be executed
33-
using the Search Scroll API in order to retrieve the next batch of results. Then
34-
the same process can be repeated over and over until no more results are returned.
35-
The initial search request as well as all subsequent scroll requests return a
36-
scroll id that can be passed to the next scroll request until results are exhausted.
29+
Here is an example of a scrolled search:
3730

3831
["source","java",subs="attributes,callouts,macros"]
3932
--------------------------------------------------
40-
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute]
33+
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-example]
4134
--------------------------------------------------
42-
<1> Create a new `SearchScrollRequest`
43-
<2> Set the `scroll` parameter again to tell Elasticsearch to keep the search context
35+
<1> Define a scroll parameter as a `TimeValue` corresponding to one minute
36+
<2> Create a new `SearchRequest`. See <<java-rest-high-search>>
37+
for more information on how to build `SearchRequest`.
38+
<3> Set the `scroll` parameter to the `SearchRequest`
39+
<4> Execute the `SearchRequest`
40+
<5> Retrieve the first scroll id
41+
<6> Retrieve the first batch of search hits
42+
<7> Iterate until there are no more search hits to process
43+
<8> Create a new `SearchScrollRequest`
44+
<9> Set the `scroll` parameter again to tell Elasticsearch to keep the search context
4445
alive for another minute
45-
<3> Set the scroll id
46-
<4> Execute the `SearchScrollRequest`
47-
<5> Retrieve the next scroll id to use in upcoming requests
48-
<6> Retrieve the next batch of search hits
49-
<7> The request returned search hits that can be processed
50-
<8> There are no more search hits to process, the scrolling is terminated
51-
52-
Finally, the scroll id can be deleted using the <<java-rest-high-clear-scroll>>.
46+
<10> Set the scroll id
47+
<11> Execute the `SearchScrollRequest` using the Search Scroll API
48+
<12> Retrieve the next scroll id to use in upcoming requests
49+
<13> Retrieve the next batch of search hits
50+
<14> Clear the scroll id using the <<java-rest-high-clear-scroll>>.
5351

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

0 commit comments

Comments
 (0)