IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Search API Point in time API »
Elastic Docs ›Elasticsearch Guide [7.12] ›REST APIs ›Search APIs

Async search

edit

Async search

edit

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 API

edit

Executes a search request asynchronously. It accepts the same parameters and request body as the search API.

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

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 response object.

{
  "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" : [ ]
    }
  }
}

Identifier of the async search that can be used to monitor its progress, retrieve its results, and/or delete it

When the query is no longer running, indicates whether the search failed or was successfully completed on all shards. While the query is being executed, is_partial is always set to true

Whether the search is still being executed or it has completed

How many shards the search will be executed on, overall

How many shards have successfully completed the search

How many documents are currently matching the query, which belong to the shards that have already completed the search

Although the query is no longer running, hence is_running is set to false, results may be partial. That happens in case the search failed after some shards returned their results, or when the node that is coordinating the async search dies.

It is possible to block and wait until the search is completed up to a certain timeout by providing the wait_for_completion_timeout parameter, which defaults to 1 second. When the async search completes within such timeout, the response won’t include the ID as the results are not stored in the cluster. 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.

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 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 reduction is performed every time the coordinating node has received a certain number of new shard responses (5 by default).
  • request_cache defaults to true
  • pre_filter_shard_size defaults to 1 and cannot be changed: this is to enforce the execution of a pre-filter roundtrip to retrieve statistics from each shard so that the ones that surely don’t hold any document matching the query get skipped.
  • ccs_minimize_roundtrips defaults to false, which is also the only supported value

Async search does not support scroll nor search requests that only include the suggest section. Cross-cluster search is supported only with ccs_minimize_roundtrips set to false.

Get async search

edit

The get async search API retrieves the results of a previously submitted async search request given its id. If the Elasticsearch security features are enabled, the access to the results of a specific async search is restricted to the user or API key that submitted it.

GET /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_partial" : true, 
  "is_running" : true, 
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986, 
  "response" : {
    "took" : 12144,
    "timed_out" : false,
    "num_reduce_phases" : 46, 
    "_shards" : {
      "total" : 562,
      "successful" : 188, 
      "skipped" : 0,
      "failed" : 0
    },
    "hits" : {
      "total" : {
        "value" : 456433,
        "relation" : "eq"
      },
      "max_score" : null,
      "hits" : [ ]
    },
    "aggregations" : { 
      "sale_date" :  {
        "buckets" : []
      }
    }
  }
}

When the query is no longer running, indicates whether the search failed or was successfully completed on all shards. While the query is being executed, is_partial is always set to true

Whether the search is still being executed or it has completed

When the async search will expire

Indicates how many reductions of the results have been performed. If this number increases compared to the last retrieved results, you can expect additional results included in the search response

Indicates how many shards have executed the query. Note that in order for shard results to be included in the search response, they need to be reduced first.

Partial aggregations results, coming from the shards that have already 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 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.

Get async search status

edit

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 Elasticsearch security features are enabled, the access to the get async search status API is restricted to the monitoring_user role.

GET /_async_search/status/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_running" : true,
  "is_partial" : true,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "_shards" : {
      "total" : 562,
      "successful" : 188, 
      "skipped" : 0,
      "failed" : 0
  }
}

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.

{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_running" : false,
  "is_partial" : false,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "_shards" : {
      "total" : 562,
      "successful" : 562,
      "skipped" : 0,
      "failed" : 0
  },
 "completion_status" : 200 
}

Indicates that the async search was successfully completed.

 
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_running" : false,
  "is_partial" : true,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "_shards" : {
      "total" : 562,
      "successful" : 450,
      "skipped" : 0,
      "failed" : 112
  },
 "completion_status" : 503 
}

Indicates that the async search was completed with an error.

Delete async search

edit

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.

DELETE /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=

If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: * The authenticated user that submitted the original search request. * Users that have the cancel_task cluster privilege.

« Search API Point in time API »