Using asyncio with Elasticsearch

The elasticsearch package supports async/await with asyncio and aiohttp. You can either install aiohttp directly or use the [async] extra:

$ python -m pip install elasticsearch aiohttp

# - OR -

$ python -m pip install elasticsearch[async]

Getting Started with Async

After installation all async API endpoints are available via AsyncElasticsearch and are used in the same way as other APIs, just with an extra await:

import asyncio
from elasticsearch import AsyncElasticsearch

client = AsyncElasticsearch()

async def main():
    resp = await client.search(
        index="documents",
        body={"query": {"match_all": {}}},
        size=20,
    )
    print(resp)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

All APIs that are available under the sync client are also available under the async client.

ASGI Applications and Elastic APM

ASGI (Asynchronous Server Gateway Interface) is a new way to serve Python web applications making use of async I/O to achieve better performance. Some examples of ASGI frameworks include FastAPI, Django 3.0+, and Starlette. If you’re using one of these frameworks along with Elasticsearch then you should be using AsyncElasticsearch to avoid blocking the event loop with synchronous network calls for optimal performance.

Elastic APM also supports tracing of async Elasticsearch queries just the same as synchronous queries. For an example on how to configure AsyncElasticsearch with a popular ASGI framework FastAPI and APM tracing there is a pre-built example in the examples/fastapi-apm directory.

Frequently Asked Questions

ValueError when initializing AsyncElasticsearch?

If when trying to use AsyncElasticsearch you receive ValueError: You must have 'aiohttp' installed to use AiohttpHttpNode you should ensure that you have aiohttp installed in your environment (check with $ python -m pip freeze | grep aiohttp). Otherwise, async support won’t be available.

What about the elasticsearch-async package?

Previously asyncio was supported separately via the elasticsearch-async package. The elasticsearch-async package has been deprecated in favor of AsyncElasticsearch provided by the elasticsearch package in v7.8 and onwards.

Receiving ‘Unclosed client session / connector’ warning?

This warning is created by aiohttp when an open HTTP connection is garbage collected. You’ll typically run into this when closing your application. To resolve the issue ensure that close() is called before the AsyncElasticsearch instance is garbage collected.

For example if using FastAPI that might look like this:

import os
from contextlib import asynccontextmanager

from fastapi import FastAPI
from elasticsearch import AsyncElasticsearch

ELASTICSEARCH_URL = os.environ["ELASTICSEARCH_URL"]
client = None

@asynccontextmanager
async def lifespan(app: FastAPI):
    global client
    client = AsyncElasticsearch(ELASTICSEARCH_URL)
    yield
    await client.close()

app = FastAPI(lifespan=lifespan)

@app.get("/")
async def main():
    return await client.info()

You can run this example by saving it to main.py and executing ELASTICSEARCH_URL=http://localhost:9200 uvicorn main:app.

Async Helpers

Async variants of all helpers are available in elasticsearch.helpers and are all prefixed with async_*. You’ll notice that these APIs are identical to the ones in the sync Helpers documentation.

All async helpers that accept an iterator or generator also accept async iterators and async generators.

Bulk and Streaming Bulk

async elasticsearch.helpers.async_bulk(client, actions, stats_only=False, ignore_status=(), *args, **kwargs)

Helper for the bulk() api that provides a more human friendly interface - it consumes an iterator of actions and sends them to elasticsearch in chunks. It returns a tuple with summary information - number of successfully executed actions and either list of errors or number of errors if stats_only is set to True. Note that by default we raise a BulkIndexError when we encounter an error so options like stats_only only+ apply when raise_on_error is set to False.

When errors are being collected original document data is included in the error dictionary which can lead to an extra high memory usage. If you need to process a lot of data and want to ignore/collect errors please consider using the async_streaming_bulk() helper which will just return the errors and not store them in memory.

Parameters:
Return type:

Tuple[int, int | List[Any]]

Any additional keyword arguments will be passed to async_streaming_bulk() which is used to execute the operation, see async_streaming_bulk() for more accepted parameters.

import asyncio
from elasticsearch import AsyncElasticsearch
from elasticsearch.helpers import async_bulk

client = AsyncElasticsearch()

async def gendata():
    mywords = ['foo', 'bar', 'baz']
    for word in mywords:
        yield {
            "_index": "mywords",
            "doc": {"word": word},
        }

async def main():
    await async_bulk(client, gendata())

loop = asyncio.get_event_loop()
loop.run_until_complete(main())
async elasticsearch.helpers.async_streaming_bulk(client, actions, chunk_size=500, max_chunk_bytes=104857600, raise_on_error=True, expand_action_callback=<function expand_action>, raise_on_exception=True, max_retries=0, initial_backoff=2, max_backoff=600, yield_ok=True, ignore_status=(), *args, **kwargs)

Streaming bulk consumes actions from the iterable passed in and yields results per action. For non-streaming usecases use async_bulk() which is a wrapper around streaming bulk that returns summary information about the bulk operation once the entire input is consumed and sent.

If you specify max_retries it will also retry any documents that were rejected with a 429 status code. To do this it will wait (by calling asyncio.sleep) for initial_backoff seconds and then, every subsequent rejection for the same chunk, for double the time every time up to max_backoff seconds.

Parameters:

  • client (AsyncElasticsearch) – instance of AsyncElasticsearch to use

  • actions (Iterable[bytes | str | Dict[str, Any]] | AsyncIterable[bytes | str | Dict[str, Any]]) – iterable or async iterable containing the actions to be executed

  • chunk_size (int) – number of docs in one chunk sent to es (default: 500)

  • max_chunk_bytes (int) – the maximum size of the request in bytes (default: 100MB)

  • raise_on_error (bool) – raise BulkIndexError containing errors (as .errors) from the execution of the last chunk when some occur. By default we raise.

  • raise_on_exception (bool) – if False then don’t propagate exceptions from call to bulk and just report the items that failed as failed.

  • expand_action_callback (Callable[[bytes | str | Dict[str, Any]], Tuple[Dict[str, Any], None | bytes | Dict[str, Any]]]) – callback executed on each action passed in, should return a tuple containing the action line and the data line (None if data line should be omitted).

  • max_retries (int) – maximum number of times a document will be retried when 429 is received, set to 0 (default) for no retries on 429

  • initial_backoff (float) – number of seconds we should wait before the first retry. Any subsequent retries will be powers of initial_backoff * 2**retry_number

  • max_backoff (float) – maximum number of seconds a retry will wait

  • yield_ok (bool) – if set to False will skip successful documents in the output

  • ignore_status (int | Collection[int]) – list of HTTP status code that you want to ignore

  • client

  • actions

  • chunk_size

  • max_chunk_bytes

  • raise_on_error

  • expand_action_callback

  • raise_on_exception

  • max_retries

  • initial_backoff

  • max_backoff

  • yield_ok

  • ignore_status

  • args (Any)

  • kwargs (Any)

Return type:

AsyncIterable[Tuple[bool, Dict[str, Any]]]

import asyncio
from elasticsearch import AsyncElasticsearch
from elasticsearch.helpers import async_streaming_bulk

client = AsyncElasticsearch()

async def gendata():
    mywords = ['foo', 'bar', 'baz']
    for word in mywords:
        yield {
            "_index": "mywords",
            "word": word,
        }

async def main():
    async for ok, result in async_streaming_bulk(client, gendata()):
        action, result = result.popitem()
        if not ok:
            print("failed to %s document %s" % ())

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Scan

async elasticsearch.helpers.async_scan(client, query=None, scroll='5m', raise_on_error=True, preserve_order=False, size=1000, request_timeout=None, clear_scroll=True, scroll_kwargs=None, **kwargs)

Simple abstraction on top of the scroll() api - a simple iterator that yields all hits as returned by underlining scroll requests.

By default scan does not return results in any pre-determined order. To have a standard order in the returned documents (either by score or explicit sort definition) when scrolling, use preserve_order=True. This may be an expensive operation and will negate the performance benefits of using scan.

