33[[async-search]]
44=== Async search
55
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.
98
109[[submit-async-search]]
1110==== Submit async search API
1211
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>>.
1514
1615[source,console,id=submit-async-search-date-histogram-example]
1716--------------------------------------------------
@@ -33,10 +32,10 @@ POST /sales*/_async_search?size=0
3332// TEST[setup:sales]
3433// TEST[s/size=0/size=0&wait_for_completion_timeout=10s&keep_on_completion=true/]
3534
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.
4039
4140[source,console-result]
4241--------------------------------------------------
@@ -104,18 +103,17 @@ The `keep_on_completion` parameter, which defaults to `false`, can be set to
104103`true` to request that results are stored for later retrieval also when the
105104search completes within the `wait_for_completion_timeout`.
106105
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.
111109
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.
116113
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:
119117
120118* `batched_reduce_size` defaults to `5`: this affects how often partial results
121119become available, which happens whenever shard results are reduced. A partial
@@ -130,16 +128,16 @@ query get skipped.
130128supported value
131129
132130WARNING: 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`.
136134
137135[[get-async-search]]
138136==== Get async search
139137
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
143141<<can-access-resources-check,the user or API key that submitted it>>.
144142
145143[source,console,id=get-async-search-date-histogram-example]
@@ -211,25 +209,25 @@ completed the execution of the query.
211209The `wait_for_completion_timeout` parameter can also be provided when calling
212210the Get Async Search API, in order to wait for the search to be completed up
213211until 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.
217215
218216The `keep_alive` parameter specifies how long the async search should be
219217available in the cluster. When not specified, the `keep_alive` set with the
220218corresponding submit async request will be used. Otherwise, it is possible to
221219override 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.
224222
225223
226224[[get-async-search-status]]
227225==== 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>>.
233231
234232[source,console,id=get-async-search-status-example]
235233--------------------------------------------------
@@ -257,9 +255,10 @@ GET /_async_search/status/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVm
257255
258256<1> Indicates how many shards have executed the query so far.
259257
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+
263262[source,console-result]
264263--------------------------------------------------
265264{
@@ -279,7 +278,7 @@ code of the completed async search.
279278--------------------------------------------------
280279// TEST[skip: a sample output of a status of a completed async search]
281280
282- <1> Indicates that the async search was successfully completed
281+ <1> Indicates that the async search was successfully completed.
283282
284283
285284[source,console-result]
@@ -301,13 +300,14 @@ code of the completed async search.
301300--------------------------------------------------
302301// TEST[skip: a sample output of a status of a completed async search]
303302
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+
305305
306306[[delete-async-search]]
307307==== Delete async search
308308
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.
311311Otherwise, the saved search results are deleted.
312312
313313[source,console,id=delete-async-search-date-histogram-example]
0 commit comments