Elasticsearch
- class elasticsearch.client.Elasticsearch(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.Transport'>, 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)
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 (Transport | 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)
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.15/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)
Clears the search context and results for a scrolling search.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/clear-scroll-api.html
- 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)
Closes a point-in-time.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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.15/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)
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.15/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)
Removes a JSON document from the specified index.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Deletes documents that match the specified query.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Changes the number of requests per second for a particular Delete By Query operation.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/docs-delete-by-query.html
- delete_script(*, id, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None)
Deletes a stored script or search template.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Checks if a document in an index exists.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Checks if a document’s _source is stored.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Returns information about why a specific document matches (or doesn’t match) a query.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
The field capabilities API returns the information about the capabilities of fields among multiple indices. The field capabilities API returns runtime fields like any other field. For example, a runtime field with a type of keyword is returned as any other field that belongs to the keyword family.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Returns a document.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Retrieves a stored script or search template.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/modules-scripting.html
- Parameters:
- Return type:
- get_script_context(*, error_trace=None, filter_path=None, human=None, pretty=None)
Returns all script contexts.
https://www.elastic.co/guide/en/elasticsearch/painless/8.15/painless-contexts.html
- get_script_languages(*, error_trace=None, filter_path=None, human=None, pretty=None)
Returns available script types, languages and contexts
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Returns the source of a document.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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.15/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)
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.15/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)
Returns basic information about the cluster.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Performs a kNN search.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Allows to get multiple documents in one request.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Allows to execute several search operations in one request.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Runs multiple templated searches with a single request.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Returns multiple termvectors in one request.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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, preference=None, pretty=None, routing=None)
A search request by default executes 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.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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.
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)
Creates or updates a stored script or search template.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Enables you to evaluate the quality of ranked search results over a set of typical search queries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Allows to copy documents from one index to another, optionally filtering the source documents by a query, changing the destination index settings, or fetching the documents from a remote cluster.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Copies documents from a source to a destination.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Renders a search template as a search request body.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Runs a script and returns a result.
https://www.elastic.co/guide/en/elasticsearch/painless/8.15/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)
Allows to retrieve a large numbers of results from a single search request.
- 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)
Returns 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.15/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)
Searches a vector tile for geospatial values. Returns results as a binary Mapbox vector tile.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Returns information about the indices and shards that a search request would be executed against.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Runs a search with a search template.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
The terms enum API can be used to discover terms in the index that begin with the provided string. It is designed for low-latency look-ups used in auto-complete scenarios.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Returns information and statistics about terms in the fields of a particular document.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
Updates a document with a script or partial document.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/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)
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.15/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)
Changes the number of requests per second for a particular Update By Query operation.
https://www.elastic.co/guide/en/elasticsearch/reference/8.15/docs-update-by-query.html