Parameters:

  • client (AsyncElasticsearch) – instance of AsyncElasticsearch to use

  • query (Any | None) – body for the search() api

  • scroll (str) – Specify how long a consistent view of the index should be maintained for scrolled search

  • raise_on_error (bool) – raises an exception (ScanError) if an error is encountered (some shards fail to execute). By default we raise.

  • preserve_order (bool) – don’t set the search_type to scan - this will cause the scroll to paginate with preserving the order. Note that this can be an extremely expensive operation and can easily lead to unpredictable results, use with caution.

  • size (int) – size (per shard) of the batch send at each iteration.

  • request_timeout (float | None) – explicit timeout for each call to scan

  • clear_scroll (bool) – explicitly calls delete on the scroll id via the clear scroll API at the end of the method on completion or error, defaults to true.

  • scroll_kwargs (MutableMapping[str, Any] | None) – additional kwargs to be passed to scroll()

  • client

  • query

  • scroll

  • raise_on_error

  • preserve_order

  • size

  • request_timeout

  • clear_scroll

  • scroll_kwargs

  • kwargs (Any)

Return type:

AsyncIterable[Dict[str, Any]]

Any additional keyword arguments will be passed to the initial search() call:

async_scan(
    client,
    query={"query": {"match": {"title": "python"}}},
    index="orders-*"
)

import asyncio
from elasticsearch import AsyncElasticsearch
from elasticsearch.helpers import async_scan

client = AsyncElasticsearch()

async def main():
    async for doc in async_scan(
        client=client,
        query={"query": {"match": {"title": "python"}}},
        index="orders-*"
    ):
        print(doc)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Reindex

async elasticsearch.helpers.async_reindex(client, source_index, target_index, query=None, target_client=None, chunk_size=500, scroll='5m', op_type=None, scan_kwargs={}, bulk_kwargs={})

Reindex all documents from one index that satisfy a given query to another, potentially (if target_client is specified) on a different cluster. If you don’t specify the query you will reindex all the documents.

Since 2.3 a reindex() api is available as part of elasticsearch itself. It is recommended to use the api instead of this helper wherever possible. The helper is here mostly for backwards compatibility and for situations where more flexibility is needed.

Note

This helper doesn’t transfer mappings, just the data.

Parameters:

  • client (AsyncElasticsearch) – instance of AsyncElasticsearch to use (for read if target_client is specified as well)

  • source_index (str | Collection[str]) – index (or list of indices) to read documents from

  • target_index (str) – name of the index in the target cluster to populate

  • query (Any) – body for the search() api

  • target_client (AsyncElasticsearch | None) – optional, is specified will be used for writing (thus enabling reindex between clusters)

  • chunk_size (int) – number of docs in one chunk sent to es (default: 500)

  • scroll (str) – Specify how long a consistent view of the index should be maintained for scrolled search

  • op_type (str | None) – Explicit operation type. Defaults to ‘_index’. Data streams must be set to ‘create’. If not specified, will auto-detect if target_index is a data stream.

  • scan_kwargs (MutableMapping[str, Any]) – additional kwargs to be passed to async_scan()

  • bulk_kwargs (MutableMapping[str, Any]) – additional kwargs to be passed to async_bulk()

  • client

  • source_index

  • target_index

  • query

  • target_client

  • chunk_size

  • scroll

  • op_type

  • scan_kwargs

  • bulk_kwargs

Return type:

Tuple[int, int | List[Any]]

API Reference

The API of AsyncElasticsearch is nearly identical to the API of Elasticsearch with the exception that every API call like search() is an async function and requires an await to properly return the response body.

AsyncElasticsearch

Note

To reference Elasticsearch APIs that are namespaced like .indices.create() refer to the sync API reference. These APIs are identical between sync and async.

class elasticsearch.AsyncElasticsearch(hosts=None, *, cloud_id=None, api_key=None, basic_auth=None, bearer_auth=None, opaque_id=None, headers=<DEFAULT>, connections_per_node=<DEFAULT>, http_compress=<DEFAULT>, verify_certs=<DEFAULT>, ca_certs=<DEFAULT>, client_cert=<DEFAULT>, client_key=<DEFAULT>, ssl_assert_hostname=<DEFAULT>, ssl_assert_fingerprint=<DEFAULT>, ssl_version=<DEFAULT>, ssl_context=<DEFAULT>, ssl_show_warn=<DEFAULT>, transport_class=<class 'elastic_transport.AsyncTransport'>, request_timeout=<DEFAULT>, node_class=<DEFAULT>, node_pool_class=<DEFAULT>, randomize_nodes_in_pool=<DEFAULT>, node_selector_class=<DEFAULT>, dead_node_backoff_factor=<DEFAULT>, max_dead_node_backoff=<DEFAULT>, serializer=None, serializers=<DEFAULT>, default_mimetype='application/json', max_retries=<DEFAULT>, retry_on_status=<DEFAULT>, retry_on_timeout=<DEFAULT>, sniff_on_start=<DEFAULT>, sniff_before_requests=<DEFAULT>, sniff_on_node_failure=<DEFAULT>, sniff_timeout=<DEFAULT>, min_delay_between_sniffing=<DEFAULT>, sniffed_node_callback=None, meta_header=<DEFAULT>, timeout=<DEFAULT>, randomize_hosts=<DEFAULT>, host_info_callback=None, sniffer_timeout=<DEFAULT>, sniff_on_connection_fail=<DEFAULT>, http_auth=<DEFAULT>, maxsize=<DEFAULT>, _transport=None)

Elasticsearch low-level client. Provides a straightforward mapping from Python to Elasticsearch REST APIs.

The client instance has additional attributes to update APIs in different namespaces such as async_search, indices, security, and more:

client = Elasticsearch("http://localhost:9200")

# Get Document API
client.get(index="*", id="1")

# Get Index API
client.indices.get(index="*")

Transport options can be set on the client constructor or using the options() method:

# Set 'api_key' on the constructor
client = Elasticsearch(
    "http://localhost:9200",
    api_key="api_key",
)
client.search(...)

# Set 'api_key' per request
client.options(api_key="api_key").search(...)
Parameters:
bulk(*, operations=None, body=None, index=None, error_trace=None, filter_path=None, human=None, pipeline=None, pretty=None, refresh=None, require_alias=None, routing=None, source=None, source_excludes=None, source_includes=None, timeout=None, wait_for_active_shards=None)

Allows to perform multiple index/update/delete operations in a single request.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html

Parameters:

  • operations (Sequence[Mapping[str, Any]] | None)

  • index (str | None) – Name of the data stream, index, or index alias to perform bulk actions on.

  • pipeline (str | None) – ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to _none disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter.

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | None) – If true, Elasticsearch refreshes the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false do nothing with refreshes. Valid values: true, false, wait_for.

  • require_alias (bool | None) – If true, the request’s actions must target an index alias.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • source (bool | str | Sequence[str] | None) – true or false to return the _source field or not, or a list of fields to return.

  • source_excludes (str | Sequence[str] | None) – A comma-separated list of source fields to exclude from the response.

  • source_includes (str | Sequence[str] | None) – A comma-separated list of source fields to include in the response.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period each action waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.

  • wait_for_active_shards (int | Literal['all', 'index-setting'] | str | None) – The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

  • body (Sequence[Mapping[str, Any]] | None)

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

clear_scroll(*, error_trace=None, filter_path=None, human=None, pretty=None, scroll_id=None, body=None)

Explicitly clears the search context for a scroll.

https://www.elastic.co/guide/en/elasticsearch/reference/master/clear-scroll-api.html

Parameters:
Return type:

ObjectApiResponse[Any]

async close()

Closes the Transport and all internal connections

Return type:

None

close_point_in_time(*, id=None, error_trace=None, filter_path=None, human=None, pretty=None, body=None)

Close a point in time

https://www.elastic.co/guide/en/elasticsearch/reference/master/point-in-time-api.html

Parameters:
Return type:

ObjectApiResponse[Any]

count(*, index=None, allow_no_indices=None, analyze_wildcard=None, analyzer=None, default_operator=None, df=None, error_trace=None, expand_wildcards=None, filter_path=None, human=None, ignore_throttled=None, ignore_unavailable=None, lenient=None, min_score=None, preference=None, pretty=None, q=None, query=None, routing=None, terminate_after=None, body=None)

