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 ifstats_only
is set toTrue
. Note that by default we raise aBulkIndexError
when we encounter an error so options likestats_only
only+ apply whenraise_on_error
is set toFalse
.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:
client (AsyncElasticsearch) – instance of
AsyncElasticsearch
to useactions (Iterable[bytes | str | Dict[str, Any]] | AsyncIterable[bytes | str | Dict[str, Any]]) – iterator containing the actions
stats_only (bool) – if True only report number of successful/failed operations instead of just number of successful and a list of error responses
ignore_status (int | Collection[int]) – list of HTTP status code that you want to ignore
client
actions
stats_only
ignore_status
args (Any)
kwargs (Any)
- Return type:
Any additional keyword arguments will be passed to
async_streaming_bulk()
which is used to execute the operation, seeasync_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=(), retry_on_status=(429, ), *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 a429
status code. Useretry_on_status
to configure which status codes will be retried. To do this it will wait (by calling asyncio.sleep which will block) forinitial_backoff
seconds and then, every subsequent rejection for the same chunk, for double the time every time up tomax_backoff
seconds.
- Parameters:
client (AsyncElasticsearch) – instance of
AsyncElasticsearch
to useactions (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 tobulk
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).
retry_on_status (int | Collection[int]) – HTTP status code that will trigger a retry. (if None is specified only status 429 will retry).
max_retries (int) – maximum number of times a document will be retried when retry_on_status (defaulting to
429
) is received, set to 0 (default) for no retriesinitial_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
retry_on_status
args (Any)
kwargs (Any)
- Return type:
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 usingscan
.
- Parameters:
client (AsyncElasticsearch) – instance of
AsyncElasticsearch
to usescroll (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
toscan
- 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
areindex()
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
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:
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:
hosts (str | Sequence[str | Mapping[str, str | int] | NodeConfig] | None)
cloud_id (str | None)
bearer_auth (str | None)
opaque_id (str | None)
headers (DefaultType | Mapping[str, str])
connections_per_node (DefaultType | int)
http_compress (DefaultType | bool)
verify_certs (DefaultType | bool)
ca_certs (DefaultType | str)
client_cert (DefaultType | str)
client_key (DefaultType | str)
ssl_assert_hostname (DefaultType | str)
ssl_assert_fingerprint (DefaultType | str)
ssl_version (DefaultType | int)
ssl_context (DefaultType | Any)
ssl_show_warn (DefaultType | bool)
transport_class (Type[AsyncTransport])
request_timeout (DefaultType | None | float)
node_class (DefaultType | Type[BaseNode])
node_pool_class (DefaultType | Type[NodePool])
randomize_nodes_in_pool (DefaultType | bool)
node_selector_class (DefaultType | Type[NodeSelector])
dead_node_backoff_factor (DefaultType | float)
max_dead_node_backoff (DefaultType | float)
serializer (Serializer | None)
serializers (DefaultType | Mapping[str, Serializer])
default_mimetype (str)
max_retries (DefaultType | int)
retry_on_status (DefaultType | int | Collection[int])
retry_on_timeout (DefaultType | bool)
sniff_on_start (DefaultType | bool)
sniff_before_requests (DefaultType | bool)
sniff_on_node_failure (DefaultType | bool)
sniff_timeout (DefaultType | None | float)
min_delay_between_sniffing (DefaultType | None | float)
sniffed_node_callback (Callable[[Dict[str, Any], NodeConfig], NodeConfig | None] | None)
meta_header (DefaultType | bool)
timeout (DefaultType | None | float)
randomize_hosts (DefaultType | bool)
host_info_callback (Callable[[Dict[str, Any], Dict[str, str | int]], Dict[str, str | int] | None] | None)
sniffer_timeout (DefaultType | None | float)
sniff_on_connection_fail (DefaultType | bool)
http_auth (DefaultType | Any)
maxsize (DefaultType | int)
_transport (AsyncTransport | None)
- 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)
Bulk index or delete documents. Performs multiple indexing or delete operations in a single API call. This reduces overhead and can greatly increase indexing speed.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/docs-bulk.html
- Parameters:
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 (bool | str | Literal['false', 'true', 'wait_for'] | 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 (str | Literal[-1] | ~typing.Literal[0] | None) – Period each action waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.
wait_for_active_shards (int | str | Literal['all', 'index-setting'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- clear_scroll(*, error_trace=None, filter_path=None, human=None, pretty=None, scroll_id=None, body=None)
Clear a scrolling search. Clear the search context and results for a scrolling search.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/clear-scroll-api.html
- 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. A point in time must be opened explicitly before being used in search requests. The keep_alive parameter tells Elasticsearch how long it should persist. A point in time is automatically closed when the keep_alive period has elapsed. However, keeping points in time has a cost; close them as soon as they are no longer required for search requests.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/point-in-time-api.html
- 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/8.16/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 (str | Literal['and', 'or'] | 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[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Index a document. Adds a JSON document to the specified data stream or index and makes it searchable. If the target is an index and the document already exists, the request updates the document and increments its version.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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.
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 (bool | str | Literal['false', 'true', 'wait_for'] | 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 (str | Literal[-1] | ~typing.Literal[0] | 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 (str | Literal['external', 'external_gte', 'force', 'internal'] | None) – Specific version type: external, external_gte.
wait_for_active_shards (int | str | Literal['all', 'index-setting'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Delete a document. Removes a JSON document from the specified index.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (bool | str | Literal['false', 'true', 'wait_for'] | 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 (str | Literal[-1] | ~typing.Literal[0] | 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 (str | Literal['external', 'external_gte', 'force', 'internal'] | None) – Specific version type: external, external_gte.
wait_for_active_shards (int | str | Literal['all', 'index-setting'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Delete documents. Deletes documents that match the specified query.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['abort', 'proceed'] | None) – What to do if delete by query hits version conflicts: abort or proceed.
default_operator (str | Literal['and', 'or'] | 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[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | 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 (str | Literal[-1] | ~typing.Literal[0] | None) – Period to retain the search context for scrolling.
scroll_size (int | None) – Size of the scroll request that powers the operation.
search_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – Explicit timeout for each search request. Defaults to no timeout.
search_type (str | Literal['dfs_query_then_fetch', 'query_then_fetch'] | 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 | str | Literal['auto'] | 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 (str | Literal[-1] | ~typing.Literal[0] | 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 | str | Literal['all', 'index-setting'] | 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)
from_ (int | None)
human (bool | None)
pretty (bool | None)
- Return type:
- delete_by_query_rethrottle(*, task_id, error_trace=None, filter_path=None, human=None, pretty=None, requests_per_second=None)
Throttle a delete by query operation. Change the number of requests per second for a particular delete by query operation. Rethrottling that speeds up the query takes effect immediately but rethrotting that slows down the query takes effect after completing the current batch to prevent scroll timeouts.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/docs-delete-by-query.html
- delete_script(*, id, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None)
Delete a script or search template. Deletes a stored script or search template.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-scripting.html
- Parameters:
id (str) – Identifier for the stored script or search template.
master_timeout (str | Literal[-1] | ~typing.Literal[0] | 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 (str | Literal[-1] | ~typing.Literal[0] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Check a document. Checks if a specified document exists.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['external', 'external_gte', 'force', 'internal'] | None) – Specific version type: external, external_gte.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Check for a document source. Checks if a document’s _source is stored.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['external', 'external_gte', 'force', 'internal'] | None) – Specific version type: external, external_gte.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Explain a document match result. Returns information about why a specific document matches, or doesn’t match, a query.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['and', 'or'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Get the field capabilities. Get information about the capabilities of fields among multiple indices. For data streams, the API returns field capabilities among the stream’s backing indices. It returns runtime fields like any other field. For example, a runtime field with a type of keyword is returned the same as any other field that belongs to the keyword family.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Get a document by its ID. Retrieves the document with the specified ID from an index.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['external', 'external_gte', 'force', 'internal'] | None) – Specific version type: internal, external, external_gte.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- get_script(*, id, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None)
Get a script or search template. Retrieves a stored script or search template.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-scripting.html
- Parameters:
- Return type:
- get_script_context(*, error_trace=None, filter_path=None, human=None, pretty=None)
Get script contexts. Get a list of supported script contexts and their methods.
https://www.elastic.co/guide/en/elasticsearch/painless/8.16/painless-contexts.html
- get_script_languages(*, error_trace=None, filter_path=None, human=None, pretty=None)
Get script languages. Get a list of available script types, languages, and contexts.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-scripting.html
- 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)
Get a document’s source. Returns the source of a document.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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.
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 (str | Literal['external', 'external_gte', 'force', 'internal'] | None) – Specific version type: internal, external, external_gte.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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/8.16/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 (str | Literal[-1] | ~typing.Literal[0] | None) – Explicit operation timeout.
verbose (bool | None) – Opt-in for more information about the health of the system.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Index a document. Adds a JSON document to the specified data stream or index and makes it searchable. If the target is an index and the document already exists, the request updates the document and increments its version.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/docs-index_.html
- Parameters:
index (str) – Name of the data stream or index to target.
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 (str | Literal['create', 'index'] | 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 (bool | str | Literal['false', 'true', 'wait_for'] | 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 (str | Literal[-1] | ~typing.Literal[0] | 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 (str | Literal['external', 'external_gte', 'force', 'internal'] | None) – Specific version type: external, external_gte.
wait_for_active_shards (int | str | Literal['all', 'index-setting'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- info(*, error_trace=None, filter_path=None, human=None, pretty=None)
Get cluster info. Returns basic information about the cluster.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/index.html
- knn_search(*, index, knn=None, docvalue_fields=None, error_trace=None, fields=None, filter=None, filter_path=None, human=None, pretty=None, routing=None, source=None, stored_fields=None, body=None)
Run a knn search. NOTE: The kNN search API has been replaced by the knn option in the search API. Perform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents. Given a query vector, the API finds the k closest vectors and returns those documents as search hits. Elasticsearch uses the HNSW algorithm to support efficient kNN search. Like most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed. This means the results returned are not always the true k closest neighbors. The kNN search API supports restricting the search using a filter. The search will return the top k documents that also match the filter query.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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
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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Get multiple documents. Get multiple JSON documents by ID from one or more indices. If you specify an index in the request URI, you only need to specify the document IDs in the request body. To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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, include_named_queries_score=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)
Run multiple searches. The format of the request is similar to the bulk API format and makes use of the newline delimited JSON (NDJSON) format. The structure is as follows:
` header\n body\n header\n body\n `
This structure is specifically optimized to reduce parsing if a specific search ends up redirected to another node. IMPORTANT: The final line of data must end with a newline character n. Each newline character may be preceded by a carriage return r. When sending requests to this endpoint the Content-Type header should be set to application/x-ndjson.https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-multi-search.html
- Parameters:
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[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | 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.
include_named_queries_score (bool | None) – Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false) This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.
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 (str | Literal['dfs_query_then_fetch', 'query_then_fetch'] | 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.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Run multiple templated searches.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-multi-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 *.
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 (str | Literal['dfs_query_then_fetch', 'query_then_fetch'] | 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.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Get multiple term vectors. You can specify existing documents by index and ID or provide artificial documents in the body of the request. You can specify the index in the request body or request URI. The response contains a docs array with all the fetched termvectors. Each element has the structure provided by the termvectors API.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['external', 'external_gte', 'force', 'internal'] | None) – Specific version type.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- open_point_in_time(*, index, keep_alive, error_trace=None, expand_wildcards=None, filter_path=None, human=None, ignore_unavailable=None, index_filter=None, preference=None, pretty=None, routing=None, body=None)
Open a point in time. A search request by default runs against the most recent visible data of the target indices, which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple search requests using the same point in time. For example, if refreshes happen between search_after requests, then the results of those requests might not be consistent as changes happening between searches are only visible to the more recent point in time. A point in time must be opened explicitly before being used in search requests. The keep_alive parameter tells Elasticsearch how long it should persist.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal[-1] | ~typing.Literal[0]) – Extends the time to live of the corresponding point in time.
expand_wildcards (Sequence[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | 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.
index_filter (Mapping[str, Any] | None) – Allows to filter indices if the provided query rewrites to match_none on every shard.
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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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
- put_script(*, id, script=None, context=None, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None, body=None)
Create or update a script or search template. Creates or updates a stored script or search template.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal[-1] | ~typing.Literal[0] | 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 (str | Literal[-1] | ~typing.Literal[0] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Evaluate ranked search results. Evaluate the quality of ranked search results over a set of typical search queries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | None) – Whether to expand wildcard expression to concrete indices that are open, closed or both.
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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Reindex documents. Copies documents from a source to a destination. The source can be any existing index, alias, or data stream. The destination must differ from the source. For example, you cannot reindex a data stream into itself.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['abort', 'proceed'] | 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 (str | Literal[-1] | ~typing.Literal[0] | None) – Specifies how long a consistent view of the index should be maintained for scrolled search.
size (int | None)
slices (int | str | Literal['auto'] | None) – The number of slices this task should be divided into. Defaults to 1 slice, meaning the task isn’t sliced into subtasks.
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – Period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards.
wait_for_active_shards (int | str | Literal['all', 'index-setting'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- reindex_rethrottle(*, task_id, error_trace=None, filter_path=None, human=None, pretty=None, requests_per_second=None)
Throttle a reindex operation. Change the number of requests per second for a particular reindex operation.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/docs-reindex.html
- render_search_template(*, id=None, error_trace=None, file=None, filter_path=None, human=None, params=None, pretty=None, source=None, body=None)
Render a search template. Render a search template as a search request body.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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)
human (bool | None)
pretty (bool | None)
- Return type:
- scripts_painless_execute(*, context=None, context_setup=None, error_trace=None, filter_path=None, human=None, pretty=None, script=None, body=None)
Run a script. Runs a script and returns a result.
https://www.elastic.co/guide/en/elasticsearch/painless/8.16/painless-execute-api.html
- Parameters:
- Return type:
- scroll(*, scroll_id=None, error_trace=None, filter_path=None, human=None, pretty=None, rest_total_hits_as_int=None, scroll=None, body=None)
Run a scrolling search. IMPORTANT: The scroll API is no longer recommend for deep pagination. If you need to preserve the index state while paging through more than 10,000 hits, use the search_after parameter with a point in time (PIT). The scroll API gets large sets of results from a single scrolling search request. To get the necessary scroll ID, submit a search API request that includes an argument for the scroll query parameter. The scroll parameter indicates how long Elasticsearch should retain the search context for the request. The search response returns a scroll ID in the _scroll_id response body parameter. You can then use the scroll ID with the scroll API to retrieve the next batch of results for the request. If the Elasticsearch security features are enabled, the access to the results of a specific scroll ID is restricted to the user or API key that submitted the search. You can also use the scroll API to specify a new scroll parameter that extends or shortens the retention period for the search context. IMPORTANT: Results from a scrolling search reflect the state of the index at the time of the initial search request. Subsequent indexing or document changes only affect later search and scroll requests.
- 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 (str | Literal[-1] | ~typing.Literal[0] | None) – Period to retain the search context for scrolling.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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, include_named_queries_score=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, retriever=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)
Run a search. Get search hits that match the query defined in the request. You can provide search queries using the q query string parameter or the request body. If both are specified, only the query parameter is used.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['and', 'or'] | 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[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | 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.
include_named_queries_score (bool | None) – Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false) This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.
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.
retriever (Mapping[str, Any] | None) – A retriever is a specification to describe top documents returned from a search. A retriever replaces other elements of the search API that also return top documents such as query and knn.
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 (str | Literal[-1] | ~typing.Literal[0] | 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 (str | Literal['dfs_query_then_fetch', 'query_then_fetch'] | 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 (str | Literal['always', 'missing', 'popular'] | 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)
from_ (int | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Search a vector tile. Search a vector tile for geospatial values.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['geohex', 'geotile'] | 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 (str | Literal['centroid', 'grid', 'point'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Get the search shards. Get the indices and shards that a search request would be run against. This information can be useful for working out issues or planning optimizations with routing and shard preferences. When filtered aliases are used, the filter is returned as part of the indices section.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Run a search with a search template.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | 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 (str | Literal[-1] | ~typing.Literal[0] | None) – Specifies how long a consistent view of the index should be maintained for scrolled search.
search_type (str | Literal['dfs_query_then_fetch', 'query_then_fetch'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Get terms in an index. Discover terms that match a partial string in an index. This “terms enum” API is designed for low-latency look-ups used in auto-complete scenarios. If the complete property in the response is false, the returned terms set may be incomplete and should be treated as approximate. This can occur due to a few reasons, such as a request timeout or a node error. NOTE: The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal[-1] | ~typing.Literal[0] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Get term vector information. Get information and statistics about terms in the fields of a particular document.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['external', 'external_gte', 'force', 'internal'] | None) – Specific version type.
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
Update a document. Updates a document by running a script or passing a partial document.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (bool | str | Literal['false', 'true', 'wait_for'] | 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 (str | Literal[-1] | ~typing.Literal[0] | 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 | str | Literal['all', 'index-setting'] | 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)
human (bool | None)
pretty (bool | None)
- Return type:
- 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, q=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)
Update documents. Updates documents that match the specified query. If no query is specified, performs an update on every document in the data stream or index without modifying the source, which is useful for picking up mapping changes.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/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 (str | Literal['abort', 'proceed'] | None) – What to do if update by query hits version conflicts: abort or proceed.
default_operator (str | Literal['and', 'or'] | 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[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | 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.
q (str | None) – Query in the Lucene query string syntax.
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 (str | Literal[-1] | ~typing.Literal[0] | None) – Period to retain the search context for scrolling.
scroll_size (int | None) – Size of the scroll request that powers the operation.
search_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – Explicit timeout for each search request.
search_type (str | Literal['dfs_query_then_fetch', 'query_then_fetch'] | 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 | str | Literal['auto'] | 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 (str | Literal[-1] | ~typing.Literal[0] | 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 | str | Literal['all', 'index-setting'] | 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)
from_ (int | None)
human (bool | None)
pretty (bool | None)
- Return type:
- update_by_query_rethrottle(*, task_id, error_trace=None, filter_path=None, human=None, pretty=None, requests_per_second=None)
Throttle an update by query operation. Change the number of requests per second for a particular update by query operation. Rethrottling that speeds up the query takes effect immediately but rethrotting that slows down the query takes effect after completing the current batch to prevent scroll timeouts.
https://www.elastic.co/guide/en/elasticsearch/reference/8.16/docs-update-by-query.html