Skip to content

Commit b06a744

Browse files
tlrxjavanna
tlrx
authored and
javanna
committed
[Docs] Document Scroll API for Java High Level REST Client (#25554)
This commit adds documentation for _search/scroll and clear scroll methods of the high level Java REST client
1 parent 2e5e451 commit b06a744

File tree

6 files changed

+345
-5
lines changed

6 files changed

+345
-5
lines changed

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

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
/*
2+
* Licensed to Elasticsearch under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.elasticsearch.client.documentation;
21+
22+
import org.elasticsearch.action.ActionListener;
23+
import org.elasticsearch.action.bulk.BulkRequest;
24+
import org.elasticsearch.action.bulk.BulkResponse;
25+
import org.elasticsearch.action.index.IndexRequest;
26+
import org.elasticsearch.action.search.ClearScrollRequest;
27+
import org.elasticsearch.action.search.ClearScrollResponse;
28+
import org.elasticsearch.action.search.SearchRequest;
29+
import org.elasticsearch.action.search.SearchResponse;
30+
import org.elasticsearch.action.search.SearchScrollRequest;
31+
import org.elasticsearch.action.support.WriteRequest;
32+
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
33+
import org.elasticsearch.client.RestHighLevelClient;
34+
import org.elasticsearch.common.unit.TimeValue;
35+
import org.elasticsearch.common.xcontent.XContentType;
36+
import org.elasticsearch.rest.RestStatus;
37+
import org.elasticsearch.search.Scroll;
38+
import org.elasticsearch.search.SearchHit;
39+
import org.elasticsearch.search.builder.SearchSourceBuilder;
40+
41+
import java.io.IOException;
42+
import java.util.Arrays;
43+
import java.util.List;
44+
45+
import static org.elasticsearch.index.query.QueryBuilders.matchQuery;
46+
import static org.hamcrest.Matchers.greaterThan;
47+
48+
/**
49+
* This class is used to generate the Java High Level REST Client Search API documentation.
50+
* <p>
51+
* You need to wrap your code between two tags like:
52+
* // tag::example[]
53+
* // end::example[]
54+
* <p>
55+
* Where example is your tag name.
56+
* <p>
57+
* Then in the documentation, you can extract what is between tag and end tags with
58+
* ["source","java",subs="attributes,callouts,macros"]
59+
* --------------------------------------------------
60+
* include-tagged::{doc-tests}/SearchDocumentationIT.java[example]
61+
* --------------------------------------------------
62+
*/
63+
public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
64+
65+
public void testScroll() throws IOException {
66+
RestHighLevelClient client = highLevelClient();
67+
{
68+
BulkRequest request = new BulkRequest();
69+
request.add(new IndexRequest("posts", "doc", "1")
70+
.source(XContentType.JSON, "title", "In which order are my Elasticsearch queries executed?"));
71+
request.add(new IndexRequest("posts", "doc", "2")
72+
.source(XContentType.JSON, "title", "Current status and upcoming changes in Elasticsearch"));
73+
request.add(new IndexRequest("posts", "doc", "3")
74+
.source(XContentType.JSON, "title", "The Future of Federated Search in Elasticsearch"));
75+
request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL);
76+
BulkResponse bulkResponse = client.bulk(request);
77+
assertSame(bulkResponse.status(), RestStatus.OK);
78+
assertFalse(bulkResponse.hasFailures());
79+
}
80+
{
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>
103+
clearScrollRequest.addScrollId(scrollId);
104+
client.clearScroll(clearScrollRequest);
105+
// end::search-scroll-example
106+
}
107+
{
108+
SearchRequest searchRequest = new SearchRequest();
109+
searchRequest.scroll("60s");
110+
111+
SearchResponse initialSearchResponse = client.search(searchRequest);
112+
String scrollId = initialSearchResponse.getScrollId();
113+
114+
SearchScrollRequest scrollRequest = new SearchScrollRequest();
115+
scrollRequest.scrollId(scrollId);
116+
117+
// tag::scroll-request-scroll
118+
scrollRequest.scroll(TimeValue.timeValueSeconds(60L)); // <1>
119+
scrollRequest.scroll("60s"); // <2>
120+
// end::scroll-request-scroll
121+
122+
// tag::search-scroll-execute-sync
123+
SearchResponse searchResponse = client.searchScroll(scrollRequest);
124+
// end::search-scroll-execute-sync
125+
126+
assertEquals(0, searchResponse.getFailedShards());
127+
assertEquals(3L, searchResponse.getHits().getTotalHits());
128+
129+
// tag::search-scroll-execute-async
130+
client.searchScrollAsync(scrollRequest, new ActionListener<SearchResponse>() {
131+
@Override
132+
public void onResponse(SearchResponse searchResponse) {
133+
// <1>
134+
}
135+
136+
@Override
137+
public void onFailure(Exception e) {
138+
// <2>
139+
}
140+
});
141+
// end::search-scroll-execute-async
142+
143+
// tag::clear-scroll-request
144+
ClearScrollRequest request = new ClearScrollRequest(); // <1>
145+
request.addScrollId(scrollId); // <2>
146+
// end::clear-scroll-request
147+
148+
// tag::clear-scroll-add-scroll-id
149+
request.addScrollId(scrollId);
150+
// end::clear-scroll-add-scroll-id
151+
152+
List<String> scrollIds = Arrays.asList(scrollId);
153+
154+
// tag::clear-scroll-add-scroll-ids
155+
request.setScrollIds(scrollIds);
156+
// end::clear-scroll-add-scroll-ids
157+
158+
// tag::clear-scroll-execute
159+
ClearScrollResponse response = client.clearScroll(request);
160+
// end::clear-scroll-execute
161+
162+
// tag::clear-scroll-response
163+
boolean success = response.isSucceeded(); // <1>
164+
int released = response.getNumFreed(); // <2>
165+
// end::clear-scroll-response
166+
assertTrue(success);
167+
assertThat(released, greaterThan(0));
168+
169+
// tag::clear-scroll-execute-async
170+
client.clearScrollAsync(request, new ActionListener<ClearScrollResponse>() {
171+
@Override
172+
public void onResponse(ClearScrollResponse clearScrollResponse) {
173+
// <1>
174+
}
175+
176+
@Override
177+
public void onFailure(Exception e) {
178+
// <2>
179+
}
180+
});
181+
// end::clear-scroll-execute-async
182+
}
183+
}
184+
}

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,6 @@ The Java High Level REST Client supports the following APIs:
1212
* <<java-rest-high-document-bulk>>
1313
1414
.Search APIs
15-
* Search API
16-
* Search Scroll API
17-
* Clear Scroll API
15+
* <<java-rest-high-search>>
16+
* <<java-rest-high-search-scroll>>
17+
* <<java-rest-high-clear-scroll>>

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

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -147,5 +147,3 @@ same index, type and id already existed:
147147
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-optype]
148148
--------------------------------------------------
149149
<1> The raised exception indicates that a version conflict error was returned
150-
151-

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,7 @@ include::get.asciidoc[]
55
include::delete.asciidoc[]
66
include::update.asciidoc[]
77
include::bulk.asciidoc[]
8+
include::search.asciidoc[]
9+
include::scroll.asciidoc[]
810