Returns number of documents matching a query.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-count.html

Parameters:

  • index (str | Sequence[str] | None) – Comma-separated list of data streams, indices, and aliases to search. Supports wildcards (*). To search all data streams and indices, omit this parameter or use * or _all.

  • allow_no_indices (bool | None) – If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.

  • analyze_wildcard (bool | None) – If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified.

  • analyzer (str | None) – Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified.

  • default_operator (Literal['and', 'or'] | str | None) – The default operator for query string query: AND or OR. This parameter can only be used when the q query string parameter is specified.

  • df (str | None) – Field to use as default where no field prefix is given in the query string. This parameter can only be used when the q query string parameter is specified.

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

  • ignore_throttled (bool | None) – If true, concrete, expanded or aliased indices are ignored when frozen.

  • ignore_unavailable (bool | None) – If false, the request returns an error if it targets a missing or closed index.

  • lenient (bool | None) – If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.

  • min_score (float | None) – Sets the minimum _score value that documents must have to be included in the result.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

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

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

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • 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.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

create(*, index, id, document=None, body=None, error_trace=None, filter_path=None, human=None, pipeline=None, pretty=None, refresh=None, routing=None, timeout=None, version=None, version_type=None, wait_for_active_shards=None)

Creates a new document in the index. Returns a 409 response when a document with a same ID already exists in the index.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-index_.html

Parameters:

  • index (str) – Name of the data stream or index to target. If the target doesn’t exist and matches the name or wildcard (*) pattern of an index template with a data_stream definition, this request creates the data stream. If the target doesn’t exist and doesn’t match a data stream template, this request creates the index.

  • id (str) – Unique identifier for the document.

  • document (Mapping[str, Any] | None)

  • pipeline (str | None) – ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to _none disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter.

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | None) – If true, Elasticsearch refreshes the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false do nothing with refreshes. Valid values: true, false, wait_for.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.

  • version (int | None) – Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.

  • version_type (Literal['external', 'external_gte', 'force', 'internal'] | str | None) – Specific version type: external, external_gte.

  • wait_for_active_shards (int | Literal['all', 'index-setting'] | str | None) – The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

  • body (Mapping[str, Any] | None)

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delete(*, index, id, error_trace=None, filter_path=None, human=None, if_primary_term=None, if_seq_no=None, pretty=None, refresh=None, routing=None, timeout=None, version=None, version_type=None, wait_for_active_shards=None)

Removes a document from the index.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-delete.html

Parameters:

  • index (str) – Name of the target index.

  • id (str) – Unique identifier for the document.

  • if_primary_term (int | None) – Only perform the operation if the document has this primary term.

  • if_seq_no (int | None) – Only perform the operation if the document has this sequence number.

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | None) – If true, Elasticsearch refreshes the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false do nothing with refreshes. Valid values: true, false, wait_for.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for active shards.

  • version (int | None) – Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.

  • version_type (Literal['external', 'external_gte', 'force', 'internal'] | str | None) – Specific version type: external, external_gte.

  • wait_for_active_shards (int | Literal['all', 'index-setting'] | str | None) – The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delete_by_query(*, index, allow_no_indices=None, analyze_wildcard=None, analyzer=None, conflicts=None, default_operator=None, df=None, error_trace=None, expand_wildcards=None, filter_path=None, from_=None, human=None, ignore_unavailable=None, lenient=None, max_docs=None, preference=None, pretty=None, q=None, query=None, refresh=None, request_cache=None, requests_per_second=None, routing=None, scroll=None, scroll_size=None, search_timeout=None, search_type=None, slice=None, slices=None, sort=None, stats=None, terminate_after=None, timeout=None, version=None, wait_for_active_shards=None, wait_for_completion=None, body=None)

Deletes documents matching the provided query.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-delete-by-query.html

Parameters:

  • index (str | Sequence[str]) – Comma-separated list of data streams, indices, and aliases to search. Supports wildcards (*). To search all data streams or indices, omit this parameter or use * or _all.

  • allow_no_indices (bool | None) – If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • analyze_wildcard (bool | None) – If true, wildcard and prefix queries are analyzed.

  • analyzer (str | None) – Analyzer to use for the query string.

  • conflicts (Literal['abort', 'proceed'] | str | None) – What to do if delete by query hits version conflicts: abort or proceed.

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

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

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • from – Starting offset (default: 0)

  • ignore_unavailable (bool | None) – If false, the request returns an error if it targets a missing or closed index.

  • lenient (bool | None) – If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.

  • max_docs (int | None) – The maximum number of documents to delete.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

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

  • query (Mapping[str, Any] | None) – Specifies the documents to delete using the Query DSL.

  • refresh (bool | None) – If true, Elasticsearch refreshes all shards involved in the delete by query after the request completes.

  • request_cache (bool | None) – If true, the request cache is used for this request. Defaults to the index-level setting.

  • requests_per_second (float | None) – The throttle for this request in sub-requests per second.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • scroll (Literal[-1] | ~typing.Literal[0] | str | None) – Period to retain the search context for scrolling.

  • scroll_size (int | None) – Size of the scroll request that powers the operation.

  • search_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Explicit timeout for each search request. Defaults to no timeout.

  • search_type (Literal['dfs_query_then_fetch', 'query_then_fetch'] | str | None) – The type of the search operation. Available options: query_then_fetch, dfs_query_then_fetch.

  • slice (Mapping[str, Any] | None) – Slice the request manually using the provided slice ID and total number of slices.

  • slices (int | Literal['auto'] | str | None) – The number of slices this task should be divided into.

  • sort (Sequence[str] | None) – A comma-separated list of <field>:<direction> pairs.

  • stats (Sequence[str] | None) – Specific tag of the request for logging and statistical purposes.

  • 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. Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period each deletion request waits for active shards.

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

  • wait_for_active_shards (int | Literal['all', 'index-setting'] | str | None) – The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

  • wait_for_completion (bool | None) – If true, the request blocks until the operation is complete.

  • 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]

delete_by_query_rethrottle(*, task_id, error_trace=None, filter_path=None, human=None, pretty=None, requests_per_second=None)

Changes the number of requests per second for a particular Delete By Query operation.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-delete-by-query.html

Parameters:

  • task_id (int | str) – The ID for the task.

  • requests_per_second (float | None) – The throttle for this request in sub-requests per second.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delete_script(*, id, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None)

Deletes a script.

https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html

Parameters:

  • id (str) – Identifier for the stored script or search template.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

exists(*, index, id, error_trace=None, filter_path=None, human=None, preference=None, pretty=None, realtime=None, refresh=None, routing=None, source=None, source_excludes=None, source_includes=None, stored_fields=None, version=None, version_type=None)

Returns information about whether a document exists in an index.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html

Parameters:

  • index (str) – Comma-separated list of data streams, indices, and aliases. Supports wildcards (*).

  • id (str) – Identifier of the document.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • realtime (bool | None) – If true, the request is real-time as opposed to near-real-time.

  • refresh (bool | None) – If true, Elasticsearch refreshes all shards involved in the delete by query after the request completes.

  • routing (str | None) – Target the specified primary shard.

  • source (bool | str | Sequence[str] | None) – true or false to return the _source field or not, or a list of fields to return.

  • source_excludes (str | Sequence[str] | None) – A comma-separated list of source fields to exclude in the response.

  • source_includes (str | Sequence[str] | None) – A comma-separated list of source fields to include in the response.

  • 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.

  • version (int | None) – Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.

  • version_type (Literal['external', 'external_gte', 'force', 'internal'] | str | None) – Specific version type: external, external_gte.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

HeadApiResponse

exists_source(*, index, id, error_trace=None, filter_path=None, human=None, preference=None, pretty=None, realtime=None, refresh=None, routing=None, source=None, source_excludes=None, source_includes=None, version=None, version_type=None)

Returns information about whether a document source exists in an index.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html

