Skip to content

Commit fdbf3bb

Browse files
javannajavanna
committed
[DOCS] revise high level client Search Scroll API docs (#25599)
Moved the full example at the end of the page, reduced the number of bullet points for it, and added smaller examples at the beginning of the page.
1 parent cf34daf commit fdbf3bb

File tree

2 files changed

+138
-70
lines changed

2 files changed

+138
-70
lines changed

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

Lines changed: 64 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,11 @@
3636
import org.elasticsearch.rest.RestStatus;
3737
import org.elasticsearch.search.Scroll;
3838
import org.elasticsearch.search.SearchHit;
39+
import org.elasticsearch.search.SearchHits;
3940
import org.elasticsearch.search.builder.SearchSourceBuilder;
4041

4142
import java.io.IOException;
42-
import java.util.Arrays;
43+
import java.util.Collections;
4344
import java.util.List;
4445

4546
import static org.elasticsearch.index.query.QueryBuilders.matchQuery;
@@ -78,31 +79,37 @@ public void testScroll() throws IOException {
7879
assertFalse(bulkResponse.hasFailures());
7980
}
8081
{
81-
// tag::search-scroll-example
82-
final Scroll scroll = new Scroll(TimeValue.timeValueMinutes(1L)); // <1>
83-
84-
SearchRequest searchRequest = new SearchRequest("posts"); // <2>
85-
searchRequest.source(new SearchSourceBuilder().query(matchQuery("title", "Elasticsearch")));
86-
searchRequest.scroll(scroll); // <3>
87-
88-
SearchResponse searchResponse = client.search(searchRequest); // <4>
89-
String scrollId = searchResponse.getScrollId(); // <5>
90-
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>
100-
}
101-
102-
ClearScrollRequest clearScrollRequest = new ClearScrollRequest(); // <14>
82+
int size = 1;
83+
// tag::search-scroll-init
84+
SearchRequest searchRequest = new SearchRequest("posts");
85+
SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
86+
searchSourceBuilder.query(matchQuery("title", "Elasticsearch"));
87+
searchSourceBuilder.size(size); // <1>
88+
searchRequest.source(searchSourceBuilder);
89+
searchRequest.scroll(TimeValue.timeValueMinutes(1L)); // <2>
90+
SearchResponse searchResponse = client.search(searchRequest);
91+
String scrollId = searchResponse.getScrollId(); // <3>
92+
SearchHits hits = searchResponse.getHits(); // <4>
93+
// end::search-scroll-init
94+
assertEquals(3, hits.getTotalHits());
95+
assertEquals(1, hits.getHits().length);
96+
assertNotNull(scrollId);
97+
98+
// tag::search-scroll2
99+
SearchScrollRequest scrollRequest = new SearchScrollRequest(scrollId); // <1>
100+
scrollRequest.scroll(TimeValue.timeValueSeconds(30));
101+
SearchResponse searchScrollResponse = client.searchScroll(scrollRequest);
102+
scrollId = searchScrollResponse.getScrollId(); // <2>
103+
hits = searchScrollResponse.getHits(); // <3>
104+
assertEquals(3, hits.getTotalHits());
105+
assertEquals(1, hits.getHits().length);
106+
assertNotNull(scrollId);
107+
// end::search-scroll2
108+
109+
ClearScrollRequest clearScrollRequest = new ClearScrollRequest();
103110
clearScrollRequest.addScrollId(scrollId);
104-
client.clearScroll(clearScrollRequest);
105-
// end::search-scroll-example
111+
ClearScrollResponse clearScrollResponse = client.clearScroll(clearScrollRequest);
112+
assertTrue(clearScrollResponse.isSucceeded());
106113
}
107114
{
108115
SearchRequest searchRequest = new SearchRequest();
@@ -114,10 +121,10 @@ public void testScroll() throws IOException {
114121
SearchScrollRequest scrollRequest = new SearchScrollRequest();
115122
scrollRequest.scrollId(scrollId);
116123

117-
// tag::scroll-request-scroll
124+
// tag::scroll-request-arguments
118125
scrollRequest.scroll(TimeValue.timeValueSeconds(60L)); // <1>
119126
scrollRequest.scroll("60s"); // <2>
120-
// end::scroll-request-scroll
127+
// end::scroll-request-arguments
121128

122129
// tag::search-scroll-execute-sync
123130
SearchResponse searchResponse = client.searchScroll(scrollRequest);
@@ -149,7 +156,7 @@ public void onFailure(Exception e) {
149156
request.addScrollId(scrollId);
150157
// end::clear-scroll-add-scroll-id
151158

152-
List<String> scrollIds = Arrays.asList(scrollId);
159+
List<String> scrollIds = Collections.singletonList(scrollId);
153160

154161
// tag::clear-scroll-add-scroll-ids
155162
request.setScrollIds(scrollIds);
@@ -180,5 +187,34 @@ public void onFailure(Exception e) {
180187
});
181188
// end::clear-scroll-execute-async
182189
}
190+
{
191+
// tag::search-scroll-example
192+
final Scroll scroll = new Scroll(TimeValue.timeValueMinutes(1L));
193+
SearchRequest searchRequest = new SearchRequest("posts");
194+
searchRequest.scroll(scroll);
195+
SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
196+
searchSourceBuilder.query(matchQuery("title", "Elasticsearch"));
197+
searchRequest.source(searchSourceBuilder);
198+
199+
SearchResponse searchResponse = client.search(searchRequest); // <1>
200+
String scrollId = searchResponse.getScrollId();
201+
SearchHit[] searchHits = searchResponse.getHits().getHits();
202+
203+
while (searchHits != null && searchHits.length > 0) { // <2>
204+
SearchScrollRequest scrollRequest = new SearchScrollRequest(scrollId); // <3>
205+
scrollRequest.scroll(scroll);
206+
searchResponse = client.searchScroll(scrollRequest);
207+
scrollId = searchResponse.getScrollId();
208+
searchHits = searchResponse.getHits().getHits();
209+
// <4>
210+
}
211+
212+
ClearScrollRequest clearScrollRequest = new ClearScrollRequest(); // <5>
213+
clearScrollRequest.addScrollId(scrollId);
214+
ClearScrollResponse clearScrollResponse = client.clearScroll(clearScrollRequest);
215+
boolean succeeded = clearScrollResponse.isSucceeded();
216+
// end::search-scroll-example
217+
assertTrue(succeeded);
218+
}
183219
}
184220
}

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

