# Async Search

class elasticsearch.client.AsyncSearchClient

  To use this client, access `client.async_search` from an `Elasticsearch` client. For example:

      from elasticsearch import Elasticsearch

      # Create the client instance
      client = Elasticsearch(...)
      # Use the async_search client
      client.async_search.<method>(...)

  delete(*, id, error_trace=None, filter_path=None, human=None, pretty=None)

    Delete an async search.

    If the asynchronous search is still running, it is cancelled. Otherwise, the saved search results are deleted. 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.

    https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation-async-search-submit

    Parameters:

      - id (str) – A unique identifier for the async search.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  get(*, id, error_trace=None, filter_path=None, human=None, keep_alive=None, pretty=None, return_intermediate_results=None, typed_keys=None, wait_for_completion_timeout=None)

    Get async search results.

    Retrieve the results of a previously submitted asynchronous search request. If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.

    https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation-async-search-submit

    Parameters:

      - id (str) – A unique identifier for the async search.

      - keep_alive (str | Literal[-1] | ~typing.Literal[0] | None) – The length of time that 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 the 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.

      - return_intermediate_results (bool | None) – Specifies whether the response should contain intermediate results if the query is still running when the wait_for_completion_timeout expires or if no wait_for_completion_timeout is specified. If true and the search is still running, the search response will include any hits and partial aggregations that are available. If false and the search is still running, the search response will not include any hits (but possibly include total hits) nor will include any partial aggregations. When not specified, the intermediate results are returned for running queries.

      - typed_keys (bool | None) – Specify whether aggregation and suggester names should be prefixed by their respective types in the response

      - wait_for_completion_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – Specifies 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.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  status(*, id, error_trace=None, filter_path=None, human=None, keep_alive=None, pretty=None)

    Get the async search status.

    Get the status of a previously submitted async search request given its identifier, without retrieving search results. If the Elasticsearch security features are enabled, the access to the status of a specific async search is restricted to:

    - The user or API key that submitted the original async search request.
    - Users that have the `monitor` cluster privilege or greater privileges.

    https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation-async-search-submit

    Parameters:

      - id (str) – A unique identifier for the async search.

      - keep_alive (str | Literal[-1] | ~typing.Literal[0] | None) – The length of time that the async search needs to be available. Ongoing async searches and any saved search results are deleted after this period.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  submit(*, index=None, aggregations=None, aggs=None, allow_no_indices=None, allow_partial_search_results=None, analyze_wildcard=None, analyzer=None, batched_reduce_size=None, ccs_minimize_roundtrips=None, collapse=None, default_operator=None, df=None, docvalue_fields=None, error_trace=None, expand_wildcards=None, explain=None, ext=None, fields=None, filter_path=None, from_=None, highlight=None, human=None, ignore_throttled=None, ignore_unavailable=None, indices_boost=None, keep_alive=None, keep_on_completion=None, knn=None, lenient=None, max_concurrent_shard_requests=None, min_score=None, pit=None, post_filter=None, preference=None, pretty=None, profile=None, project_routing=None, q=None, query=None, request_cache=None, rescore=None, rest_total_hits_as_int=None, routing=None, runtime_mappings=None, script_fields=None, search_after=None, search_type=None, seq_no_primary_term=None, size=None, slice=None, sort=None, source=None, source_excludes=None, source_includes=None, stats=None, stored_fields=None, suggest=None, suggest_field=None, suggest_mode=None, suggest_size=None, suggest_text=None, terminate_after=None, timeout=None, track_scores=None, track_total_hits=None, typed_keys=None, version=None, wait_for_completion_timeout=None, body=None)

    Run an 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.

    https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation-async-search-submit

    Parameters:

      - index (str | Sequence[str] | None) – A comma-separated list of index names to search; use _all or empty string to perform the operation on all indices

      - aggregations (Mapping[str, Mapping[str, Any]] | None)

      - aggs (Mapping[str, Mapping[str, Any]] | None)

      - allow_no_indices (bool | None) – 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 (bool | None) – Indicate if an error should be returned if there is a partial search failure or timeout

      - analyze_wildcard (bool | None) – Specify whether wildcard and prefix queries should be analyzed

      - analyzer (str | None) – The analyzer to use for the query string

      - batched_reduce_size (int | None) – 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 (bool | None) – The default value is the only supported value.

      - collapse (Mapping[str, Any] | None)

      - default_operator (str | Literal['and', 'or'] | None) – The default operator for query string query (AND or OR)

      - df (str | None) – The field to use as default where no field prefix is given in the query string

      - docvalue_fields (Sequence[Mapping[str, Any]] | None) – Array of wildcard (*) patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

      - expand_wildcards (Sequence[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | None) – Whether to expand wildcard expression to concrete indices that are open, closed or both

      - explain (bool | None) – If true, returns detailed information about score computation as part of a hit.

      - ext (Mapping[str, Any] | None) – Configuration of search extensions defined by Elasticsearch plugins.

      - fields (Sequence[Mapping[str, Any]] | None) – Array of wildcard (*) patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.

      - from – 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 (Mapping[str, Any] | None)

      - ignore_throttled (bool | None) – Whether specified concrete, expanded or aliased indices should be ignored when throttled

      - ignore_unavailable (bool | None) – 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.

      - indices_boost (Sequence[Mapping[str, float]] | None) – Boosts the _score of documents from specified indices.

      - keep_alive (str | Literal[-1] | ~typing.Literal[0] | None) – 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 (bool | None) – If true, results are stored for later retrieval when the search completes within the wait_for_completion_timeout.

      - knn (Mapping[str, Any] | Sequence[Mapping[str, Any]] | None) – Defines the approximate kNN search to run.

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

      - max_concurrent_shard_requests (int | None) – 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

      - min_score (float | None) – Minimum _score for matching documents. Documents with a lower _score are not included in search results and results collected by aggregations.

      - pit (Mapping[str, Any] | None) – Limits the search to a point in time (PIT). If you provide a PIT, you cannot specify an <index> in the request path.

      - post_filter (Mapping[str, Any] | None)

      - preference (str | None) – Specify the node or shard the operation should be performed on

      - profile (bool | None)

      - project_routing (str | None) – Specifies a subset of projects to target for the search using project metadata tags in a subset of Lucene query syntax. Allowed Lucene queries: the _alias tag and a single value (possibly wildcarded). Examples: _alias:my-project _alias:_origin _alias:pr Supported in serverless only.

      - q (str | None) – Query in the Lucene query string syntax

      - query (Mapping[str, Any] | None) – Defines the search definition using the Query DSL.

      - request_cache (bool | None) – Specify if request cache should be used for this request or not, defaults to true

      - rescore (Mapping[str, Any] | Sequence[Mapping[str, Any]] | None)

      - rest_total_hits_as_int (bool | None) – Indicates whether hits.total should be rendered as an integer or an object in the rest search response

      - routing (str | Sequence[str] | None) – A comma-separated list of specific routing values

      - runtime_mappings (Mapping[str, Mapping[str, Any]] | None) – Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.

      - script_fields (Mapping[str, Mapping[str, Any]] | None) – Retrieve a script evaluation (based on different fields) for each hit.

      - search_after (Sequence[None | bool | float | int | str] | None)

      - search_type (str | Literal['dfs_query_then_fetch', 'query_then_fetch'] | None) – Search operation type

      - seq_no_primary_term (bool | None) – If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.

      - size (int | None) – 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 (Mapping[str, Any] | None)

      - sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None)

      - source (bool | Mapping[str, Any] | None) – Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.

      - source_excludes (str | Sequence[str] | None) – A list of fields to exclude from the returned _source field

      - source_includes (str | Sequence[str] | None) – A list of fields to extract and return from the _source field

      - stats (Sequence[str] | None) – 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.

      - stored_fields (str | Sequence[str] | None) – 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.

      - suggest (Mapping[str, Any] | None)

      - suggest_field (str | None) – Specifies which field to use for suggestions.

      - suggest_mode (str | Literal['always', 'missing', 'popular'] | None) – Specify suggest mode

      - suggest_size (int | None) – How many suggestions to return in response

      - suggest_text (str | None) – The source text for which the suggestions should be returned.

      - terminate_after (int | None) – 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 (str | None) – 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 (bool | None) – If true, calculate and return document scores, even if the scores are not used for sorting.

      - track_total_hits (bool | int | None) – 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.

      - typed_keys (bool | None) – Specify whether aggregation and suggester names should be prefixed by their respective types in the response

      - version (bool | None) – If true, returns document version as part of a hit.

      - wait_for_completion_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 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.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - from_ (int | None)

      - human (bool | None)

      - pretty (bool | None)

      - body (Dict[str, Any] | None)

    Return type:

      ObjectApiResponse[Any]