Parameters:

  • index (str) – Comma-separated list of data streams, indices, and aliases. Supports wildcards (*).

  • id (str) – Identifier of the document.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • realtime (bool | None) – If true, the request is real-time as opposed to near-real-time.

  • refresh (bool | None) – If true, Elasticsearch refreshes all shards involved in the delete by query after the request completes.

  • routing (str | None) – Target the specified primary shard.

  • source (bool | str | Sequence[str] | None) – true or false to return the _source field or not, or a list of fields to return.

  • source_excludes (str | Sequence[str] | None) – A comma-separated list of source fields to exclude in the response.

  • source_includes (str | Sequence[str] | None) – A comma-separated list of source fields to include in the response.

  • version (int | None) – Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.

  • version_type (Literal['external', 'external_gte', 'force', 'internal'] | str | None) – Specific version type: external, external_gte.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

HeadApiResponse

explain(*, index, id, analyze_wildcard=None, analyzer=None, default_operator=None, df=None, error_trace=None, filter_path=None, human=None, lenient=None, preference=None, pretty=None, q=None, query=None, routing=None, source=None, source_excludes=None, source_includes=None, stored_fields=None, body=None)

Returns information about why a specific matches (or doesn’t match) a query.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-explain.html

Parameters:

  • index (str) – Index names used to limit the request. Only a single index name can be provided to this parameter.

  • id (str) – Defines the document ID.

  • analyze_wildcard (bool | None) – If true, wildcard and prefix queries are analyzed.

  • analyzer (str | None) – Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified.

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

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

  • lenient (bool | None) – If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

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

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

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • source (bool | str | Sequence[str] | None) – True or false to return the _source field or not, or a list of fields to return.

  • source_excludes (str | Sequence[str] | None) – A comma-separated list of source fields to exclude from the response.

  • source_includes (str | Sequence[str] | None) – A comma-separated list of source fields to include in the response.

  • stored_fields (str | Sequence[str] | None) – A comma-separated list of stored fields to return in the response.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

field_caps(*, index=None, allow_no_indices=None, error_trace=None, expand_wildcards=None, fields=None, filter_path=None, filters=None, human=None, ignore_unavailable=None, include_empty_fields=None, include_unmapped=None, index_filter=None, pretty=None, runtime_mappings=None, types=None, body=None)

Returns the information about the capabilities of fields among multiple indices.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-field-caps.html

Parameters:

  • index (str | Sequence[str] | None) – Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.

  • allow_no_indices (bool | None) – If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

  • fields (str | Sequence[str] | None) – List of fields to retrieve capabilities for. Wildcard (*) expressions are supported.

  • filters (str | None) – An optional set of filters: can include +metadata,-metadata,-nested,-multifield,-parent

  • ignore_unavailable (bool | None) – If true, missing or closed indices are not included in the response.

  • include_empty_fields (bool | None) – If false, empty fields are not included in the response.

  • include_unmapped (bool | None) – If true, unmapped fields are included in the response.

  • index_filter (Mapping[str, Any] | None) – Allows to filter indices if the provided query rewrites to match_none on every shard.

  • runtime_mappings (Mapping[str, Mapping[str, Any]] | None) – Defines ad-hoc runtime fields in the request similar to the way it is done in search requests. These fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings.

  • types (Sequence[str] | None) – Only return results for fields that have one of the types in the list

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

get(*, index, id, error_trace=None, filter_path=None, force_synthetic_source=None, human=None, preference=None, pretty=None, realtime=None, refresh=None, routing=None, source=None, source_excludes=None, source_includes=None, stored_fields=None, version=None, version_type=None)

Returns a document.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html

Parameters:

  • index (str) – Name of the index that contains the document.

  • id (str) – Unique identifier of the document.

  • force_synthetic_source (bool | None) – Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • realtime (bool | None) – If true, the request is real-time as opposed to near-real-time.

  • refresh (bool | None) – If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes.

  • routing (str | None) – Target the specified primary shard.

  • source (bool | str | Sequence[str] | None) – True or false to return the _source field or not, or a list of fields to return.

  • source_excludes (str | Sequence[str] | None) – A comma-separated list of source fields to exclude in the response.

  • source_includes (str | Sequence[str] | None) – A comma-separated list of source fields to include in the response.

  • 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.

  • version (int | None) – Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.

  • version_type (Literal['external', 'external_gte', 'force', 'internal'] | str | None) – Specific version type: internal, external, external_gte.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_script(*, id, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None)

Returns a script.

https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html

Parameters:

  • id (str) – Identifier for the stored script or search template.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Specify timeout for connection to master

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_script_context(*, error_trace=None, filter_path=None, human=None, pretty=None)

Returns all script contexts.

https://www.elastic.co/guide/en/elasticsearch/painless/master/painless-contexts.html

Parameters:
Return type:

ObjectApiResponse[Any]

get_script_languages(*, error_trace=None, filter_path=None, human=None, pretty=None)

Returns available script types, languages and contexts

https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html

Parameters:
Return type:

ObjectApiResponse[Any]

get_source(*, index, id, error_trace=None, filter_path=None, human=None, preference=None, pretty=None, realtime=None, refresh=None, routing=None, source=None, source_excludes=None, source_includes=None, stored_fields=None, version=None, version_type=None)

Returns the source of a document.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html

Parameters:

  • index (str) – Name of the index that contains the document.

  • id (str) – Unique identifier of the document.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • realtime (bool | None) – Boolean) If true, the request is real-time as opposed to near-real-time.

  • refresh (bool | None) – If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes.

  • routing (str | None) – Target the specified primary shard.

  • source (bool | str | Sequence[str] | None) – True or false to return the _source field or not, or a list of fields to return.

  • source_excludes (str | Sequence[str] | None) – A comma-separated list of source fields to exclude in the response.

  • source_includes (str | Sequence[str] | None) – A comma-separated list of source fields to include in the response.

  • stored_fields (str | Sequence[str] | None)

  • version (int | None) – Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.

  • version_type (Literal['external', 'external_gte', 'force', 'internal'] | str | None) – Specific version type: internal, external, external_gte.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

health_report(*, feature=None, error_trace=None, filter_path=None, human=None, pretty=None, size=None, timeout=None, verbose=None)

Returns the health of the cluster.

https://www.elastic.co/guide/en/elasticsearch/reference/master/health-api.html

Parameters:

  • feature (str | Sequence[str] | None) – A feature of the cluster, as returned by the top-level health report API.

  • size (int | None) – Limit the number of affected resources the health report API returns.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Explicit operation timeout.

  • verbose (bool | None) – Opt-in for more information about the health of the system.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

index(*, index, document=None, body=None, id=None, error_trace=None, filter_path=None, human=None, if_primary_term=None, if_seq_no=None, op_type=None, pipeline=None, pretty=None, refresh=None, require_alias=None, routing=None, timeout=None, version=None, version_type=None, wait_for_active_shards=None)

Creates or updates a document in an index.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-index_.html

Parameters:

  • index (str) – Name of the data stream or index to target.

  • document (Mapping[str, Any] | None)

  • id (str | None) – Unique identifier for the document.

  • if_primary_term (int | None) – Only perform the operation if the document has this primary term.

  • if_seq_no (int | None) – Only perform the operation if the document has this sequence number.

  • op_type (Literal['create', 'index'] | str | None) – Set to create to only index the document if it does not already exist (put if absent). If a document with the specified _id already exists, the indexing operation will fail. Same as using the <index>/_create endpoint. Valid values: index, create. If document id is specified, it defaults to index. Otherwise, it defaults to create.

  • pipeline (str | None) – ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to _none disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter.

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | None) – If true, Elasticsearch refreshes the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false do nothing with refreshes. Valid values: true, false, wait_for.

  • require_alias (bool | None) – If true, the destination must be an index alias.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.

  • version (int | None) – Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.

  • version_type (Literal['external', 'external_gte', 'force', 'internal'] | str | None) – Specific version type: external, external_gte.

  • wait_for_active_shards (int | Literal['all', 'index-setting'] | str | None) – The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

  • body (Mapping[str, Any] | None)

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

