Run an async search

POST /{index}/_async_search
POST /_async_search

Auth

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. Partial results become available following the sort criteria that was requested.

Warning

Asynchronous search does not support scroll or search requests that include only the suggest section.

By default, Elasticsearch does not allow you to store an async search response larger than 10Mb and an attempt to do this results in an error. The maximum allowed size for a stored async search response can be set by changing the search.max_async_search_response_size cluster level setting.

Required privileges

Index privileges read

Path parameters

index union string | string[] optional

A comma-separated list of index names to search; use _all or empty string to perform the operation on all indices

Leave it out to use /_async_search.

Query parameters

wait_for_completion_timeout union oneOf · default: 1s

Blocks and waits until the search is completed up to a certain timeout. When the async search completes within the timeout, the response won’t include the ID as the results are not stored in the cluster.

Values: -1 0

keep_alive union oneOf · default: 5d

Specifies how long the async search needs to be available. Ongoing async searches and any saved search results are deleted after this period.

Values: -1 0

keep_on_completion boolean · default: false

If true, results are stored for later retrieval when the search completes within the wait_for_completion_timeout.

allow_no_indices boolean

A setting that does two separate checks on the index expression. If false, the request returns an error (1) if any wildcard expression (including _all and *) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. If true, index expressions that resolve to no indices are allowed and the request returns an empty result.

allow_partial_search_results boolean · default: true

Indicate if an error should be returned if there is a partial search failure or timeout

analyzer string

The analyzer to use for the query string

analyze_wildcard boolean · default: false

Specify whether wildcard and prefix queries should be analyzed

batched_reduce_size number · default: 5

Affects how often partial results become available, which happens whenever shard results are reduced. A partial reduction is performed every time the coordinating node has received a certain number of new shard responses (5 by default).

ccs_minimize_roundtrips boolean · default: false

The default value is the only supported value.

default_operator enum · default: or

The default operator for query string query (AND or OR)

Values: and AND or OR

df string

The field to use as default where no field prefix is given in the query string

docvalue_fields union string | string[]

A comma-separated list of fields to return as the docvalue representation of a field for each hit

expand_wildcards union oneOf · default: open

Whether to expand wildcard expression to concrete indices that are open, closed or both

Supported values include:

all: Match any data stream or index, including hidden ones.
open: Match open, non-hidden indices. Also matches any non-hidden data stream.
closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
none: Wildcard expressions are not accepted.

Values: all open closed hidden none

explain boolean

Specify whether to return detailed information about score computation as part of a hit

ignore_throttled boolean

Whether specified concrete, expanded or aliased indices should be ignored when throttled

ignore_unavailable boolean

If false, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. If true, unavailable concrete targets are silently ignored.

lenient boolean

Specify whether format-based query failures (such as providing text to a numeric field) should be ignored

max_concurrent_shard_requests number · default: 5

The number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests

preference string · default: random

Specify the node or shard the operation should be performed on

request_cache boolean · default: true

Specify if request cache should be used for this request or not, defaults to true

routing union string | string[]

A comma-separated list of specific routing values

search_type enum

Search operation type

Supported values include:

query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.

Values: query_then_fetch dfs_query_then_fetch

stats string[]

Specific 'tag' of the request for logging and statistical purposes

stored_fields union string | string[]

A comma-separated list of stored fields to return as part of a hit

suggest_field string

Specifies which field to use for suggestions.

suggest_mode enum · default: missing

Specify suggest mode

Supported values include:

missing: Only generate suggestions for terms that are not in the shard.
popular: Only suggest terms that occur in more docs on the shard than the original term.
always: Suggest any matching suggestions based on terms in the suggest text.

Values: missing popular always

suggest_size number

How many suggestions to return in response

suggest_text string

The source text for which the suggestions should be returned.

terminate_after number

The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early

timeout union oneOf

Explicit operation timeout

Values: -1 0

Reference

track_total_hits boolean | number

Indicate if the number of documents that match the query should be tracked. A number can also be specified, to accurately track the total hit count up to the number.

track_scores boolean

Whether to calculate and return scores even if they are not used for sorting

typed_keys boolean

Specify whether aggregation and suggester names should be prefixed by their respective types in the response

rest_total_hits_as_int boolean · default: false

Indicates whether hits.total should be rendered as an integer or an object in the rest search response

version boolean

Specify whether to return document version as part of a hit

_source union oneOf

True or false to return the _source field or not, or a list of fields to return

One of: boolean or string

_source_excludes union string | string[]

A list of fields to exclude from the returned _source field

_source_includes union string | string[]

A list of fields to extract and return from the _source field

seq_no_primary_term boolean

Specify whether to return sequence number and primary term of the last modification of each hit

q string

Query in the Lucene query string syntax

size number · default: 10

Number of hits to return

from number · default: 0

Starting offset

sort union string | string[]

A comma-separated list of

Request body

aggregations map string to {} Aggregation
collapse object
explain boolean · default: false: If true, returns detailed information about score computation as part of a hit.
ext map string to object: Configuration of search extensions defined by Elasticsearch plugins.
from number · default: 0: Starting document offset. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
highlight object: Same fields as highlight in inner_hits
track_total_hits boolean | number: Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
indices_boost string to number[]: Boosts the _score of documents from specified indices.
docvalue_fields object[]: Array of wildcard (*) patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
knn union oneOf: Defines the approximate kNN search to run.; object or object[]
min_score number: Minimum _score for matching documents. Documents with a lower _score are not included in search results and results collected by aggregations.
post_filter {} Query
profile boolean
query {} Query: Defines the search definition using the Query DSL.
rescore union oneOf: object or object[]
script_fields map string to object: Retrieve a script evaluation (based on different fields) for each hit.
search_after union[]
size number · default: 10: The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
slice object
sort union oneOf: Same options as sort in inner_hits
_source union oneOf: Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.; One of:
fields object[]: Array of wildcard (*) patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
suggest object
terminate_after number · default: 0: Maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting. Defaults to 0, which does not terminate query execution early.
timeout string: Specifies the period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
track_scores boolean · default: false: If true, calculate and return document scores, even if the scores are not used for sorting.
version boolean · default: false: If true, returns document version as part of a hit.
seq_no_primary_term boolean: If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.
stored_fields union oneOf: List of stored fields to return as part of a hit. If no fields are specified, no stored fields are included in the response. If this field is specified, the _source parameter defaults to false. You can pass _source: true to return both source fields and stored fields in the search response.; One of: string[] or string
pit object: Limits the search to a point in time (PIT). If you provide a PIT, you cannot specify an
runtime_mappings object: Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.
stats string[]: Stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

application/json

id string
is_partial boolean required: When the query is no longer running, this property indicates whether the search failed or was successfully completed on all shards. While the query is running, is_partial is always set to true.
is_running boolean required: Indicates whether the search is still running or has completed.

Note

If the search failed after some shards returned their results or the node that is coordinating the async search dies, results may be partial even though is_running is false.
expiration_time union oneOf: Indicates when the async search will expire.; One of: string or number
expiration_time_in_millis number required
start_time union oneOf: One of: string or number
start_time_in_millis number required
completion_time union oneOf: Indicates when the async search completed. It is present only when the search has completed.; One of: string or number
completion_time_in_millis number
error object
response object required

application/json

Required privileges

Path parameters

Query parameters

Request body { }

Responses

Request body