911
:doc-tests!:

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

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
[[java-rest-high-search-scroll]]
2+
=== Search Scroll API
3+
4+
The Scroll API can be used to retrieve a large number of results from
5+
a search request.
6+
7+
In order to use scrolling, several steps need to be executed in a given order:
8+
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`.
15+
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.
22+
23+
* Finally, the last scroll identifier can be deleted using the <<java-rest-high-clear-scroll>>
24+
in order to release the search context.
25+
26+
[[java-rest-high-search-scroll-example]]
27+
==== Example of Execution
28+
29+
Here is an example of a scrolled search:
30+
31+
["source","java",subs="attributes,callouts,macros"]
32+
--------------------------------------------------
33+
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-example]
34+
--------------------------------------------------
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>>.
51+
52+
==== Optional arguments
53+
The following argument can optionally be provided:
54+
55+
["source","java",subs="attributes,callouts,macros"]
56+
--------------------------------------------------
57+
include-tagged::{doc-tests}/SearchDocumentationIT.java[scroll-request-scroll]
58+
--------------------------------------------------
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`
61+
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
64+
initial search request).
65+
66+
[[java-rest-high-search-scroll-sync]]
67+
==== Synchronous Execution
68+
69+
["source","java",subs="attributes,callouts,macros"]
70+
--------------------------------------------------
71+
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-sync]
72+
--------------------------------------------------
73+
74+
[[java-rest-high-search-scroll-async]]
75+
==== Asynchronous Execution
76+
77+
["source","java",subs="attributes,callouts,macros"]
78+
--------------------------------------------------
79+
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-async]
80+
--------------------------------------------------
81+
<1> Called when the execution is successfully completed. The response is
82+
provided as an argument
83+
<2> Called in case of failure. The raised exception is provided as an argument
84+
85+
86+
[[java-rest-high-clear-scroll]]
87+
=== Clear Scroll API
88+
89+
The search contexts used by the Scroll API are automatically deleted when the scroll
90+
times out. But it is advised to release search contexts as soon as they are not
91+
necessary anymore using the Clear Scroll API.
92+
93+
[[java-rest-high-clear-scroll-request]]
94+
==== Clear Scroll Request
95+
96+
A `ClearScrollRequest` can be created as follows:
97+
98+
["source","java",subs="attributes,callouts,macros"]
99+
--------------------------------------------------
100+
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-request]
101+
--------------------------------------------------
102+
<1> Create a new `ClearScrollRequest`
103+
<2> Adds a scroll id to the list of scroll identifiers to clear
104+
105+
==== Providing the scroll identifiers
106+
The `ClearScrollRequest` allows to clear one or more scroll identifiers in a single request.
107+
108+
The scroll identifiers can be added to the request one by one:
109+
110+
["source","java",subs="attributes,callouts,macros"]
111+
--------------------------------------------------
112+
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-add-scroll-id]
113+
--------------------------------------------------
114+
115+
Or all together using:
116+
117+
["source","java",subs="attributes,callouts,macros"]
118+
--------------------------------------------------
119+
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-add-scroll-ids]
120+
--------------------------------------------------
121+
122+
[[java-rest-high-clear-scroll-sync]]
123+
==== Synchronous Execution
124+
125+
["source","java",subs="attributes,callouts,macros"]
126+
--------------------------------------------------
127+
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute]
128+
--------------------------------------------------
129+
130+
[[java-rest-high-clear-scroll-async]]
131+
==== Asynchronous Execution
132+
133+
["source","java",subs="attributes,callouts,macros"]
134+
--------------------------------------------------
135+
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute-async]
136+
--------------------------------------------------
137+
<1> Called when the execution is successfully completed. The response is
138+
provided as an argument
139+
<2> Called in case of failure. The raised exception is provided as an argument
140+
141+
[[java-rest-high-clear-scroll-response]]
142+
==== Clear Scroll Response
143+
144+
The returned `ClearScrollResponse` allows to retrieve information about the released
145+
search contexts:
146+
147+
["source","java",subs="attributes,callouts,macros"]
148+
--------------------------------------------------
149+
include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-response]
150+
--------------------------------------------------
151+
<1> Return true if the request succeeded
152+
<2> Return the number of released search contexts

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[[java-rest-high-search]]
2+
=== Search API
3+
4+
To be documented.

0 commit comments

Comments
 (0)