info(*, error_trace=None, filter_path=None, human=None, pretty=None)

Returns basic information about the cluster.

https://www.elastic.co/guide/en/elasticsearch/reference/master/index.html

Parameters:
Return type:

ObjectApiResponse[Any]

Performs a kNN search.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-search.html

Parameters:

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

  • knn (Mapping[str, Any] | None) – kNN query to execute

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

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

  • filter (Mapping[str, Any] | Sequence[Mapping[str, Any]] | None) – Query to filter the documents that can match. The kNN search will return the top k documents that also match this filter. The value can be a single query or a list of queries. If filter isn’t provided, all documents are allowed to match.

  • routing (str | None) – A comma-separated list of specific routing values

  • 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.

  • 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.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

mget(*, index=None, docs=None, error_trace=None, filter_path=None, force_synthetic_source=None, human=None, ids=None, preference=None, pretty=None, realtime=None, refresh=None, routing=None, source=None, source_excludes=None, source_includes=None, stored_fields=None, body=None)

Allows to get multiple documents in one request.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-multi-get.html

Parameters:

  • index (str | None) – Name of the index to retrieve documents from when ids are specified, or when a document in the docs array does not specify an index.

  • docs (Sequence[Mapping[str, Any]] | None) – The documents you want to retrieve. Required if no index is specified in the request URI.

  • force_synthetic_source (bool | None) – Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.

  • ids (str | Sequence[str] | None) – The IDs of the documents you want to retrieve. Allowed when the index is specified in the request URI.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • realtime (bool | None) – If true, the request is real-time as opposed to near-real-time.

  • refresh (bool | None) – If true, the request refreshes relevant shards before retrieving documents.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • source (bool | str | Sequence[str] | None) – True or false to return the _source field or not, or a list of fields to return.

  • source_excludes (str | Sequence[str] | None) – A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.

  • source_includes (str | Sequence[str] | None) – A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter. If the _source parameter is false, this parameter is ignored.

  • stored_fields (str | Sequence[str] | None) – If true, retrieves the document fields stored in the index rather than the document _source.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

msearch(*, searches=None, body=None, index=None, allow_no_indices=None, ccs_minimize_roundtrips=None, error_trace=None, expand_wildcards=None, filter_path=None, human=None, ignore_throttled=None, ignore_unavailable=None, max_concurrent_searches=None, max_concurrent_shard_requests=None, pre_filter_shard_size=None, pretty=None, rest_total_hits_as_int=None, routing=None, search_type=None, typed_keys=None)

Allows to execute several search operations in one request.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-multi-search.html

Parameters:

  • searches (Sequence[Mapping[str, Any]] | None)

  • index (str | Sequence[str] | None) – Comma-separated list of data streams, indices, and index aliases to search.

  • allow_no_indices (bool | None) – If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • ccs_minimize_roundtrips (bool | None) – If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.

  • ignore_throttled (bool | None) – If true, concrete, expanded or aliased indices are ignored when frozen.

  • ignore_unavailable (bool | None) – If true, missing or closed indices are not included in the response.

  • max_concurrent_searches (int | None) – Maximum number of concurrent searches the multi search API can execute.

  • max_concurrent_shard_requests (int | None) – Maximum number of concurrent shard requests that each sub-search request executes per node.

  • pre_filter_shard_size (int | None) – Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.

  • rest_total_hits_as_int (bool | None) – If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.

  • routing (str | None) – Custom routing value used to route search operations to a specific shard.

  • search_type (Literal['dfs_query_then_fetch', 'query_then_fetch'] | str | None) – Indicates whether global term and document frequencies should be used when scoring returned documents.

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

  • body (Sequence[Mapping[str, Any]] | None)

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

msearch_template(*, search_templates=None, body=None, index=None, ccs_minimize_roundtrips=None, error_trace=None, filter_path=None, human=None, max_concurrent_searches=None, pretty=None, rest_total_hits_as_int=None, search_type=None, typed_keys=None)

Allows to execute several search template operations in one request.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-multi-search.html

Parameters:

  • search_templates (Sequence[Mapping[str, Any]] | None)

  • index (str | Sequence[str] | None) – Comma-separated list of data streams, indices, and aliases to search. Supports wildcards (*). To search all data streams and indices, omit this parameter or use *.

  • ccs_minimize_roundtrips (bool | None) – If true, network round-trips are minimized for cross-cluster search requests.

  • max_concurrent_searches (int | None) – Maximum number of concurrent searches the API can run.

  • rest_total_hits_as_int (bool | None) – If true, the response returns hits.total as an integer. If false, it returns hits.total as an object.

  • search_type (Literal['dfs_query_then_fetch', 'query_then_fetch'] | str | None) – The type of the search operation. Available options: query_then_fetch, dfs_query_then_fetch.

  • typed_keys (bool | None) – If true, the response prefixes aggregation and suggester names with their respective types.

  • body (Sequence[Mapping[str, Any]] | None)

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

mtermvectors(*, index=None, docs=None, error_trace=None, field_statistics=None, fields=None, filter_path=None, human=None, ids=None, offsets=None, payloads=None, positions=None, preference=None, pretty=None, realtime=None, routing=None, term_statistics=None, version=None, version_type=None, body=None)

Returns multiple termvectors in one request.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-multi-termvectors.html

Parameters:

  • index (str | None) – Name of the index that contains the documents.

  • docs (Sequence[Mapping[str, Any]] | None) – Array of existing or artificial documents.

  • field_statistics (bool | None) – If true, the response includes the document count, sum of document frequencies, and sum of total term frequencies.

  • fields (str | Sequence[str] | None) – Comma-separated list or wildcard expressions of fields to include in the statistics. Used as the default list unless a specific field list is provided in the completion_fields or fielddata_fields parameters.

  • ids (Sequence[str] | None) – Simplified syntax to specify documents by their ID if they’re in the same index.

  • offsets (bool | None) – If true, the response includes term offsets.

  • payloads (bool | None) – If true, the response includes term payloads.

  • positions (bool | None) – If true, the response includes term positions.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • realtime (bool | None) – If true, the request is real-time as opposed to near-real-time.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • term_statistics (bool | None) – If true, the response includes term frequency and document frequency.

  • version (int | None) – If true, returns the document version as part of a hit.

  • version_type (Literal['external', 'external_gte', 'force', 'internal'] | str | None) – Specific version type.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

open_point_in_time(*, index, keep_alive, error_trace=None, expand_wildcards=None, filter_path=None, human=None, ignore_unavailable=None, preference=None, pretty=None, routing=None)

Open a point in time that can be used in subsequent searches

https://www.elastic.co/guide/en/elasticsearch/reference/master/point-in-time-api.html

Parameters:

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

  • keep_alive (Literal[-1] | ~typing.Literal[0] | str) – Extends the time to live of the corresponding point in time.

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • ignore_unavailable (bool | None) – If false, the request returns an error if it targets a missing or closed index.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

ping(*, error_trace=None, filter_path=None, human=None, pretty=None)

Returns True if a successful response returns from the info() API, otherwise returns False. This API call can fail either at the transport layer (due to connection errors or timeouts) or from a non-2XX HTTP response (due to authentication or authorization issues).

If you want to discover why the request failed you should use the info() API.

https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html

Parameters:
Return type:

bool

put_script(*, id, script=None, context=None, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None, body=None)

Creates or updates a script.

https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html

Parameters:

  • id (str) – Identifier for the stored script or search template. Must be unique within the cluster.

  • script (Mapping[str, Any] | None) – Contains the script or search template, its parameters, and its language.

  • context (str | None) – Context in which the script or search template should run. To prevent errors, the API immediately compiles the script or template in this context.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

rank_eval(*, requests=None, index=None, allow_no_indices=None, error_trace=None, expand_wildcards=None, filter_path=None, human=None, ignore_unavailable=None, metric=None, pretty=None, search_type=None, body=None)

Allows to evaluate the quality of ranked search results over a set of typical search queries

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-rank-eval.html