Lines changed: 74 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -4,63 +4,73 @@
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, several steps need to be executed in a given order:
7+
In order to use scrolling, the following steps need to be executed in the
8+
given order.
89

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`.
1510

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.
11+
==== Initialize the search scroll context
2212

23-
* Finally, the last scroll identifier can be deleted using the <<java-rest-high-clear-scroll>>
24-
in order to release the search context.
13+
An initial search request with a `scroll` parameter must be executed to
14+
initialize the scroll session through the <<java-rest-high-search>>.
15+
When processing this `SearchRequest`, Elasticsearch detects the presence of
16+
the `scroll` parameter and keeps the search context alive for the
17+
corresponding time interval.
2518

26-
[[java-rest-high-search-scroll-example]]
27-
==== Example of Execution
19+
["source","java",subs="attributes,callouts,macros"]
20+
--------------------------------------------------
21+
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-init]
22+
--------------------------------------------------
23+
<1> Create the `SearchRequest` and its corresponding `SearchSourceBuilder`.
24+
Also optionally set the `size` to control how many results to retrieve at
25+
a time.
26+
<2> Set the scroll interval
27+
<3> Read the returned scroll id, which points to the search context that's
28+
being kept alive and will be needed in the following search scroll call
29+
<4> Retrieve the first batch of search hits
30+
31+
==== Retrieve all the relevant documents
2832

29-
Here is an example of a scrolled search:
33+
As a second step, the received scroll identifier must be set to a
34+
`SearchScrollRequest` along with a new scroll interval and sent through the
35+
`searchScroll` method. Elasticsearch returns another batch of results with
36+
a new scroll identifier. This new scroll identifier can then be used in a
37+
subsequent `SearchScrollRequest` to retrieve the next batch of results,
38+
and so on. This process should be repeated in a loop until no more results are
39+
returned, meaning that the scroll has been exhausted and all the matching
40+
documents have been retrieved.
3041

3142
["source","java",subs="attributes,callouts,macros"]
3243
--------------------------------------------------
33-
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-example]
44+
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll2]
3445
--------------------------------------------------
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
45-
alive for another minute
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>>.
46+
<1> Create the `SearchScrollRequest` by setting the required scroll id and
47+
the scroll interval
48+
<2> Read the new scroll id, which points to the search context that's
49+
being kept alive and will be needed in the following search scroll call
50+
<3> Retrieve another batch of search hits
51+
<4>
52+
53+
==== Clear the scroll context
54+
55+
Finally, the last scroll identifier can be deleted using the <<java-rest-high-clear-scroll>>
56+
in order to release the search context. This happens automatically when the
57+
scroll expires, but it's good practice to do it as soon as the scroll session
58+
is completed.
5159

5260
==== Optional arguments
53-
The following argument can optionally be provided:
61+
62+
The following arguments can optionally be provided when constructing
63+
the `SearchScrollRequest`:
5464

5565
["source","java",subs="attributes,callouts,macros"]
5666
--------------------------------------------------
57-
include-tagged::{doc-tests}/SearchDocumentationIT.java[scroll-request-scroll]
67+
include-tagged::{doc-tests}/SearchDocumentationIT.java[scroll-request-arguments]
5868
--------------------------------------------------
59-
<1> Scroll value (ie, the time to keep alive the search context) as a `TimeValue`
60-
<2> Scroll value (ie, the time to keep alive the search context) as a `String`
69+
<1> Scroll interval as a `TimeValue`
70+
<2> Scroll interval as a `String`
6171

62-
If no `scroll` value is set for the `SearchScrollRequest`, then the search context
63-
will expire once the initial scroll time expired (ie, the scroll time set in the
72+
If no `scroll` value is set for the `SearchScrollRequest`, the search context will
73+
expire once the initial scroll time expired (ie, the scroll time set in the
6474
initial search request).
6575

6676
[[java-rest-high-search-scroll-sync]]
@@ -82,11 +92,33 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-asy
8292
provided as an argument
8393
<2> Called in case of failure. The raised exception is provided as an argument
8494

95+
[[java-rest-high-search-scroll-response]]
96+
==== Response
97+
98+
The search scroll API returns a `SearchResponse` object, same as the
99+
Search API.
100+
101+
[[java-rest-high-search-scroll-example]]
102+
==== Full example
103+
104+
The following is a complete example of a scrolled search.
105+
106+
["source","java",subs="attributes,callouts,macros"]
107+
--------------------------------------------------
108+
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-example]
109+
--------------------------------------------------
110+
<1> Initialize the search context by sending the initial `SearchRequest`
111+
<2> Retrieve all the search hits by calling the Search Scroll api in a loop
112+
until no documents are returned
113+
<3> Create a new `SearchScrollRequest` holding the last returned scroll
114+
identifier and the scroll interval
115+
<4> Process the returned search results
116+
<5> Clear the scroll context once the scroll is completed
85117

86118
[[java-rest-high-clear-scroll]]
87119
=== Clear Scroll API
88120

89-
The search contexts used by the Scroll API are automatically deleted when the scroll
121+
The search contexts used by the Search Scroll API are automatically deleted when the scroll
90122
times out. But it is advised to release search contexts as soon as they are not
91123
necessary anymore using the Clear Scroll API.
92124

0 commit comments

Comments
 (0)