Run an async search

POST /{index}/_async_search
POST /_async_search

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.

Path Parameters

index union IndexName | [] IndexName 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 string Duration · 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.

keep_alive string Duration · 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.

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 Operator · 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 Fields

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

One of: Field or Field[]

expand_wildcards string ExpandWildcards · 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 Routing

A comma-separated list of specific routing values

One of: string or string[]

search_type enum SearchType

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 Fields

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

One of: Field or Field[]

suggest_field string Field

Specifies which field to use for suggestions.

suggest_mode enum SuggestMode · 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 string Duration

Explicit operation timeout

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 SourceConfigParam

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

One of: boolean or Fields

_source_excludes union Fields

A list of fields to exclude from the returned _source field

One of: Field or Field[]

_source_includes union Fields

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

One of: Field or 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

One of: string or string[]

Request

Response

application/json

Examples

Perform a search request asynchronously with POST /sales*/_async_search?size=0. It accepts the same parameters and request body as the search API.

Request Console 1 / 8 languages

Console Kibana Dev Tools

POST /sales*/_async_search?size=0
{
  "sort": [
    { "date": { "order": "asc" } }
  ],
  "aggs": {
    "sale_date": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "1d"
      }
    }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.asyncSearch.submit({
  index: "sales*",
  size: 0,
  sort: [
    {
      date: {
        order: "asc",
      },
    },
  ],
  aggs: {
    sale_date: {
      date_histogram: {
        field: "date",
        calendar_interval: "1d",
      },
    },
  },
});

Python Elasticsearch Python Client

resp = client.async_search.submit(
    index="sales*",
    size="0",
    sort=[
        {
            "date": {
                "order": "asc"
            }
        }
    ],
    aggs={
        "sale_date": {
            "date_histogram": {
                "field": "date",
                "calendar_interval": "1d"
            }
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/sales*/_async_search?size=0" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sort": [
      {
        "date": {
          "order": "asc"
        }
      }
    ],
    "aggs": {
      "sale_date": {
        "date_histogram": {
          "field": "date",
          "calendar_interval": "1d"
        }
      }
    }
  }'

Java Elasticsearch Java Client

client.asyncSearch().submit(s -> s
    .aggregations("sale_date", a -> a
        .dateHistogram(d -> d
            .calendarInterval(CalendarInterval.Day)
            .field("date")
        )
    )
    .index("sales*")
    .size(0)
    .sort(so -> so
        .field(f -> f
            .field("date")
            .order(SortOrder.Asc)
        )
    )
,Void.class);

C# Elasticsearch .NET Client

var response = await client.AsyncSearch
    .SubmitAsync<MyDocument>(d1 => d1
        .Indices(new[] { "sales*" })
        .Aggregations(d2 => d2
            .Add("sale_date", d3 => d3
                .DateHistogram(d4 => d4
                    .CalendarInterval(CalendarInterval.Day)
                    .Field(x => x.Date)
                )
            )
        )
        .Sort(d2 => d2
            .Field(d3 => d3
                .Field(x => x.Date)
                .Order(SortOrder.Asc)
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->asyncSearch()->submit([
    "index" => "sales*",
    "size" => "0",
    "body" => [
        "sort" => array(
            [
                "date" => [
                    "order" => "asc",
                ],
            ],
        ),
        "aggs" => [
            "sale_date" => [
                "date_histogram" => [
                    "field" => "date",
                    "calendar_interval" => "1d",
                ],
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.async_search.submit(
  index: "sales*",
  size: "0",
  body: {
    "sort": [
      {
        "date": {
          "order": "asc"
        }
      }
    ],
    "aggs": {
      "sale_date": {
        "date_histogram": {
          "field": "date",
          "calendar_interval": "1d"
        }
      }
    }
  }
)

Response

{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_partial" : true,
  "is_running" : true,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "response" : {
    "took" : 1122,
    "timed_out" : false,
    "num_reduce_phases" : 0,
    "_shards" : {
      "total" : 562,
      "successful" : 3,
      "skipped" : 0,
      "failed" : 0
    },
    "hits" : {
      "total" : {
        "value" : 157483,
        "relation" : "gte"
      },
      "max_score" : null,
      "hits" : [ ]
    }
  }
}