Parameters:

  • requests (Sequence[Mapping[str, Any]] | None) – A set of typical search requests, together with their provided ratings.

  • index (str | Sequence[str] | None) – Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard (*) expressions are supported. To target all data streams and indices in a cluster, omit this parameter or use _all or *.

  • allow_no_indices (bool | None) – If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

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

  • ignore_unavailable (bool | None) – If true, missing or closed indices are not included in the response.

  • metric (Mapping[str, Any] | None) – Definition of the evaluation metric to calculate.

  • search_type (str | None) – Search operation type

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

reindex(*, dest=None, source=None, conflicts=None, error_trace=None, filter_path=None, human=None, max_docs=None, pretty=None, refresh=None, requests_per_second=None, require_alias=None, script=None, scroll=None, size=None, slices=None, timeout=None, wait_for_active_shards=None, wait_for_completion=None, body=None)

Allows to copy documents from one index to another, optionally filtering the source documents by a query, changing the destination index settings, or fetching the documents from a remote cluster.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-reindex.html

Parameters:

  • dest (Mapping[str, Any] | None) – The destination you are copying to.

  • source (Mapping[str, Any] | None) – The source you are copying from.

  • conflicts (Literal['abort', 'proceed'] | str | None) – Set to proceed to continue reindexing even if there are conflicts.

  • max_docs (int | None) – The maximum number of documents to reindex.

  • refresh (bool | None) – If true, the request refreshes affected shards to make this operation visible to search.

  • requests_per_second (float | None) – The throttle for this request in sub-requests per second. Defaults to no throttle.

  • require_alias (bool | None) – If true, the destination must be an index alias.

  • script (Mapping[str, Any] | None) – The script to run to update the document source or metadata when reindexing.

  • scroll (Literal[-1] | ~typing.Literal[0] | str | None) – Specifies how long a consistent view of the index should be maintained for scrolled search.

  • size (int | None)

  • slices (int | Literal['auto'] | str | None) – The number of slices this task should be divided into. Defaults to 1 slice, meaning the task isn’t sliced into subtasks.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards.

  • wait_for_active_shards (int | Literal['all', 'index-setting'] | str | None) – The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

  • wait_for_completion (bool | None) – If true, the request blocks until the operation is complete.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

reindex_rethrottle(*, task_id, error_trace=None, filter_path=None, human=None, pretty=None, requests_per_second=None)

Changes the number of requests per second for a particular Reindex operation.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-reindex.html

Parameters:

  • task_id (str) – Identifier for the task.

  • requests_per_second (float | None) – The throttle for this request in sub-requests per second.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

render_search_template(*, id=None, error_trace=None, file=None, filter_path=None, human=None, params=None, pretty=None, source=None, body=None)

Allows to use the Mustache language to pre-render a search definition.

https://www.elastic.co/guide/en/elasticsearch/reference/master/render-search-template-api.html

Parameters:

  • id (str | None) – ID of the search template to render. If no source is specified, this or the id request body parameter is required.

  • file (str | None)

  • params (Mapping[str, Any] | None) – Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value.

  • source (str | None) – An inline search template. Supports the same parameters as the search API’s request body. These parameters also support Mustache variables. If no id or <templated-id> is specified, this parameter is required.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

scripts_painless_execute(*, context=None, context_setup=None, error_trace=None, filter_path=None, human=None, pretty=None, script=None, body=None)

Allows an arbitrary script to be executed and a result to be returned

https://www.elastic.co/guide/en/elasticsearch/painless/master/painless-execute-api.html

Parameters:

  • context (str | None) – The context that the script should run in.

  • context_setup (Mapping[str, Any] | None) – Additional parameters for the context.

  • script (Mapping[str, Any] | None) – The Painless script to execute.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

scroll(*, scroll_id=None, error_trace=None, filter_path=None, human=None, pretty=None, rest_total_hits_as_int=None, scroll=None, body=None)

Allows to retrieve a large numbers of results from a single search request.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-request-body.html#request-body-search-scroll

Parameters:

  • scroll_id (str | None) – Scroll ID of the search.

  • rest_total_hits_as_int (bool | None) – If true, the API response’s hit.total property is returned as an integer. If false, the API response’s hit.total property is returned as an object.

  • scroll (Literal[-1] | ~typing.Literal[0] | str | None) – Period to retain the search context for scrolling.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

search(*, 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, force_synthetic_source=None, from_=None, highlight=None, human=None, ignore_throttled=None, ignore_unavailable=None, indices_boost=None, knn=None, lenient=None, max_concurrent_shard_requests=None, min_compatible_shard_node=None, min_score=None, pit=None, post_filter=None, pre_filter_shard_size=None, preference=None, pretty=None, profile=None, q=None, query=None, rank=None, request_cache=None, rescore=None, rest_total_hits_as_int=None, routing=None, runtime_mappings=None, script_fields=None, scroll=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, body=None)

Returns results matching a query.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-search.html

Parameters:

  • index (str | Sequence[str] | None) – Comma-separated list of data streams, indices, and aliases to search. Supports wildcards (*). To search all data streams and indices, omit this parameter or use * or _all.

  • aggregations (Mapping[str, Mapping[str, Any]] | None) – Defines the aggregations that are run as part of the search request.

  • aggs (Mapping[str, Mapping[str, Any]] | None) – Defines the aggregations that are run as part of the search request.

  • allow_no_indices (bool | None) – If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • allow_partial_search_results (bool | None) – If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results.

  • analyze_wildcard (bool | None) – If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified.

  • analyzer (str | None) – Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified.

  • batched_reduce_size (int | None) – The number of shard results that should be reduced at once on the coordinating node. This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.

  • ccs_minimize_roundtrips (bool | None) – If true, network round-trips between the coordinating node and the remote clusters are minimized when executing cross-cluster search (CCS) requests.

  • collapse (Mapping[str, Any] | None) – Collapses search results the values of the specified field.

  • default_operator (Literal['and', 'or'] | str | None) – The default operator for query string query: AND or OR. This parameter can only be used when the q query string parameter is specified.

  • df (str | None) – Field to use as default where no field prefix is given in the query string. This parameter can only be used when the q query string parameter is specified.

  • 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[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

  • 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.

  • force_synthetic_source (bool | None) – Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.

  • from – Starting document offset. Needs to be non-negative. 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) – Specifies the highlighter to use for retrieving highlighted snippets from one or more fields in your search results.

  • ignore_throttled (bool | None) – If true, concrete, expanded or aliased indices will be ignored when frozen.

  • ignore_unavailable (bool | None) – If false, the request returns an error if it targets a missing or closed index.

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

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

  • lenient (bool | None) – If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can only be used when the q query string parameter is specified.

  • max_concurrent_shard_requests (int | None) – Defines 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_compatible_shard_node (str | None) – The minimum version of the node that can handle the request Any handling node with a lower version will fail the request.

  • min_score (float | None) – Minimum _score for matching documents. Documents with a lower _score are not included in the search results.

  • 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) – Use the post_filter parameter to filter search results. The search hits are filtered after the aggregations are calculated. A post filter has no impact on the aggregation results.

  • pre_filter_shard_size (int | None) – Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint). When unspecified, the pre-filter phase is executed if any of these conditions is met: the request targets more than 128 shards; the request targets one or more read-only index; the primary sort of the query targets an indexed field.

  • preference (str | None) – Nodes and shards used for the search. By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are: _only_local to run the search only on shards on the local node; _local to, if possible, run the search on shards on the local node, or if not, select shards using the default method; _only_nodes:<node-id>,<node-id> to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method; _prefer_nodes:<node-id>,<node-id> to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method; _shards:<shard>,<shard> to run the search only on the specified shards; <custom-string> (any string that does not start with _) to route searches with the same <custom-string> to the same shards in the same order.

  • profile (bool | None) – Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.

  • q (str | None) – Query in the Lucene query string syntax using query parameter search. Query parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.

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

  • rank (Mapping[str, Any] | None) – Defines the Reciprocal Rank Fusion (RRF) to use.

  • request_cache (bool | None) – If true, the caching of search results is enabled for requests where size is 0. Defaults to index level settings.

  • rescore (Mapping[str, Any] | Sequence[Mapping[str, Any]] | None) – Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.

  • 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 | None) – Custom value used to route operations to a specific shard.

  • 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.

  • scroll (Literal[-1] | ~typing.Literal[0] | str | None) – Period to retain the search context for scrolling. See Scroll search results. By default, this value cannot exceed 1d (24 hours). You can change this limit using the search.max_keep_alive cluster-level setting.

  • search_after (Sequence[None | bool | float | int | str | Any] | None) – Used to retrieve the next page of hits using a set of sort values from the previous page.

  • search_type (Literal['dfs_query_then_fetch', 'query_then_fetch'] | str | None) – How distributed term frequencies are calculated for relevance scoring.

  • seq_no_primary_term (bool | None) – If true, returns sequence number and primary term of the last modification of each hit.

  • 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) – Can be used to split a scrolled search into multiple slices that can be consumed independently.

  • sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None) – A comma-separated list of <field>:<direction> pairs.

  • 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 comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter. If the _source parameter is false, this parameter is ignored.

  • source_includes (str | Sequence[str] | None) – A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter. If the _source parameter is false, this parameter is ignored.

  • 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) – Defines a suggester that provides similar looking terms based on a provided text.

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

  • suggest_mode (Literal['always', 'missing', 'popular'] | str | None) – Specifies the suggest mode. This parameter can only be used when the suggest_field and suggest_text query string parameters are specified.

  • suggest_size (int | None) – Number of suggestions to return. This parameter can only be used when the suggest_field and suggest_text query string parameters are specified.

  • suggest_text (str | None) – The source text for which the suggestions should be returned. This parameter can only be used when the suggest_field and suggest_text query string parameters are specified.

  • 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. Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers. If set to 0 (default), the query does not terminate 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.

  • typed_keys (bool | None) – If true, aggregation and suggester names are be prefixed by their respective types in the response.

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

  • 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]

