Skip to content

[7.11] [DOCS] Fixes typo in async search API docs. (#70448) #70459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 17, 2021
Merged

[7.11] [DOCS] Fixes typo in async search API docs. (#70448) #70459

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 39 additions & 39 deletions docs/reference/search/async-search.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,14 @@
[[async-search]]
=== Async search

The async search API let you asynchronously execute a
search request, monitor its progress, and retrieve partial results
as they become available.
The async search API let you asynchronously execute a search request, monitor
its progress, and retrieve partial results as they become available.

[[submit-async-search]]
==== Submit async search API

Executes a search request asynchronously. It accepts the same
parameters and request body as the <<search-search,search API>>.
Executes a search request asynchronously. It accepts the same parameters and
request body as the <<search-search,search API>>.

[source,console,id=submit-async-search-date-histogram-example]
--------------------------------------------------
Expand All @@ -33,10 +32,10 @@ POST /sales*/_async_search?size=0
// TEST[setup:sales]
// TEST[s/size=0/size=0&wait_for_completion_timeout=10s&keep_on_completion=true/]

The response contains an identifier of the search being executed.
You can use this ID to later retrieve the search's final results.
The currently available search
results are returned as part of the <<search-api-response-body,`response`>> object.
The response contains an identifier of the search being executed. You can use
this ID to later retrieve the search's final results. The currently available
search results are returned as part of the
<<search-api-response-body,`response`>> object.

[source,console-result]
--------------------------------------------------
Expand Down Expand Up @@ -104,18 +103,17 @@ The `keep_on_completion` parameter, which defaults to `false`, can be set to
`true` to request that results are stored for later retrieval also when the
search completes within the `wait_for_completion_timeout`.

You can also specify how long the async search needs to be
available through the `keep_alive` parameter, which defaults to `5d` (five days).
Ongoing async searches and any saved search results are deleted after this
period.
You can also specify how long the async search needs to be available through the
`keep_alive` parameter, which defaults to `5d` (five days). Ongoing async
searches and any saved search results are deleted after this period.

NOTE: When the primary sort of the results is an indexed field, shards get
sorted based on minimum and maximum value that they hold for that field,
hence partial results become available following the sort criteria that
was requested.
NOTE: When the primary sort of the results is an indexed field, shards get
sorted based on minimum and maximum value that they hold for that field, hence
partial results become available following the sort criteria that was requested.

The submit async search API supports the same <<search-search-api-query-params,parameters>>
as the search API, though some have different default values:
The submit async search API supports the same
<<search-search-api-query-params,parameters>> as the search API, though some
have different default values:

* `batched_reduce_size` defaults to `5`: this affects how often partial results
become available, which happens whenever shard results are reduced. A partial
Expand All @@ -130,9 +128,9 @@ query get skipped.
supported value

WARNING: Async search does not support <<scroll-search-results,scroll>>
nor search requests that only include the <<search-suggesters,suggest section>>.
{ccs} is supported only with <<ccs-min-roundtrips,`ccs_minimize_roundtrips`>>
set to `false`.
nor search requests that only include the <<search-suggesters,suggest section>>.
{ccs-cap} is supported only with
<<ccs-min-roundtrips,`ccs_minimize_roundtrips`>> set to `false`.

[[get-async-search]]
==== Get async search
Expand Down Expand Up @@ -211,25 +209,25 @@ completed the execution of the query.
The `wait_for_completion_timeout` parameter can also be provided when calling
the Get Async Search API, in order to wait for the search to be completed up
until the provided timeout. Final results will be returned if available before
the timeout expires, otherwise the currently available results will be
returned once the timeout expires. By default no timeout is set meaning that
the currently available results will be returned without any additional wait.
the timeout expires, otherwise the currently available results will be returned
once the timeout expires. By default no timeout is set meaning that the
currently available results will be returned without any additional wait.

The `keep_alive` parameter specifies how long the async search should be
available in the cluster. When not specified, the `keep_alive` set with the
corresponding submit async request will be used. Otherwise, it is possible to
override such value and extend the validity of the request. When this period
expires, the search, if still running, is cancelled. If the search is
completed, its saved results are deleted.
expires, the search, if still running, is cancelled. If the search is completed,
its saved results are deleted.


[[get-async-search-status]]
==== Get async search status
The get async search status API, without retrieving search results, shows
only the status of a previously submitted async search request given its `id`.
If the {es} {security-features} are enabled, the access to the get async
search status API is restricted to the
<<built-in-roles, monitoring_user role>>.

The get async search status API, without retrieving search results, shows only
the status of a previously submitted async search request given its `id`. If the
{es} {security-features} are enabled, the access to the get async search status
API is restricted to the <<built-in-roles, monitoring_user role>>.

[source,console,id=get-async-search-status-example]
--------------------------------------------------
Expand Down Expand Up @@ -257,9 +255,10 @@ GET /_async_search/status/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVm

<1> Indicates how many shards have executed the query so far.

For an async search that has been completed, the status response has
an additional `completion_status` field that shows the status
code of the completed async search.
For an async search that has been completed, the status response has an
additional `completion_status` field that shows the status code of the completed
async search.

[source,console-result]
--------------------------------------------------
{
Expand All @@ -279,7 +278,7 @@ code of the completed async search.
--------------------------------------------------
// TEST[skip: a sample output of a status of a completed async search]

<1> Indicates that the async search was successfully completed
<1> Indicates that the async search was successfully completed.


[source,console-result]
Expand All @@ -301,13 +300,14 @@ code of the completed async search.
--------------------------------------------------
// TEST[skip: a sample output of a status of a completed async search]

<1> Indicates that the async search was completed with an error
<1> Indicates that the async search was completed with an error.


[[delete-async-search]]
==== Delete async search

You can use the delete async search API to manually delete an async search
by ID. If the search is still running, the search request will be cancelled.
You can use the delete async search API to manually delete an async search by
ID. If the search is still running, the search request will be cancelled.
Otherwise, the saved search results are deleted.

[source,console,id=delete-async-search-date-histogram-example]
Expand Down