3
3
[[async-search]]
4
4
=== Async search
5
5
6
- The async search API let you asynchronously execute a
7
- search request, monitor its progress, and retrieve partial results
8
- as they become available.
6
+ The async search API let you asynchronously execute a search request, monitor
7
+ its progress, and retrieve partial results as they become available.
9
8
10
9
[[submit-async-search]]
11
10
==== Submit async search API
12
11
13
- Executes a search request asynchronously. It accepts the same
14
- parameters and request body as the <<search-search,search API>>.
12
+ Executes a search request asynchronously. It accepts the same parameters and
13
+ request body as the <<search-search,search API>>.
15
14
16
15
[source,console,id=submit-async-search-date-histogram-example]
17
16
--------------------------------------------------
@@ -33,10 +32,10 @@ POST /sales*/_async_search?size=0
33
32
// TEST[setup:sales]
34
33
// TEST[s/size=0/size=0&wait_for_completion_timeout=10s&keep_on_completion=true/]
35
34
36
- The response contains an identifier of the search being executed.
37
- You can use this ID to later retrieve the search's final results.
38
- The currently available search
39
- results are returned as part of the <<search-api-response-body,`response`>> object.
35
+ The response contains an identifier of the search being executed. You can use
36
+ this ID to later retrieve the search's final results. The currently available
37
+ search results are returned as part of the
38
+ <<search-api-response-body,`response`>> object.
40
39
41
40
[source,console-result]
42
41
--------------------------------------------------
@@ -104,18 +103,17 @@ The `keep_on_completion` parameter, which defaults to `false`, can be set to
104
103
`true` to request that results are stored for later retrieval also when the
105
104
search completes within the `wait_for_completion_timeout`.
106
105
107
- You can also specify how long the async search needs to be
108
- available through the `keep_alive` parameter, which defaults to `5d` (five days).
109
- Ongoing async searches and any saved search results are deleted after this
110
- period.
106
+ You can also specify how long the async search needs to be available through the
107
+ `keep_alive` parameter, which defaults to `5d` (five days). Ongoing async
108
+ searches and any saved search results are deleted after this period.
111
109
112
- NOTE: When the primary sort of the results is an indexed field, shards get
113
- sorted based on minimum and maximum value that they hold for that field,
114
- hence partial results become available following the sort criteria that
115
- was requested.
110
+ NOTE: When the primary sort of the results is an indexed field, shards get
111
+ sorted based on minimum and maximum value that they hold for that field, hence
112
+ partial results become available following the sort criteria that was requested.
116
113
117
- The submit async search API supports the same <<search-search-api-query-params,parameters>>
118
- as the search API, though some have different default values:
114
+ The submit async search API supports the same
115
+ <<search-search-api-query-params,parameters>> as the search API, though some
116
+ have different default values:
119
117
120
118
* `batched_reduce_size` defaults to `5`: this affects how often partial results
121
119
become available, which happens whenever shard results are reduced. A partial
@@ -130,16 +128,16 @@ query get skipped.
130
128
supported value
131
129
132
130
WARNING: Async search does not support <<scroll-search-results,scroll>>
133
- nor search requests that only include the <<search-suggesters,suggest section>>.
134
- {ccs} is supported only with <<ccs-min-roundtrips,`ccs_minimize_roundtrips`>>
135
- set to `false`.
131
+ nor search requests that only include the <<search-suggesters,suggest section>>.
132
+ {ccs-cap } is supported only with
133
+ <<ccs-min-roundtrips,`ccs_minimize_roundtrips`>> set to `false`.
136
134
137
135
[[get-async-search]]
138
136
==== Get async search
139
137
140
- The get async search API retrieves the results of a previously submitted
141
- async search request given its id. If the {es} {security-features} are enabled,
142
- the access to the results of a specific async search is restricted to
138
+ The get async search API retrieves the results of a previously submitted async
139
+ search request given its id. If the {es} {security-features} are enabled, the
140
+ access to the results of a specific async search is restricted to
143
141
<<can-access-resources-check,the user or API key that submitted it>>.
144
142
145
143
[source,console,id=get-async-search-date-histogram-example]
@@ -211,25 +209,25 @@ completed the execution of the query.
211
209
The `wait_for_completion_timeout` parameter can also be provided when calling
212
210
the Get Async Search API, in order to wait for the search to be completed up
213
211
until the provided timeout. Final results will be returned if available before
214
- the timeout expires, otherwise the currently available results will be
215
- returned once the timeout expires. By default no timeout is set meaning that
216
- the currently available results will be returned without any additional wait.
212
+ the timeout expires, otherwise the currently available results will be returned
213
+ once the timeout expires. By default no timeout is set meaning that the
214
+ currently available results will be returned without any additional wait.
217
215
218
216
The `keep_alive` parameter specifies how long the async search should be
219
217
available in the cluster. When not specified, the `keep_alive` set with the
220
218
corresponding submit async request will be used. Otherwise, it is possible to
221
219
override such value and extend the validity of the request. When this period
222
- expires, the search, if still running, is cancelled. If the search is
223
- completed, its saved results are deleted.
220
+ expires, the search, if still running, is cancelled. If the search is completed,
221
+ its saved results are deleted.
224
222
225
223
226
224
[[get-async-search-status]]
227
225
==== Get async search status
228
- The get async search status API, without retrieving search results, shows
229
- only the status of a previously submitted async search request given its `id`.
230
- If the {es} {security-features} are enabled, the access to the get async
231
- search status API is restricted to the
232
- <<built-in-roles, monitoring_user role>>.
226
+
227
+ The get async search status API, without retrieving search results, shows only
228
+ the status of a previously submitted async search request given its `id`. If the
229
+ {es} {security-features} are enabled, the access to the get async search status
230
+ API is restricted to the <<built-in-roles, monitoring_user role>>.
233
231
234
232
[source,console,id=get-async-search-status-example]
235
233
--------------------------------------------------
@@ -257,9 +255,10 @@ GET /_async_search/status/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVm
257
255
258
256
<1> Indicates how many shards have executed the query so far.
259
257
260
- For an async search that has been completed, the status response has
261
- an additional `completion_status` field that shows the status
262
- code of the completed async search.
258
+ For an async search that has been completed, the status response has an
259
+ additional `completion_status` field that shows the status code of the completed
260
+ async search.
261
+
263
262
[source,console-result]
264
263
--------------------------------------------------
265
264
{
@@ -279,7 +278,7 @@ code of the completed async search.
279
278
--------------------------------------------------
280
279
// TEST[skip: a sample output of a status of a completed async search]
281
280
282
- <1> Indicates that the async search was successfully completed
281
+ <1> Indicates that the async search was successfully completed.
283
282
284
283
285
284
[source,console-result]
@@ -301,13 +300,14 @@ code of the completed async search.
301
300
--------------------------------------------------
302
301
// TEST[skip: a sample output of a status of a completed async search]
303
302
304
- <1> Indicates that the async search was completed with an error
303
+ <1> Indicates that the async search was completed with an error.
304
+
305
305
306
306
[[delete-async-search]]
307
307
==== Delete async search
308
308
309
- You can use the delete async search API to manually delete an async search
310
- by ID. If the search is still running, the search request will be cancelled.
309
+ You can use the delete async search API to manually delete an async search by
310
+ ID. If the search is still running, the search request will be cancelled.
311
311
Otherwise, the saved search results are deleted.
312
312
313
313
[source,console,id=delete-async-search-date-histogram-example]
0 commit comments