search_mvt(*, index, field, zoom, x, y, aggs=None, buffer=None, error_trace=None, exact_bounds=None, extent=None, fields=None, filter_path=None, grid_agg=None, grid_precision=None, grid_type=None, human=None, pretty=None, query=None, runtime_mappings=None, size=None, sort=None, track_total_hits=None, with_labels=None, body=None)

Searches a vector tile for geospatial values. Returns results as a binary Mapbox vector tile.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-vector-tile-api.html

Parameters:

  • index (str | Sequence[str]) – Comma-separated list of data streams, indices, or aliases to search

  • field (str) – Field containing geospatial data to return

  • zoom (int) – Zoom level for the vector tile to search

  • x (int) – X coordinate for the vector tile to search

  • y (int) – Y coordinate for the vector tile to search

  • aggs (Mapping[str, Mapping[str, Any]] | None) – Sub-aggregations for the geotile_grid. Supports the following aggregation types: - avg - cardinality - max - min - sum

  • buffer (int | None) – Size, in pixels, of a clipping buffer outside the tile. This allows renderers to avoid outline artifacts from geometries that extend past the extent of the tile.

  • exact_bounds (bool | None) – If false, the meta layer’s feature is the bounding box of the tile. If true, the meta layer’s feature is a bounding box resulting from a geo_bounds aggregation. The aggregation runs on <field> values that intersect the <zoom>/<x>/<y> tile with wrap_longitude set to false. The resulting bounding box may be larger than the vector tile.

  • extent (int | None) – Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.

  • fields (str | Sequence[str] | None) – Fields to return in the hits layer. Supports wildcards (*). This parameter does not support fields with array values. Fields with array values may return inconsistent results.

  • grid_agg (Literal['geohex', 'geotile'] | str | None) – Aggregation used to create a grid for the field.

  • grid_precision (int | None) – Additional zoom levels available through the aggs layer. For example, if <zoom> is 7 and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results don’t include the aggs layer.

  • grid_type (Literal['centroid', 'grid', 'point'] | str | None) – Determines the geometry type for features in the aggs layer. In the aggs layer, each feature represents a geotile_grid cell. If ‘grid’ each feature is a Polygon of the cells bounding box. If ‘point’ each feature is a Point that is the centroid of the cell.

  • query (Mapping[str, Any] | None) – Query DSL used to filter documents for the search.

  • 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.

  • size (int | None) – Maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don’t include the hits layer.

  • sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None) – Sorts features in the hits layer. By default, the API calculates a bounding box for each feature. It sorts features based on this box’s diagonal length, from longest to shortest.

  • 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.

  • with_labels (bool | None) – If true, the hits and aggs layers will contain additional point features representing suggested label positions for the original features.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

BinaryApiResponse

search_shards(*, index=None, allow_no_indices=None, error_trace=None, expand_wildcards=None, filter_path=None, human=None, ignore_unavailable=None, local=None, preference=None, pretty=None, routing=None)

Returns information about the indices and shards that a search request would be executed against.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-shards.html

Parameters:

  • index (str | Sequence[str] | None) – Returns the indices and shards that a search request would be executed against.

  • allow_no_indices (bool | None) – If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • ignore_unavailable (bool | None) – If false, the request returns an error if it targets a missing or closed index.

  • local (bool | None) – If true, the request retrieves information from the local node only.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

search_template(*, index=None, allow_no_indices=None, ccs_minimize_roundtrips=None, error_trace=None, expand_wildcards=None, explain=None, filter_path=None, human=None, id=None, ignore_throttled=None, ignore_unavailable=None, params=None, preference=None, pretty=None, profile=None, rest_total_hits_as_int=None, routing=None, scroll=None, search_type=None, source=None, typed_keys=None, body=None)

Allows to use the Mustache language to pre-render a search definition.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-template.html

Parameters:

  • index (str | Sequence[str] | None) – Comma-separated list of data streams, indices, and aliases to search. Supports wildcards (*).

  • allow_no_indices (bool | None) – If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • ccs_minimize_roundtrips (bool | None) – If true, network round-trips are minimized for cross-cluster search requests.

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • explain (bool | None) – If true, returns detailed information about score calculation as part of each hit.

  • id (str | None) – ID of the search template to use. If no source is specified, this parameter is required.

  • ignore_throttled (bool | None) – If true, specified concrete, expanded, or aliased indices are not included in the response when throttled.

  • ignore_unavailable (bool | None) – If false, the request returns an error if it targets a missing or closed index.

  • params (Mapping[str, Any] | None) – Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • profile (bool | None) – If true, the query execution is profiled.

  • rest_total_hits_as_int (bool | None) – If true, hits.total are rendered as an integer in the response.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • scroll (Literal[-1] | ~typing.Literal[0] | str | None) – Specifies how long a consistent view of the index should be maintained for scrolled search.

  • search_type (Literal['dfs_query_then_fetch', 'query_then_fetch'] | str | None) – The type of the search operation.

  • source (str | None) – An inline search template. Supports the same parameters as the search API’s request body. Also supports Mustache variables. If no id is specified, this parameter is required.

  • typed_keys (bool | None) – If true, the response prefixes aggregation and suggester names with their respective types.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

terms_enum(*, index, field=None, case_insensitive=None, error_trace=None, filter_path=None, human=None, index_filter=None, pretty=None, search_after=None, size=None, string=None, timeout=None, body=None)

The terms enum API can be used to discover terms in the index that begin with the provided string. It is designed for low-latency look-ups used in auto-complete scenarios.

https://www.elastic.co/guide/en/elasticsearch/reference/master/search-terms-enum.html

Parameters:

  • index (str) – Comma-separated list of data streams, indices, and index aliases to search. Wildcard (*) expressions are supported.

  • field (str | None) – The string to match at the start of indexed terms. If not provided, all terms in the field are considered.

  • case_insensitive (bool | None) – When true the provided search string is matched against index terms without case sensitivity.

  • index_filter (Mapping[str, Any] | None) – Allows to filter an index shard if the provided query rewrites to match_none.

  • search_after (str | None)

  • size (int | None) – How many matching terms to return.

  • string (str | None) – The string after which terms in the index should be returned. Allows for a form of pagination if the last result from one request is passed as the search_after parameter for a subsequent request.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – The maximum length of time to spend collecting results. Defaults to “1s” (one second). If the timeout is exceeded the complete flag set to false in the response and the results may be partial or empty.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

termvectors(*, index, id=None, doc=None, error_trace=None, field_statistics=None, fields=None, filter=None, filter_path=None, human=None, offsets=None, payloads=None, per_field_analyzer=None, positions=None, preference=None, pretty=None, realtime=None, routing=None, term_statistics=None, version=None, version_type=None, body=None)

Returns information and statistics about terms in the fields of a particular document.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-termvectors.html

Parameters:

  • index (str) – Name of the index that contains the document.

  • id (str | None) – Unique identifier of the document.

  • doc (Mapping[str, Any] | None) – An artificial document (a document not present in the index) for which you want to retrieve term vectors.

  • field_statistics (bool | None) – If true, the response includes the document count, sum of document frequencies, and sum of total term frequencies.

  • fields (str | Sequence[str] | None) – Comma-separated list or wildcard expressions of fields to include in the statistics. Used as the default list unless a specific field list is provided in the completion_fields or fielddata_fields parameters.

  • filter (Mapping[str, Any] | None) – Filter terms based on their tf-idf scores.

  • offsets (bool | None) – If true, the response includes term offsets.

  • payloads (bool | None) – If true, the response includes term payloads.

  • per_field_analyzer (Mapping[str, str] | None) – Overrides the default per-field analyzer.

  • positions (bool | None) – If true, the response includes term positions.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • realtime (bool | None) – If true, the request is real-time as opposed to near-real-time.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • term_statistics (bool | None) – If true, the response includes term frequency and document frequency.

  • version (int | None) – If true, returns the document version as part of a hit.

  • version_type (Literal['external', 'external_gte', 'force', 'internal'] | str | None) – Specific version type.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

update(*, index, id, detect_noop=None, doc=None, doc_as_upsert=None, error_trace=None, filter_path=None, human=None, if_primary_term=None, if_seq_no=None, lang=None, pretty=None, refresh=None, require_alias=None, retry_on_conflict=None, routing=None, script=None, scripted_upsert=None, source=None, source_excludes=None, source_includes=None, timeout=None, upsert=None, wait_for_active_shards=None, body=None)

Updates a document with a script or partial document.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-update.html

Parameters:

  • index (str) – The name of the index

  • id (str) – Document ID

  • detect_noop (bool | None) – Set to false to disable setting ‘result’ in the response to ‘noop’ if no change to the document occurred.

  • doc (Mapping[str, Any] | None) – A partial update to an existing document.

  • doc_as_upsert (bool | None) – Set to true to use the contents of ‘doc’ as the value of ‘upsert’

  • if_primary_term (int | None) – Only perform the operation if the document has this primary term.

  • if_seq_no (int | None) – Only perform the operation if the document has this sequence number.

  • lang (str | None) – The script language.

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | None) – If ‘true’, Elasticsearch refreshes the affected shards to make this operation visible to search, if ‘wait_for’ then wait for a refresh to make this operation visible to search, if ‘false’ do nothing with refreshes.

  • require_alias (bool | None) – If true, the destination must be an index alias.

  • retry_on_conflict (int | None) – Specify how many times should the operation be retried when a conflict occurs.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • script (Mapping[str, Any] | None) – Script to execute to update the document.

  • scripted_upsert (bool | None) – Set to true to execute the script whether or not the document exists.

  • source (bool | Mapping[str, Any] | None) – Set to false to disable source retrieval. You can also specify a comma-separated list of the fields you want to retrieve.

  • source_excludes (str | Sequence[str] | None) – Specify the source fields you want to exclude.

  • source_includes (str | Sequence[str] | None) – Specify the source fields you want to retrieve.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for dynamic mapping updates and active shards. This guarantees Elasticsearch waits for at least the timeout before failing. The actual wait time could be longer, particularly when multiple waits occur.

  • upsert (Mapping[str, Any] | None) – If the document does not already exist, the contents of ‘upsert’ are inserted as a new document. If the document exists, the ‘script’ is executed.

  • wait_for_active_shards (int | Literal['all', 'index-setting'] | str | None) – The number of shard copies that must be active before proceeding with the operations. Set to ‘all’ or any positive integer up to the total number of shards in the index (number_of_replicas+1). Defaults to 1 meaning the primary shard.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

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

Return type:

ObjectApiResponse[Any]

update_by_query(*, index, allow_no_indices=None, analyze_wildcard=None, analyzer=None, conflicts=None, default_operator=None, df=None, error_trace=None, expand_wildcards=None, filter_path=None, from_=None, human=None, ignore_unavailable=None, lenient=None, max_docs=None, pipeline=None, preference=None, pretty=None, query=None, refresh=None, request_cache=None, requests_per_second=None, routing=None, script=None, scroll=None, scroll_size=None, search_timeout=None, search_type=None, slice=None, slices=None, sort=None, stats=None, terminate_after=None, timeout=None, version=None, version_type=None, wait_for_active_shards=None, wait_for_completion=None, body=None)

Updates documents that match the specified query. If no query is specified, performs an update on every document in the index without changing the source, for example to pick up a mapping change.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-update-by-query.html

Parameters:

  • index (str | Sequence[str]) – Comma-separated list of data streams, indices, and aliases to search. Supports wildcards (*). To search all data streams or indices, omit this parameter or use * or _all.

  • allow_no_indices (bool | None) – If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • analyze_wildcard (bool | None) – If true, wildcard and prefix queries are analyzed.

  • analyzer (str | None) – Analyzer to use for the query string.

  • conflicts (Literal['abort', 'proceed'] | str | None) – What to do if update by query hits version conflicts: abort or proceed.

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

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

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • from – Starting offset (default: 0)

  • ignore_unavailable (bool | None) – If false, the request returns an error if it targets a missing or closed index.

  • lenient (bool | None) – If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.

  • max_docs (int | None) – The maximum number of documents to update.

  • pipeline (str | None) – ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to _none disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter.

  • preference (str | None) – Specifies the node or shard the operation should be performed on. Random by default.

  • query (Mapping[str, Any] | None) – Specifies the documents to update using the Query DSL.

  • refresh (bool | None) – If true, Elasticsearch refreshes affected shards to make the operation visible to search.

  • request_cache (bool | None) – If true, the request cache is used for this request.

  • requests_per_second (float | None) – The throttle for this request in sub-requests per second.

  • routing (str | None) – Custom value used to route operations to a specific shard.

  • script (Mapping[str, Any] | None) – The script to run to update the document source or metadata when updating.

  • scroll (Literal[-1] | ~typing.Literal[0] | str | None) – Period to retain the search context for scrolling.

  • scroll_size (int | None) – Size of the scroll request that powers the operation.

  • search_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Explicit timeout for each search request.

  • search_type (Literal['dfs_query_then_fetch', 'query_then_fetch'] | str | None) – The type of the search operation. Available options: query_then_fetch, dfs_query_then_fetch.

  • slice (Mapping[str, Any] | None) – Slice the request manually using the provided slice ID and total number of slices.

  • slices (int | Literal['auto'] | str | None) – The number of slices this task should be divided into.

  • sort (Sequence[str] | None) – A comma-separated list of <field>:<direction> pairs.

  • stats (Sequence[str] | None) – Specific tag of the request for logging and statistical purposes.

  • 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. Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period each update request waits for the following operations: dynamic mapping updates, waiting for active shards.

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

  • version_type (bool | None) – Should the document increment the version number (internal) on hit or not (reindex)

  • wait_for_active_shards (int | Literal['all', 'index-setting'] | str | None) – The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

  • wait_for_completion (bool | None) – If true, the request blocks until the operation is complete.

  • 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]

update_by_query_rethrottle(*, task_id, error_trace=None, filter_path=None, human=None, pretty=None, requests_per_second=None)

Changes the number of requests per second for a particular Update By Query operation.

https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-update-by-query.html

Parameters:

  • task_id (str) – The ID for the task.

  • requests_per_second (float | None) – The throttle for this request in sub-requests per second.

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]