`_
+ .. raw:: html
+
+ Reindex documents.
+ Copy documents from a source to a destination.
+ You can copy all documents to the destination index or reindex a subset of the documents.
+ The source can be any existing index, alias, or data stream.
+ The destination must differ from the source.
+ For example, you cannot reindex a data stream into itself.
+ IMPORTANT: Reindex requires _source to be enabled for all documents in the source.
+ The destination should be configured as wanted before calling the reindex API.
+ Reindex does not copy the settings from the source or its associated template.
+ Mappings, shard counts, and replicas, for example, must be configured ahead of time.
+ If the Elasticsearch security features are enabled, you must have the following security privileges:
+
+ - The
read index privilege for the source data stream, index, or alias.
+ - The
write index privilege for the destination data stream, index, or index alias.
+ - To automatically create a data stream or index with a reindex API request, you must have the
auto_configure, create_index, or manage index privilege for the destination data stream, index, or alias.
+ - If reindexing from a remote cluster, the
source.remote.user must have the monitor cluster privilege and the read index privilege for the source data stream, index, or alias.
+
+ If reindexing from a remote cluster, you must explicitly allow the remote host in the reindex.remote.whitelist setting.
+ Automatic data stream creation requires a matching index template with data stream enabled.
+ The dest element can be configured like the index API to control optimistic concurrency control.
+ Omitting version_type or setting it to internal causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID.
+ Setting version_type to external causes Elasticsearch to preserve the version from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source.
+ Setting op_type to create causes the reindex API to create only missing documents in the destination.
+ All existing documents will cause a version conflict.
+ IMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an op_type of create.
+ A reindex can only add new documents to a destination data stream.
+ It cannot update existing documents in a destination data stream.
+ By default, version conflicts abort the reindex process.
+ To continue reindexing if there are conflicts, set the conflicts request body property to proceed.
+ In this case, the response includes a count of the version conflicts that were encountered.
+ Note that the handling of other error types is unaffected by the conflicts property.
+ Additionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than max_docs until it has successfully indexed max_docs documents into the target or it has gone through every document in the source query.
+ NOTE: The reindex API makes no effort to handle ID collisions.
+ The last document written will "win" but the order isn't usually predictable so it is not a good idea to rely on this behavior.
+ Instead, make sure that IDs are unique by using a script.
+ Running reindex asynchronously
+ If the request contains wait_for_completion=false, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task.
+ Elasticsearch creates a record of this task as a document at _tasks/<task_id>.
+ Reindex from multiple sources
+ If you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources.
+ That way you can resume the process if there are any errors by removing the partially completed source and starting over.
+ It also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel.
+ For example, you can use a bash script like this:
+ for index in i1 i2 i3 i4 i5; do
+ curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{
+ "source": {
+ "index": "'$index'"
+ },
+ "dest": {
+ "index": "'$index'-reindexed"
+ }
+ }'
+ done
+
+ Throttling
+ Set requests_per_second to any positive decimal number (1.4, 6, 1000, for example) to throttle the rate at which reindex issues batches of index operations.
+ Requests are throttled by padding each batch with a wait time.
+ To turn off throttling, set requests_per_second to -1.
+ The throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding.
+ The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing.
+ By default the batch size is 1000, so if requests_per_second is set to 500:
+ target_time = 1000 / 500 per second = 2 seconds
+ wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
+
+ Since the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set.
+ This is "bursty" instead of "smooth".
+ Slicing
+ Reindex supports sliced scroll to parallelize the reindexing process.
+ This parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.
+ NOTE: Reindexing from remote clusters does not support manual or automatic slicing.
+ You can slice a reindex request manually by providing a slice ID and total number of slices to each request.
+ You can also let reindex automatically parallelize by using sliced scroll to slice on _id.
+ The slices parameter specifies the number of slices to use.
+ Adding slices to the reindex request just automates the manual process, creating sub-requests which means it has some quirks:
+
+ - You can see these requests in the tasks API. These sub-requests are "child" tasks of the task for the request with slices.
+ - Fetching the status of the task for the request with
slices only contains the status of completed slices.
+ - These sub-requests are individually addressable for things like cancellation and rethrottling.
+ - Rethrottling the request with
slices will rethrottle the unfinished sub-request proportionally.
+ - Canceling the request with
slices will cancel each sub-request.
+ - Due to the nature of
slices, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
+ - Parameters like
requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being reindexed.
+ - Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time.
+
+ If slicing automatically, setting slices to auto will choose a reasonable number for most indices.
+ If slicing manually or otherwise tuning automatic slicing, use the following guidelines.
+ Query performance is most efficient when the number of slices is equal to the number of shards in the index.
+ If that number is large (for example, 500), choose a lower number as too many slices will hurt performance.
+ Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
+ Indexing performance scales linearly across available resources with the number of slices.
+ Whether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources.
+ Modify documents during reindexing
+ Like _update_by_query, reindex operations support a script that modifies the document.
+ Unlike _update_by_query, the script is allowed to modify the document's metadata.
+ Just as in _update_by_query, you can set ctx.op to change the operation that is run on the destination.
+ For example, set ctx.op to noop if your script decides that the document doesn’t have to be indexed in the destination. This "no operation" will be reported in the noop counter in the response body.
+ Set ctx.op to delete if your script decides that the document must be deleted from the destination.
+ The deletion will be reported in the deleted counter in the response body.
+ Setting ctx.op to anything else will return an error, as will setting any other field in ctx.
+ Think of the possibilities! Just be careful; you are able to change:
+
+ _id_index_version_routing
+ Setting _version to null or clearing it from the ctx map is just like not sending the version in an indexing request.
+ It will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API.
+ Reindex from remote
+ Reindex supports reindexing from a remote Elasticsearch cluster.
+ The host parameter must contain a scheme, host, port, and optional path.
+ The username and password parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication.
+ Be sure to use HTTPS when using basic authentication or the password will be sent in plain text.
+ There are a range of settings available to configure the behavior of the HTTPS connection.
+ When using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key.
+ Remote hosts must be explicitly allowed with the reindex.remote.whitelist setting.
+ It can be set to a comma delimited list of allowed remote host and port combinations.
+ Scheme is ignored; only the host and port are used.
+ For example:
+ reindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*"]
+
+ The list of allowed hosts must be configured on any nodes that will coordinate the reindex.
+ This feature should work with remote clusters of any version of Elasticsearch.
+ This should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version.
+ WARNING: Elasticsearch does not support forward compatibility across major versions.
+ For example, you cannot reindex from a 7.x cluster into a 6.x cluster.
+ To enable queries sent to older versions of Elasticsearch, the query parameter is sent directly to the remote host without validation or modification.
+ NOTE: Reindexing from remote clusters does not support manual or automatic slicing.
+ Reindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb.
+ If the remote index includes very large documents you'll need to use a smaller batch size.
+ It is also possible to set the socket read timeout on the remote connection with the socket_timeout field and the connection timeout with the connect_timeout field.
+ Both default to 30 seconds.
+ Configuring SSL parameters
+ Reindex from remote supports configurable SSL settings.
+ These must be specified in the elasticsearch.yml file, with the exception of the secure settings, which you add in the Elasticsearch keystore.
+ It is not possible to configure SSL in the body of the reindex request.
+
+
+ ``_
:param dest: The destination you are copying to.
:param source: The source you are copying from.
- :param conflicts: Set to proceed to continue reindexing even if there are conflicts.
- :param max_docs: The maximum number of documents to reindex.
+ :param conflicts: Indicates whether to continue reindexing even when there are
+ conflicts.
+ :param max_docs: The maximum number of documents to reindex. By default, all
+ documents are reindexed. If it is a value less then or equal to `scroll_size`,
+ a scroll will not be used to retrieve the results for the operation. If `conflicts`
+ is set to `proceed`, the reindex operation could attempt to reindex more
+ documents from the source than `max_docs` until it has successfully indexed
+ `max_docs` documents into the target or it has gone through every document
+ in the source query.
:param refresh: If `true`, the request refreshes affected shards to make this
operation visible to search.
:param requests_per_second: The throttle for this request in sub-requests per
- second. Defaults to no throttle.
+ second. By default, there is no throttle.
:param require_alias: If `true`, the destination must be an index alias.
:param script: The script to run to update the document source or metadata when
reindexing.
- :param scroll: Specifies how long a consistent view of the index should be maintained
- for scrolled search.
- :param size:
- :param slices: The number of slices this task should be divided into. Defaults
- to 1 slice, meaning the task isn’t sliced into subtasks.
- :param timeout: Period each indexing waits for automatic index creation, dynamic
- mapping updates, and waiting for active shards.
+ :param scroll: The period of time that a consistent view of the index should
+ be maintained for scrolled search.
+ :param slices: The number of slices this task should be divided into. It defaults
+ to one slice, which means the task isn't sliced into subtasks. Reindex supports
+ sliced scroll to parallelize the reindexing process. This parallelization
+ can improve efficiency and provide a convenient way to break the request
+ down into smaller parts. NOTE: Reindexing from remote clusters does not support
+ manual or automatic slicing. If set to `auto`, Elasticsearch chooses the
+ number of slices to use. This setting will use one slice per shard, up to
+ a certain limit. If there are multiple sources, it will choose the number
+ of slices based on the index or backing index with the smallest number of
+ shards.
+ :param timeout: The period each indexing waits for automatic index creation,
+ dynamic mapping updates, and waiting for active shards. By default, Elasticsearch
+ waits for at least one minute before failing. The actual wait time could
+ be longer, particularly when multiple waits occur.
:param wait_for_active_shards: 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`).
+ before proceeding with the operation. Set it to `all` or any positive integer
+ up to the total number of shards in the index (`number_of_replicas+1`). The
+ default value is one, which means it waits for each primary shard to be active.
:param wait_for_completion: If `true`, the request blocks until the operation
is complete.
"""
@@ -3406,8 +4271,6 @@ async def reindex(
__body["max_docs"] = max_docs
if script is not None:
__body["script"] = script
- if size is not None:
- __body["size"] = size
__headers = {"accept": "application/json", "content-type": "application/json"}
return await self.perform_request( # type: ignore[return-value]
"POST",
@@ -3431,13 +4294,24 @@ async def reindex_rethrottle(
requests_per_second: t.Optional[float] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Copies documents from a source to a destination.
+ .. raw:: html
+
+ Throttle a reindex operation.
+ Change the number of requests per second for a particular reindex operation.
+ For example:
+ POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
+
+ Rethrottling that speeds up the query takes effect immediately.
+ Rethrottling that slows down the query will take effect after completing the current batch.
+ This behavior prevents scroll timeouts.
+
- ``_
+ ``_
- :param task_id: Identifier for the task.
+ :param task_id: The task identifier, which can be found by using the tasks API.
:param requests_per_second: The throttle for this request in sub-requests per
- second.
+ second. It can be either `-1` to turn off throttling or any decimal number
+ like `1.7` or `12` to throttle to that level.
"""
if task_id in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'task_id'")
@@ -3482,17 +4356,21 @@ async def render_search_template(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Renders a search template as a search request body.
+ .. raw:: html
+
+ Render a search template.
+ Render a search template as a search request body.
- ``_
- :param id: ID of the search template to render. If no `source` is specified,
+ ``_
+
+ :param id: The ID of the search template to render. If no `source` is specified,
this or the `id` request body parameter is required.
:param file:
:param params: Key-value pairs used to replace Mustache variables in the template.
The key is the variable name. The value is the variable value.
- :param source: An inline search template. Supports the same parameters as the
- search API's request body. These parameters also support Mustache variables.
+ :param source: An inline search template. It supports the same parameters as
+ the search API's request body. These parameters also support Mustache variables.
If no `id` or `` is specified, this parameter is required.
"""
__path_parts: t.Dict[str, str]
@@ -3519,11 +4397,7 @@ async def render_search_template(
__body["params"] = params
if source is not None:
__body["source"] = source
- if not __body:
- __body = None # type: ignore[assignment]
- __headers = {"accept": "application/json"}
- if __body is not None:
- __headers["content-type"] = "application/json"
+ __headers = {"accept": "application/json", "content-type": "application/json"}
return await self.perform_request( # type: ignore[return-value]
"POST",
__path,
@@ -3537,10 +4411,28 @@ async def render_search_template(
@_rewrite_parameters(
body_fields=("context", "context_setup", "script"),
)
+ @_stability_warning(Stability.EXPERIMENTAL)
async def scripts_painless_execute(
self,
*,
- context: t.Optional[str] = None,
+ context: t.Optional[
+ t.Union[
+ str,
+ t.Literal[
+ "boolean_field",
+ "composite_field",
+ "date_field",
+ "double_field",
+ "filter",
+ "geo_point_field",
+ "ip_field",
+ "keyword_field",
+ "long_field",
+ "painless_test",
+ "score",
+ ],
+ ]
+ ] = None,
context_setup: t.Optional[t.Mapping[str, t.Any]] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
@@ -3550,13 +4442,24 @@ async def scripts_painless_execute(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Run a script. Runs a script and returns a result.
+ .. raw:: html
+
+ Run a script.
+ Runs a script and returns a result.
+ Use this API to build and test scripts, such as when defining a script for a runtime field.
+ This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.
+ The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.
+ Each context requires a script, but additional parameters depend on the context you're using for that script.
- ``_
- :param context: The context that the script should run in.
- :param context_setup: Additional parameters for the `context`.
- :param script: The Painless script to execute.
+ ``_
+
+ :param context: The context that the script should run in. NOTE: Result ordering
+ in the field contexts is not guaranteed.
+ :param context_setup: Additional parameters for the `context`. NOTE: This parameter
+ is required for all contexts except `painless_test`, which is the default
+ if no value is provided for `context`.
+ :param script: The Painless script to run.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_scripts/painless/_execute"
@@ -3577,11 +4480,7 @@ async def scripts_painless_execute(
__body["context_setup"] = context_setup
if script is not None:
__body["script"] = script
- if not __body:
- __body = None # type: ignore[assignment]
- __headers = {"accept": "application/json"}
- if __body is not None:
- __headers["content-type"] = "application/json"
+ __headers = {"accept": "application/json", "content-type": "application/json"}
return await self.perform_request( # type: ignore[return-value]
"POST",
__path,
@@ -3608,15 +4507,27 @@ async def scroll(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Allows to retrieve a large numbers of results from a single search request.
+ .. raw:: html
+
+ Run a scrolling search.
+ IMPORTANT: The scroll API is no longer recommend for deep pagination. If you need to preserve the index state while paging through more than 10,000 hits, use the search_after parameter with a point in time (PIT).
+ The scroll API gets large sets of results from a single scrolling search request.
+ To get the necessary scroll ID, submit a search API request that includes an argument for the scroll query parameter.
+ The scroll parameter indicates how long Elasticsearch should retain the search context for the request.
+ The search response returns a scroll ID in the _scroll_id response body parameter.
+ You can then use the scroll ID with the scroll API to retrieve the next batch of results for the request.
+ If the Elasticsearch security features are enabled, the access to the results of a specific scroll ID is restricted to the user or API key that submitted the search.
+ You can also use the scroll API to specify a new scroll parameter that extends or shortens the retention period for the search context.
+ IMPORTANT: Results from a scrolling search reflect the state of the index at the time of the initial search request. Subsequent indexing or document changes only affect later search and scroll requests.
+
- ``_
+ ``_
- :param scroll_id: Scroll ID of the search.
+ :param scroll_id: The scroll ID of the search.
:param rest_total_hits_as_int: 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.
- :param scroll: Period to retain the search context for scrolling.
+ :param scroll: The period to retain the search context for scrolling.
"""
if scroll_id is None and body is None:
raise ValueError("Empty value passed for parameter 'scroll_id'")
@@ -3798,15 +4709,29 @@ async def search(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- 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.
-
- ``_
-
- :param index: 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`.
+ .. raw:: html
+
+ Run a search.
+ Get search hits that match the query defined in the request.
+ You can provide search queries using the q query string parameter or the request body.
+ If both are specified, only the query parameter is used.
+ If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.
+ To search a point in time (PIT) for an alias, you must have the read index privilege for the alias's data streams or indices.
+ Search slicing
+ When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the slice and pit properties.
+ By default the splitting is done first on the shards, then locally on each shard.
+ The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.
+ For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.
+ IMPORTANT: The same point-in-time ID should be used for all slices.
+ If different PIT IDs are used, slices can overlap and miss documents.
+ This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.
+
+
+ ``_
+
+ :param index: A comma-separated list of data streams, indices, and aliases to
+ search. It supports wildcards (`*`). To search all data streams and indices,
+ omit this parameter or use `*` or `_all`.
:param aggregations: Defines the aggregations that are run as part of the search
request.
:param aggs: Defines the aggregations that are run as part of the search request.
@@ -3815,45 +4740,46 @@ async def search(
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`.
- :param allow_partial_search_results: If true, returns partial results if there
- are shard request timeouts or shard failures. If false, returns an error
- with no partial results.
- :param analyze_wildcard: If true, wildcard and prefix queries are analyzed. This
- parameter can only be used when the q query string parameter is specified.
- :param analyzer: Analyzer to use for the query string. This parameter can only
- be used when the q query string parameter is specified.
+ :param allow_partial_search_results: If `true` and there are shard request timeouts
+ or shard failures, the request returns partial results. If `false`, it returns
+ an error with no partial results. To override the default behavior, you can
+ set the `search.default_allow_partial_results` cluster setting to `false`.
+ :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed.
+ This parameter can be used only when the `q` query string parameter is specified.
+ :param analyzer: The analyzer to use for the query string. This parameter can
+ be used only when the `q` query string parameter is specified.
:param batched_reduce_size: 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.
- :param ccs_minimize_roundtrips: If true, network round-trips between the coordinating
- node and the remote clusters are minimized when executing cross-cluster search
+ at once on the coordinating node. If the potential number of shards in the
+ request can be large, this value should be used as a protection mechanism
+ to reduce the memory overhead per search request.
+ :param ccs_minimize_roundtrips: If `true`, network round-trips between the coordinating
+ node and the remote clusters are minimized when running cross-cluster search
(CCS) requests.
:param collapse: Collapses search results the values of the specified field.
- :param default_operator: The default operator for query string query: AND or
- OR. This parameter can only be used when the `q` query string parameter is
- specified.
- :param df: 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
+ :param default_operator: The default operator for the query string query: `and`
+ or `or`. This parameter can be used only when the `q` query string parameter
is specified.
- :param docvalue_fields: Array of wildcard (`*`) patterns. The request returns
- doc values for field names matching these patterns in the `hits.fields` property
- of the response.
- :param expand_wildcards: 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`.
- :param explain: If true, returns detailed information about score computation
- as part of a hit.
+ :param df: The field to use as a default when no field prefix is given in the
+ query string. This parameter can be used only when the `q` query string parameter
+ is specified.
+ :param docvalue_fields: An array of wildcard (`*`) field patterns. The request
+ returns doc values for field names matching these patterns in the `hits.fields`
+ property of the response.
+ :param expand_wildcards: The 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. It supports comma-separated
+ values such as `open,hidden`.
+ :param explain: If `true`, the request returns detailed information about score
+ computation as part of a hit.
:param ext: Configuration of search extensions defined by Elasticsearch plugins.
- :param fields: Array of wildcard (`*`) patterns. The request returns values for
- field names matching these patterns in the `hits.fields` property of the
- response.
+ :param fields: An array of wildcard (`*`) field patterns. The request returns
+ values for field names matching these patterns in the `hits.fields` property
+ of the response.
:param force_synthetic_source: 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.
- :param from_: Starting document offset. Needs to be non-negative. By default,
+ :param from_: The starting document offset, which must 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.
:param highlight: Specifies the highlighter to use for retrieving highlighted
@@ -3862,95 +4788,102 @@ async def search(
be ignored when frozen.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
- :param include_named_queries_score: 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.
- :param indices_boost: Boosts the _score of documents from specified indices.
- :param knn: Defines the approximate kNN search to run.
+ :param include_named_queries_score: If `true`, the response includes the score
+ contribution from any named queries. 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.
+ :param indices_boost: Boost the `_score` of documents from specified indices.
+ The boost value is the factor by which scores are multiplied. A boost value
+ greater than `1.0` increases the score. A boost value between `0` and `1.0`
+ decreases the score.
+ :param knn: The approximate kNN search to run.
:param lenient: 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.
- :param max_concurrent_shard_requests: 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.
+ be used only when the `q` query string parameter is specified.
+ :param max_concurrent_shard_requests: The number of concurrent shard requests
+ per node that the search runs 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.
:param min_compatible_shard_node: The minimum version of the node that can handle
the request Any handling node with a lower version will fail the request.
- :param min_score: Minimum `_score` for matching documents. Documents with a lower
- `_score` are not included in the search results.
- :param pit: Limits the search to a point in time (PIT). If you provide a PIT,
+ :param min_score: The minimum `_score` for matching documents. Documents with
+ a lower `_score` are not included in search results and results collected
+ by aggregations.
+ :param pit: Limit the search to a point in time (PIT). If you provide a PIT,
you cannot specify an `` in the request path.
:param post_filter: 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.
- :param pre_filter_shard_size: 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
+ :param pre_filter_shard_size: 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.
- :param preference: Nodes and shards used for the search. By default, Elasticsearch
+ :param preference: The 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:,` 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:,` to if
+ 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:,` 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:,` to if
possible, run the search on the specified nodes IDs, or if not, select shards
- using the default method; `_shards:,` to run the search only
- on the specified shards; `` (any string that does not start
+ using the default method; * `_shards:,` to run the search only
+ on the specified shards; * `` (any string that does not start
with `_`) to route searches with the same `` to the same shards
in the same order.
:param profile: 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.
- :param q: 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.
- :param query: Defines the search definition using the Query DSL.
- :param rank: Defines the Reciprocal Rank Fusion (RRF) to use.
+ :param q: A query in the Lucene query string syntax. Query parameter searches
+ do not support the full Elasticsearch Query DSL but are handy for testing.
+ IMPORTANT: This parameter overrides the query parameter in the request body.
+ If both parameters are specified, documents matching the query request body
+ parameter are not returned.
+ :param query: The search definition using the Query DSL.
+ :param rank: The Reciprocal Rank Fusion (RRF) to use.
:param request_cache: If `true`, the caching of search results is enabled for
- requests where `size` is `0`. Defaults to index level settings.
+ requests where `size` is `0`. It defaults to index level settings.
:param rescore: Can be used to improve precision by reordering just the top (for
example 100 - 500) documents returned by the `query` and `post_filter` phases.
:param rest_total_hits_as_int: Indicates whether `hits.total` should be rendered
as an integer or an object in the rest search response.
:param retriever: 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.
- :param routing: Custom value used to route operations to a specific shard.
- :param runtime_mappings: Defines one or more runtime fields in the search request.
- These fields take precedence over mapped fields with the same name.
+ also return top documents such as `query` and `knn`.
+ :param routing: A custom value that is used to route operations to a specific
+ shard.
+ :param runtime_mappings: One or more runtime fields in the search request. These
+ fields take precedence over mapped fields with the same name.
:param script_fields: Retrieve a script evaluation (based on different fields)
for each hit.
- :param scroll: 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.
+ :param scroll: The period to retain the search context for scrolling. By default,
+ this value cannot exceed `1d` (24 hours). You can change this limit by using
+ the `search.max_keep_alive` cluster-level setting.
:param search_after: Used to retrieve the next page of hits using a set of sort
values from the previous page.
- :param search_type: How distributed term frequencies are calculated for relevance
- scoring.
- :param seq_no_primary_term: If `true`, returns sequence number and primary term
- of the last modification of each hit.
- :param size: 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.
- :param slice: Can be used to split a scrolled search into multiple slices that
- can be consumed independently.
+ :param search_type: Indicates how distributed term frequencies are calculated
+ for relevance scoring.
+ :param seq_no_primary_term: If `true`, the request returns sequence number and
+ primary term of the last modification of each hit.
+ :param size: The number of hits to return, which must not be 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` property.
+ :param slice: Split a scrolled search into multiple slices that can be consumed
+ independently.
:param sort: A comma-separated list of : pairs.
- :param source: Indicates which source fields are returned for matching documents.
- These fields are returned in the hits._source property of the search response.
+ :param source: The source fields that are returned for matching documents. These
+ fields are returned in the `hits._source` property of the search response.
+ If the `stored_fields` property is specified, the `_source` property defaults
+ to `false`. Otherwise, it defaults to `true`.
:param source_excludes: 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`
@@ -3960,45 +4893,46 @@ async def search(
returned. You can exclude fields from this subset using the `_source_excludes`
query parameter. If the `_source` parameter is `false`, this parameter is
ignored.
- :param stats: Stats groups to associate with the search. Each group maintains
+ :param stats: The 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.
- :param stored_fields: 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.
+ :param stored_fields: A comma-separated 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` property defaults to
+ `false`. You can pass `_source: true` to return both source fields and stored
+ fields in the search response.
:param suggest: Defines a suggester that provides similar looking terms based
on a provided text.
- :param suggest_field: Specifies which field to use for suggestions.
- :param suggest_mode: Specifies the suggest mode. This parameter can only be used
- when the `suggest_field` and `suggest_text` query string parameters are specified.
- :param suggest_size: Number of suggestions to return. This parameter can only
- be used when the `suggest_field` and `suggest_text` query string parameters
+ :param suggest_field: The field to use for suggestions.
+ :param suggest_mode: The suggest mode. This parameter can be used only when the
+ `suggest_field` and `suggest_text` query string parameters are specified.
+ :param suggest_size: The number of suggestions to return. This parameter can
+ be used only when the `suggest_field` and `suggest_text` query string parameters
are specified.
:param suggest_text: The source text for which the suggestions should be returned.
- This parameter can only be used when the `suggest_field` and `suggest_text`
+ This parameter can be used only when the `suggest_field` and `suggest_text`
query string parameters are specified.
- :param terminate_after: Maximum number of documents to collect for each shard.
+ :param terminate_after: The 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.
- :param timeout: 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.
- :param track_scores: If true, calculate and return document scores, even if the
- scores are not used for sorting.
+ Elasticsearch collects documents before sorting. IMPORTANT: Use with caution.
+ Elasticsearch applies this property to each shard handling the request. When
+ possible, let Elasticsearch perform early termination automatically. Avoid
+ specifying this property for requests that target data streams with backing
+ indices across multiple data tiers. If set to `0` (default), the query does
+ not terminate early.
+ :param timeout: 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.
+ :param track_scores: If `true`, calculate and return document scores, even if
+ the scores are not used for sorting.
:param track_total_hits: 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.
:param typed_keys: If `true`, aggregation and suggester names are be prefixed
by their respective types in the response.
- :param version: If true, returns document version as part of a hit.
+ :param version: If `true`, the request returns the document version as part of
+ a hit.
"""
__path_parts: t.Dict[str, str]
if index not in SKIP_IN_PATH:
@@ -4230,52 +5164,376 @@ async def search_mvt(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> BinaryApiResponse:
"""
- Search a vector tile. Searches a vector tile for geospatial values.
-
- ``_
+ .. raw:: html
+
+ Search a vector tile.
+ Search a vector tile for geospatial values.
+ Before using this API, you should be familiar with the Mapbox vector tile specification.
+ The API returns results as a binary mapbox vector tile.
+ Internally, Elasticsearch translates a vector tile search API request into a search containing:
+
+ - A
geo_bounding_box query on the <field>. The query uses the <zoom>/<x>/<y> tile as a bounding box.
+ - A
geotile_grid or geohex_grid aggregation on the <field>. The grid_agg parameter determines the aggregation type. The aggregation uses the <zoom>/<x>/<y> tile as a bounding box.
+ - Optionally, a
geo_bounds aggregation on the <field>. The search only includes this aggregation if the exact_bounds parameter is true.
+ - If the optional parameter
with_labels is true, the internal search will include a dynamic runtime field that calls the getLabelPosition function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.
+
+ For example, Elasticsearch may translate a vector tile search API request with a grid_agg argument of geotile and an exact_bounds argument of true into the following search
+ GET my-index/_search
+ {
+ "size": 10000,
+ "query": {
+ "geo_bounding_box": {
+ "my-geo-field": {
+ "top_left": {
+ "lat": -40.979898069620134,
+ "lon": -45
+ },
+ "bottom_right": {
+ "lat": -66.51326044311186,
+ "lon": 0
+ }
+ }
+ }
+ },
+ "aggregations": {
+ "grid": {
+ "geotile_grid": {
+ "field": "my-geo-field",
+ "precision": 11,
+ "size": 65536,
+ "bounds": {
+ "top_left": {
+ "lat": -40.979898069620134,
+ "lon": -45
+ },
+ "bottom_right": {
+ "lat": -66.51326044311186,
+ "lon": 0
+ }
+ }
+ }
+ },
+ "bounds": {
+ "geo_bounds": {
+ "field": "my-geo-field",
+ "wrap_longitude": false
+ }
+ }
+ }
+ }
+
+ The API returns results as a binary Mapbox vector tile.
+ Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:
+
+ - A
hits layer containing a feature for each <field> value matching the geo_bounding_box query.
+ - An
aggs layer containing a feature for each cell of the geotile_grid or geohex_grid. The layer only contains features for cells with matching data.
+ - A meta layer containing:
+
+ - A feature containing a bounding box. By default, this is the bounding box of the tile.
+ - Value ranges for any sub-aggregations on the
geotile_grid or geohex_grid.
+ - Metadata for the search.
+
+
+
+ The API only returns features that can display at its zoom level.
+ For example, if a polygon feature has no area at its zoom level, the API omits it.
+ The API returns errors as UTF-8 encoded JSON.
+ IMPORTANT: You can specify several options for this API as either a query parameter or request body parameter.
+ If you specify both parameters, the query parameter takes precedence.
+ Grid precision for geotile
+ For a grid_agg of geotile, you can use cells in the aggs layer as tiles for lower zoom levels.
+ grid_precision represents the additional zoom levels available through these cells. The final precision is computed by as follows: <zoom> + grid_precision.
+ For example, if <zoom> is 7 and grid_precision is 8, then the geotile_grid aggregation will use a precision of 15.
+ The maximum final precision is 29.
+ The grid_precision also determines the number of cells for the grid as follows: (2^grid_precision) x (2^grid_precision).
+ For example, a value of 8 divides the tile into a grid of 256 x 256 cells.
+ The aggs layer only contains features for cells with matching data.
+ Grid precision for geohex
+ For a grid_agg of geohex, Elasticsearch uses <zoom> and grid_precision to calculate a final precision as follows: <zoom> + grid_precision.
+ This precision determines the H3 resolution of the hexagonal cells produced by the geohex aggregation.
+ The following table maps the H3 resolution for each precision.
+ For example, if <zoom> is 3 and grid_precision is 3, the precision is 6.
+ At a precision of 6, hexagonal cells have an H3 resolution of 2.
+ If <zoom> is 3 and grid_precision is 4, the precision is 7.
+ At a precision of 7, hexagonal cells have an H3 resolution of 3.
+
+
+
+ | Precision |
+ Unique tile bins |
+ H3 resolution |
+ Unique hex bins |
+ Ratio |
+
+
+
+
+ | 1 |
+ 4 |
+ 0 |
+ 122 |
+ 30.5 |
+
+
+ | 2 |
+ 16 |
+ 0 |
+ 122 |
+ 7.625 |
+
+
+ | 3 |
+ 64 |
+ 1 |
+ 842 |
+ 13.15625 |
+
+
+ | 4 |
+ 256 |
+ 1 |
+ 842 |
+ 3.2890625 |
+
+
+ | 5 |
+ 1024 |
+ 2 |
+ 5882 |
+ 5.744140625 |
+
+
+ | 6 |
+ 4096 |
+ 2 |
+ 5882 |
+ 1.436035156 |
+
+
+ | 7 |
+ 16384 |
+ 3 |
+ 41162 |
+ 2.512329102 |
+
+
+ | 8 |
+ 65536 |
+ 3 |
+ 41162 |
+ 0.6280822754 |
+
+
+ | 9 |
+ 262144 |
+ 4 |
+ 288122 |
+ 1.099098206 |
+
+
+ | 10 |
+ 1048576 |
+ 4 |
+ 288122 |
+ 0.2747745514 |
+
+
+ | 11 |
+ 4194304 |
+ 5 |
+ 2016842 |
+ 0.4808526039 |
+
+
+ | 12 |
+ 16777216 |
+ 6 |
+ 14117882 |
+ 0.8414913416 |
+
+
+ | 13 |
+ 67108864 |
+ 6 |
+ 14117882 |
+ 0.2103728354 |
+
+
+ | 14 |
+ 268435456 |
+ 7 |
+ 98825162 |
+ 0.3681524172 |
+
+
+ | 15 |
+ 1073741824 |
+ 8 |
+ 691776122 |
+ 0.644266719 |
+
+
+ | 16 |
+ 4294967296 |
+ 8 |
+ 691776122 |
+ 0.1610666797 |
+
+
+ | 17 |
+ 17179869184 |
+ 9 |
+ 4842432842 |
+ 0.2818666889 |
+
+
+ | 18 |
+ 68719476736 |
+ 10 |
+ 33897029882 |
+ 0.4932667053 |
+
+
+ | 19 |
+ 274877906944 |
+ 11 |
+ 237279209162 |
+ 0.8632167343 |
+
+
+ | 20 |
+ 1099511627776 |
+ 11 |
+ 237279209162 |
+ 0.2158041836 |
+
+
+ | 21 |
+ 4398046511104 |
+ 12 |
+ 1660954464122 |
+ 0.3776573213 |
+
+
+ | 22 |
+ 17592186044416 |
+ 13 |
+ 11626681248842 |
+ 0.6609003122 |
+
+
+ | 23 |
+ 70368744177664 |
+ 13 |
+ 11626681248842 |
+ 0.165225078 |
+
+
+ | 24 |
+ 281474976710656 |
+ 14 |
+ 81386768741882 |
+ 0.2891438866 |
+
+
+ | 25 |
+ 1125899906842620 |
+ 15 |
+ 569707381193162 |
+ 0.5060018015 |
+
+
+ | 26 |
+ 4503599627370500 |
+ 15 |
+ 569707381193162 |
+ 0.1265004504 |
+
+
+ | 27 |
+ 18014398509482000 |
+ 15 |
+ 569707381193162 |
+ 0.03162511259 |
+
+
+ | 28 |
+ 72057594037927900 |
+ 15 |
+ 569707381193162 |
+ 0.007906278149 |
+
+
+ | 29 |
+ 288230376151712000 |
+ 15 |
+ 569707381193162 |
+ 0.001976569537 |
+
+
+
+ Hexagonal cells don't align perfectly on a vector tile.
+ Some cells may intersect more than one vector tile.
+ To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level.
+ Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density.
+
+
+ ``_
:param index: Comma-separated list of data streams, indices, or aliases to search
:param field: Field containing geospatial data to return
:param zoom: Zoom level for the vector tile to search
:param x: X coordinate for the vector tile to search
:param y: Y coordinate for the vector tile to search
- :param aggs: Sub-aggregations for the geotile_grid. Supports the following aggregation
- types: - avg - cardinality - max - min - sum
- :param buffer: 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.
- :param exact_bounds: 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 values that intersect
- the // tile with wrap_longitude set to false. The resulting bounding
- box may be larger than the vector tile.
- :param extent: Size, in pixels, of a side of the tile. Vector tiles are square
+ :param aggs: Sub-aggregations for the geotile_grid. It supports the following
+ aggregation types: - `avg` - `boxplot` - `cardinality` - `extended stats`
+ - `max` - `median absolute deviation` - `min` - `percentile` - `percentile-rank`
+ - `stats` - `sum` - `value count` The aggregation names can't start with
+ `_mvt_`. The `_mvt_` prefix is reserved for internal aggregations.
+ :param buffer: The 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.
+ :param exact_bounds: 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 values that
+ intersect the `//` tile with `wrap_longitude` set to `false`.
+ The resulting bounding box may be larger than the vector tile.
+ :param extent: The size, in pixels, of a side of the tile. Vector tiles are square
with equal sides.
- :param fields: 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.
- :param grid_agg: Aggregation used to create a grid for the `field`.
+ :param fields: The fields to return in the `hits` layer. It supports wildcards
+ (`*`). This parameter does not support fields with array values. Fields with
+ array values may return inconsistent results.
+ :param grid_agg: The aggregation used to create a grid for the `field`.
:param grid_precision: Additional zoom levels available through the aggs layer.
- For example, if 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.
+ For example, if `` 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.
:param grid_type: 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
+ 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.
- :param query: Query DSL used to filter documents for the search.
+ :param query: The query DSL used to filter documents for the search.
:param runtime_mappings: Defines one or more runtime fields in the search request.
These fields take precedence over mapped fields with the same name.
- :param size: Maximum number of features to return in the hits layer. Accepts
- 0-10000. If 0, results don’t include the hits layer.
- :param sort: 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
+ :param size: The maximum number of features to return in the hits layer. Accepts
+ 0-10000. If 0, results don't include the hits layer.
+ :param sort: Sort the 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.
- :param track_total_hits: Number of hits matching the query to count accurately.
+ :param track_total_hits: The 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.
:param with_labels: If `true`, the hits and aggs layers will contain additional
point features representing suggested label positions for the original features.
+ * `Point` and `MultiPoint` features will have one of the points selected.
+ * `Polygon` and `MultiPolygon` features will have a single point generated,
+ either the centroid, if it is within the polygon, or another point within
+ the polygon selected from the sorted triangle-tree. * `LineString` features
+ will likewise provide a roughly central point selected from the triangle-tree.
+ * The aggregation results will provide one central point for each aggregation
+ bucket. All attributes from the original features will also be copied to
+ the new label features. In addition, the new features will be distinguishable
+ using the tag `_mvt_label_position`.
"""
if index in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'index'")
@@ -4379,18 +5637,26 @@ async def search_shards(
human: t.Optional[bool] = None,
ignore_unavailable: t.Optional[bool] = None,
local: t.Optional[bool] = None,
+ master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
preference: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
routing: t.Optional[str] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Returns information about the indices and shards that a search request would
- be executed against.
+ .. raw:: html
+
+ Get the search shards.
+ Get the indices and shards that a search request would be run against.
+ This information can be useful for working out issues or planning optimizations with routing and shard preferences.
+ When filtered aliases are used, the filter is returned as part of the indices section.
+ If the Elasticsearch security features are enabled, you must have the view_index_metadata or manage index privilege for the target data stream, index, or alias.
- ``_
- :param index: Returns the indices and shards that a search request would be executed
- against.
+ ``_
+
+ :param index: A comma-separated list of data streams, indices, and aliases to
+ search. It supports wildcards (`*`). To search all data streams and indices,
+ omit this parameter or use `*` or `_all`.
:param allow_no_indices: 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
@@ -4399,14 +5665,18 @@ async def search_shards(
:param expand_wildcards: 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`.
+ as `open,hidden`.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
:param local: If `true`, the request retrieves information from the local node
only.
- :param preference: Specifies the node or shard the operation should be performed
- on. Random by default.
- :param routing: Custom value used to route operations to a specific shard.
+ :param master_timeout: The period to wait for a connection to the master node.
+ If the master node is not available before the timeout expires, the request
+ fails and returns an error. IT can also be set to `-1` to indicate that the
+ request should never timeout.
+ :param preference: The node or shard the operation should be performed on. It
+ is random by default.
+ :param routing: A custom value used to route operations to a specific shard.
"""
__path_parts: t.Dict[str, str]
if index not in SKIP_IN_PATH:
@@ -4430,6 +5700,8 @@ async def search_shards(
__query["ignore_unavailable"] = ignore_unavailable
if local is not None:
__query["local"] = local
+ if master_timeout is not None:
+ __query["master_timeout"] = master_timeout
if preference is not None:
__query["preference"] = preference
if pretty is not None:
@@ -4486,12 +5758,15 @@ async def search_template(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Runs a search with a search template.
+ .. raw:: html
- ``_
+ Run a search with a search template.
- :param index: Comma-separated list of data streams, indices, and aliases to search.
- Supports wildcards (*).
+
+ ``_
+
+ :param index: A comma-separated list of data streams, indices, and aliases to
+ search. It supports wildcards (`*`).
:param allow_no_indices: 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
@@ -4499,32 +5774,33 @@ async def search_template(
with `foo` but no index starts with `bar`.
:param ccs_minimize_roundtrips: If `true`, network round-trips are minimized
for cross-cluster search requests.
- :param expand_wildcards: 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`.
+ :param expand_wildcards: The 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`.
:param explain: If `true`, returns detailed information about score calculation
- as part of each hit.
- :param id: ID of the search template to use. If no source is specified, this
- parameter is required.
+ as part of each hit. If you specify both this and the `explain` query parameter,
+ the API uses only the query parameter.
+ :param id: The ID of the search template to use. If no `source` is specified,
+ this parameter is required.
:param ignore_throttled: If `true`, specified concrete, expanded, or aliased
indices are not included in the response when throttled.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
:param params: Key-value pairs used to replace Mustache variables in the template.
The key is the variable name. The value is the variable value.
- :param preference: Specifies the node or shard the operation should be performed
- on. Random by default.
+ :param preference: The node or shard the operation should be performed on. It
+ is random by default.
:param profile: If `true`, the query execution is profiled.
- :param rest_total_hits_as_int: If true, hits.total are rendered as an integer
- in the response.
- :param routing: Custom value used to route operations to a specific shard.
+ :param rest_total_hits_as_int: If `true`, `hits.total` is rendered as an integer
+ in the response. If `false`, it is rendered as an object.
+ :param routing: A custom value used to route operations to a specific shard.
:param scroll: Specifies how long a consistent view of the index should be maintained
for scrolled search.
:param search_type: The type of the search operation.
:param source: 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.
+ search API's request body. It also supports Mustache variables. If no `id`
+ is specified, this parameter is required.
:param typed_keys: If `true`, the response prefixes aggregation and suggester
names with their respective types.
"""
@@ -4618,28 +5894,39 @@ async def terms_enum(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- 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.
+ .. raw:: html
- ``_
+ Get terms in an index.
+ Discover terms that match a partial string in an index.
+ This API is designed for low-latency look-ups used in auto-complete scenarios.
+
+ info
+ The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.
+
- :param index: Comma-separated list of data streams, indices, and index aliases
- to search. Wildcard (*) expressions are supported.
+
+ ``_
+
+ :param index: A comma-separated list of data streams, indices, and index aliases
+ to search. Wildcard (`*`) expressions are supported. To search all data streams
+ or indices, omit this parameter or use `*` or `_all`.
:param field: The string to match at the start of indexed terms. If not provided,
all terms in the field are considered.
- :param case_insensitive: When true the provided search string is matched against
+ :param case_insensitive: When `true`, the provided search string is matched against
index terms without case sensitivity.
- :param index_filter: Allows to filter an index shard if the provided query rewrites
- to match_none.
- :param search_after:
- :param size: How many matching terms to return.
- :param string: 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.
- :param timeout: 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.
+ :param index_filter: Filter an index shard if the provided query rewrites to
+ `match_none`.
+ :param search_after: The string after which terms in the index should be returned.
+ It allows for a form of pagination if the last result from one request is
+ passed as the `search_after` parameter for a subsequent request.
+ :param size: The number of matching terms to return.
+ :param string: The string to match at the start of indexed terms. If it is not
+ provided, all terms in the field are considered. > info > The prefix string
+ cannot be larger than the largest possible keyword value, which is Lucene's
+ term byte-length limit of 32766.
+ :param timeout: The maximum length of time to spend collecting results. If the
+ timeout is exceeded the `complete` flag set to `false` in the response and
+ the results may be partial or empty.
"""
if index in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'index'")
@@ -4672,11 +5959,7 @@ async def terms_enum(
__body["string"] = string
if timeout is not None:
__body["timeout"] = timeout
- if not __body:
- __body = None # type: ignore[assignment]
- __headers = {"accept": "application/json"}
- if __body is not None:
- __headers["content-type"] = "application/json"
+ __headers = {"accept": "application/json", "content-type": "application/json"}
return await self.perform_request( # type: ignore[return-value]
"POST",
__path,
@@ -4688,7 +5971,20 @@ async def terms_enum(
)
@_rewrite_parameters(
- body_fields=("doc", "filter", "per_field_analyzer"),
+ body_fields=(
+ "doc",
+ "field_statistics",
+ "fields",
+ "filter",
+ "offsets",
+ "payloads",
+ "per_field_analyzer",
+ "positions",
+ "routing",
+ "term_statistics",
+ "version",
+ "version_type",
+ ),
)
async def termvectors(
self,
@@ -4698,7 +5994,7 @@ async def termvectors(
doc: t.Optional[t.Mapping[str, t.Any]] = None,
error_trace: t.Optional[bool] = None,
field_statistics: t.Optional[bool] = None,
- fields: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ fields: t.Optional[t.Sequence[str]] = None,
filter: t.Optional[t.Mapping[str, t.Any]] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
@@ -4713,38 +6009,82 @@ async def termvectors(
term_statistics: t.Optional[bool] = None,
version: t.Optional[int] = None,
version_type: t.Optional[
- t.Union[str, t.Literal["external", "external_gte", "force", "internal"]]
+ t.Union[str, t.Literal["external", "external_gte", "internal"]]
] = None,
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Get term vector information. Returns information and statistics about terms in
- the fields of a particular document.
-
- ``_
-
- :param index: Name of the index that contains the document.
- :param id: Unique identifier of the document.
+ .. raw:: html
+
+ Get term vector information.
+ Get information and statistics about terms in the fields of a particular document.
+ You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request.
+ You can specify the fields you are interested in through the fields parameter or by adding the fields to the request body.
+ For example:
+ GET /my-index-000001/_termvectors/1?fields=message
+
+ Fields can be specified using wildcards, similar to the multi match query.
+ Term vectors are real-time by default, not near real-time.
+ This can be changed by setting realtime parameter to false.
+ You can request three types of values: term information, term statistics, and field statistics.
+ By default, all term information and field statistics are returned for all fields but term statistics are excluded.
+ Term information
+
+ - term frequency in the field (always returned)
+ - term positions (
positions: true)
+ - start and end offsets (
offsets: true)
+ - term payloads (
payloads: true), as base64 encoded bytes
+
+ If the requested information wasn't stored in the index, it will be computed on the fly if possible.
+ Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.
+
+ warn
+ Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.
+
+ Behaviour
+ The term and field statistics are not accurate.
+ Deleted documents are not taken into account.
+ The information is only retrieved for the shard the requested document resides in.
+ The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context.
+ By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected.
+ Use routing only to hit a particular shard.
+
+
+ ``_
+
+ :param index: The name of the index that contains the document.
+ :param id: A unique identifier for the document.
:param doc: An artificial document (a document not present in the index) for
which you want to retrieve term vectors.
- :param field_statistics: If `true`, the response includes the document count,
- sum of document frequencies, and sum of total term frequencies.
- :param fields: 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.
- :param filter: Filter terms based on their tf-idf scores.
+ :param field_statistics: If `true`, the response includes: * The document count
+ (how many documents contain this field). * The sum of document frequencies
+ (the sum of document frequencies for all terms in this field). * The sum
+ of total term frequencies (the sum of total term frequencies of each term
+ in this field).
+ :param fields: A list of fields to include in the statistics. It is used as the
+ default list unless a specific field list is provided in the `completion_fields`
+ or `fielddata_fields` parameters.
+ :param filter: Filter terms based on their tf-idf scores. This could be useful
+ in order find out a good characteristic vector of a document. This feature
+ works in a similar manner to the second phase of the More Like This Query.
:param offsets: If `true`, the response includes term offsets.
:param payloads: If `true`, the response includes term payloads.
- :param per_field_analyzer: Overrides the default per-field analyzer.
+ :param per_field_analyzer: Override the default per-field analyzer. This is useful
+ in order to generate term vectors in any fashion, especially when using artificial
+ documents. When providing an analyzer for a field that already stores term
+ vectors, the term vectors will be regenerated.
:param positions: If `true`, the response includes term positions.
- :param preference: Specifies the node or shard the operation should be performed
- on. Random by default.
+ :param preference: The node or shard the operation should be performed on. It
+ is random by default.
:param realtime: If true, the request is real-time as opposed to near-real-time.
- :param routing: Custom value used to route operations to a specific shard.
- :param term_statistics: If `true`, the response includes term frequency and document
- frequency.
+ :param routing: A custom value that is used to route operations to a specific
+ shard.
+ :param term_statistics: If `true`, the response includes: * The total term frequency
+ (how often a term occurs in all documents). * The document frequency (the
+ number of documents containing the current term). By default these values
+ are not returned since term statistics can have a serious performance impact.
:param version: If `true`, returns the document version as part of a hit.
- :param version_type: Specific version type.
+ :param version_type: The version type.
"""
if index in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'index'")
@@ -4761,41 +6101,41 @@ async def termvectors(
__body: t.Dict[str, t.Any] = body if body is not None else {}
if error_trace is not None:
__query["error_trace"] = error_trace
- if field_statistics is not None:
- __query["field_statistics"] = field_statistics
- if fields is not None:
- __query["fields"] = fields
if filter_path is not None:
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
- if offsets is not None:
- __query["offsets"] = offsets
- if payloads is not None:
- __query["payloads"] = payloads
- if positions is not None:
- __query["positions"] = positions
if preference is not None:
__query["preference"] = preference
if pretty is not None:
__query["pretty"] = pretty
if realtime is not None:
__query["realtime"] = realtime
- if routing is not None:
- __query["routing"] = routing
- if term_statistics is not None:
- __query["term_statistics"] = term_statistics
- if version is not None:
- __query["version"] = version
- if version_type is not None:
- __query["version_type"] = version_type
if not __body:
if doc is not None:
__body["doc"] = doc
+ if field_statistics is not None:
+ __body["field_statistics"] = field_statistics
+ if fields is not None:
+ __body["fields"] = fields
if filter is not None:
__body["filter"] = filter
+ if offsets is not None:
+ __body["offsets"] = offsets
+ if payloads is not None:
+ __body["payloads"] = payloads
if per_field_analyzer is not None:
__body["per_field_analyzer"] = per_field_analyzer
+ if positions is not None:
+ __body["positions"] = positions
+ if routing is not None:
+ __body["routing"] = routing
+ if term_statistics is not None:
+ __body["term_statistics"] = term_statistics
+ if version is not None:
+ __body["version"] = version
+ if version_type is not None:
+ __body["version_type"] = version_type
if not __body:
__body = None # type: ignore[assignment]
__headers = {"accept": "application/json"}
@@ -4840,6 +6180,7 @@ async def update(
human: t.Optional[bool] = None,
if_primary_term: t.Optional[int] = None,
if_seq_no: t.Optional[int] = None,
+ include_source_on_error: t.Optional[bool] = None,
lang: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
refresh: t.Optional[
@@ -4861,46 +6202,67 @@ async def update(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Update a document. Updates a document by running a script or passing a partial
- document.
-
- ``_
-
- :param index: The name of the index
- :param id: Document ID
- :param detect_noop: Set to false to disable setting 'result' in the response
- to 'noop' if no change to the document occurred.
- :param doc: A partial update to an existing document.
- :param doc_as_upsert: Set to true to use the contents of 'doc' as the value of
- 'upsert'
+ .. raw:: html
+
+ Update a document.
+ Update a document by running a script or passing a partial document.
+ If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.
+ The script can update, delete, or skip modifying the document.
+ The API also supports passing a partial document, which is merged into the existing document.
+ To fully replace an existing document, use the index API.
+ This operation:
+
+ - Gets the document (collocated with the shard) from the index.
+ - Runs the specified script.
+ - Indexes the result.
+
+ The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.
+ The _source field must be enabled to use this API.
+ In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).
+
+
+ ``_
+
+ :param index: The name of the target index. By default, the index is created
+ automatically if it doesn't exist.
+ :param id: A unique identifier for the document to be updated.
+ :param detect_noop: If `true`, the `result` in the response is set to `noop`
+ (no operation) when there are no changes to the document.
+ :param doc: A partial update to an existing document. If both `doc` and `script`
+ are specified, `doc` is ignored.
+ :param doc_as_upsert: If `true`, use the contents of 'doc' as the value of 'upsert'.
+ NOTE: Using ingest pipelines with `doc_as_upsert` is not supported.
:param if_primary_term: Only perform the operation if the document has this primary
term.
:param if_seq_no: Only perform the operation if the document has this sequence
number.
+ :param include_source_on_error: True or false if to include the document source
+ in the error message in case of parsing errors.
:param lang: The script language.
:param refresh: 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.
- :param require_alias: If true, the destination must be an index alias.
- :param retry_on_conflict: Specify how many times should the operation be retried
+ this operation visible to search. If 'wait_for', it waits for a refresh to
+ make this operation visible to search. If 'false', it does nothing with refreshes.
+ :param require_alias: If `true`, the destination must be an index alias.
+ :param retry_on_conflict: The number of times the operation should be retried
when a conflict occurs.
- :param routing: Custom value used to route operations to a specific shard.
- :param script: Script to execute to update the document.
- :param scripted_upsert: Set to true to execute the script whether or not the
- document exists.
- :param source: Set to false to disable source retrieval. You can also specify
- a comma-separated list of the fields you want to retrieve.
- :param source_excludes: Specify the source fields you want to exclude.
- :param source_includes: Specify the source fields you want to retrieve.
- :param timeout: 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.
+ :param routing: A custom value used to route operations to a specific shard.
+ :param script: The script to run to update the document.
+ :param scripted_upsert: If `true`, run the script whether or not the document
+ exists.
+ :param source: If `false`, turn off source retrieval. You can also specify a
+ comma-separated list of the fields you want to retrieve.
+ :param source_excludes: The source fields you want to exclude.
+ :param source_includes: The source fields you want to retrieve.
+ :param timeout: The period to wait for the following operations: dynamic mapping
+ updates and waiting for active shards. Elasticsearch waits for at least the
+ timeout period before failing. The actual wait time could be longer, particularly
+ when multiple waits occur.
:param upsert: 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.
- :param wait_for_active_shards: 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.
+ are inserted as a new document. If the document exists, the 'script' is run.
+ :param wait_for_active_shards: The number of copies of each shard 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).
+ The default value of `1` means it waits for each primary shard to be active.
"""
if index in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'index'")
@@ -4920,6 +6282,8 @@ async def update(
__query["if_primary_term"] = if_primary_term
if if_seq_no is not None:
__query["if_seq_no"] = if_seq_no
+ if include_source_on_error is not None:
+ __query["include_source_on_error"] = include_source_on_error
if lang is not None:
__query["lang"] = lang
if pretty is not None:
@@ -5026,82 +6390,165 @@ async def update_by_query(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Update documents. Updates documents that match the specified query. If no query
- is specified, performs an update on every document in the data stream or index
- without modifying the source, which is useful for picking up mapping changes.
-
- ``_
-
- :param index: 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`.
+ .. raw:: html
+
+ Update documents.
+ Updates documents that match the specified query.
+ If no query is specified, performs an update on every document in the data stream or index without modifying the source, which is useful for picking up mapping changes.
+ If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias:
+
+ readindex or write
+ You can specify the query criteria in the request URI or the request body using the same syntax as the search API.
+ When you submit an update by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and updates matching documents using internal versioning.
+ When the versions match, the document is updated and the version number is incremented.
+ If a document changes between the time that the snapshot is taken and the update operation is processed, it results in a version conflict and the operation fails.
+ You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed.
+ Note that if you opt to count version conflicts, the operation could attempt to update more documents from the source than max_docs until it has successfully updated max_docs documents or it has gone through every document in the source query.
+ NOTE: Documents with a version equal to 0 cannot be updated using update by query because internal versioning does not support 0 as a valid version number.
+ While processing an update by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents.
+ A bulk update request is performed for each batch of matching documents.
+ Any query or update failures cause the update by query request to fail and the failures are shown in the response.
+ Any update requests that completed successfully still stick, they are not rolled back.
+ Throttling update requests
+ To control the rate at which update by query issues batches of update operations, you can set requests_per_second to any positive decimal number.
+ This pads each batch with a wait time to throttle the rate.
+ Set requests_per_second to -1 to turn off throttling.
+ Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account.
+ The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing.
+ By default the batch size is 1000, so if requests_per_second is set to 500:
+ target_time = 1000 / 500 per second = 2 seconds
+ wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
+
+ Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set.
+ This is "bursty" instead of "smooth".
+ Slicing
+ Update by query supports sliced scroll to parallelize the update process.
+ This can improve efficiency and provide a convenient way to break the request down into smaller parts.
+ Setting slices to auto chooses a reasonable number for most data streams and indices.
+ This setting will use one slice per shard, up to a certain limit.
+ If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards.
+ Adding slices to _update_by_query just automates the manual process of creating sub-requests, which means it has some quirks:
+
+ - You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices.
+ - Fetching the status of the task for the request with
slices only contains the status of completed slices.
+ - These sub-requests are individually addressable for things like cancellation and rethrottling.
+ - Rethrottling the request with
slices will rethrottle the unfinished sub-request proportionally.
+ - Canceling the request with slices will cancel each sub-request.
+ - Due to the nature of slices each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
+ - Parameters like
requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the point above about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being updated.
+ - Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time.
+
+ If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:
+
+ - Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
+ - Update performance scales linearly across available resources with the number of slices.
+
+ Whether query or update performance dominates the runtime depends on the documents being reindexed and cluster resources.
+ Update the document source
+ Update by query supports scripts to update the document source.
+ As with the update API, you can set ctx.op to change the operation that is performed.
+ Set ctx.op = "noop" if your script decides that it doesn't have to make any changes.
+ The update by query operation skips updating the document and increments the noop counter.
+ Set ctx.op = "delete" if your script decides that the document should be deleted.
+ The update by query operation deletes the document and increments the deleted counter.
+ Update by query supports only index, noop, and delete.
+ Setting ctx.op to anything else is an error.
+ Setting any other field in ctx is an error.
+ This API enables you to only modify the source of matching documents; you cannot move them.
+
+
+ ``_
+
+ :param index: A comma-separated list of data streams, indices, and aliases to
+ search. It supports wildcards (`*`). To search all data streams or indices,
+ omit this parameter or use `*` or `_all`.
:param allow_no_indices: 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`.
:param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed.
- :param analyzer: Analyzer to use for the query string.
- :param conflicts: What to do if update by query hits version conflicts: `abort`
- or `proceed`.
- :param default_operator: The default operator for query string query: `AND` or
- `OR`.
- :param df: Field to use as default where no field prefix is given in the query
- string.
- :param expand_wildcards: 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`.
- :param from_: Starting offset (default: 0)
+ This parameter can be used only when the `q` query string parameter is specified.
+ :param analyzer: The analyzer to use for the query string. This parameter can
+ be used only when the `q` query string parameter is specified.
+ :param conflicts: The preferred behavior when update by query hits version conflicts:
+ `abort` or `proceed`.
+ :param default_operator: The default operator for query string query: `and` or
+ `or`. This parameter can be used only when the `q` query string parameter
+ is specified.
+ :param df: The field to use as default where no field prefix is given in the
+ query string. This parameter can be used only when the `q` query string parameter
+ is specified.
+ :param expand_wildcards: The 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. It supports comma-separated
+ values, such as `open,hidden`.
+ :param from_: Skips the specified number of documents.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
:param lenient: If `true`, format-based query failures (such as providing text
- to a numeric field) in the query string will be ignored.
+ to a numeric field) in the query string will be ignored. This parameter can
+ be used only when the `q` query string parameter is specified.
:param max_docs: The maximum number of documents to update.
- :param pipeline: ID of the pipeline to use to preprocess incoming documents.
+ :param pipeline: The 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.
- :param preference: Specifies the node or shard the operation should be performed
- on. Random by default.
- :param q: Query in the Lucene query string syntax.
- :param query: Specifies the documents to update using the Query DSL.
+ :param preference: The node or shard the operation should be performed on. It
+ is random by default.
+ :param q: A query in the Lucene query string syntax.
+ :param query: The documents to update using the Query DSL.
:param refresh: If `true`, Elasticsearch refreshes affected shards to make the
- operation visible to search.
+ operation visible to search after the request completes. This is different
+ than the update API's `refresh` parameter, which causes just the shard that
+ received the request to be refreshed.
:param request_cache: If `true`, the request cache is used for this request.
+ It defaults to the index-level setting.
:param requests_per_second: The throttle for this request in sub-requests per
second.
- :param routing: Custom value used to route operations to a specific shard.
+ :param routing: A custom value used to route operations to a specific shard.
:param script: The script to run to update the document source or metadata when
updating.
- :param scroll: Period to retain the search context for scrolling.
- :param scroll_size: Size of the scroll request that powers the operation.
- :param search_timeout: Explicit timeout for each search request.
- :param search_type: The type of the search operation. Available options: `query_then_fetch`,
- `dfs_query_then_fetch`.
+ :param scroll: The period to retain the search context for scrolling.
+ :param scroll_size: The size of the scroll request that powers the operation.
+ :param search_timeout: An explicit timeout for each search request. By default,
+ there is no timeout.
+ :param search_type: The type of the search operation. Available options include
+ `query_then_fetch` and `dfs_query_then_fetch`.
:param slice: Slice the request manually using the provided slice ID and total
number of slices.
:param slices: The number of slices this task should be divided into.
:param sort: A comma-separated list of : pairs.
- :param stats: Specific `tag` of the request for logging and statistical purposes.
- :param terminate_after: Maximum number of documents to collect for each shard.
+ :param stats: The specific `tag` of the request for logging and statistical purposes.
+ :param terminate_after: The 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.
- :param timeout: Period each update request waits for the following operations:
- dynamic mapping updates, waiting for active shards.
+ Elasticsearch collects documents before sorting. IMPORTANT: 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.
+ :param timeout: The period each update request waits for the following operations:
+ dynamic mapping updates, waiting for active shards. By default, it is one
+ minute. This guarantees Elasticsearch waits for at least the timeout before
+ failing. The actual wait time could be longer, particularly when multiple
+ waits occur.
:param version: If `true`, returns the document version as part of a hit.
:param version_type: Should the document increment the version number (internal)
on hit or not (reindex)
:param wait_for_active_shards: 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`).
+ up to the total number of shards in the index (`number_of_replicas+1`). The
+ `timeout` parameter controls how long each write request waits for unavailable
+ shards to become available. Both work exactly the way they work in the bulk
+ API.
:param wait_for_completion: If `true`, the request blocks until the operation
- is complete.
+ is complete. If `false`, Elasticsearch performs some preflight checks, launches
+ the request, and returns a task ID that you can use to cancel or get the
+ status of the task. Elasticsearch creates a record of this task as a document
+ at `.tasks/task/${taskId}`.
"""
if index in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'index'")
@@ -5224,13 +6671,18 @@ async def update_by_query_rethrottle(
requests_per_second: t.Optional[float] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Changes the number of requests per second for a particular Update By Query operation.
+ .. raw:: html
- ``_
+ Throttle an update by query operation.
+ Change the number of requests per second for a particular update by query operation.
+ Rethrottling that speeds up the query takes effect immediately but rethrotting that slows down the query takes effect after completing the current batch to prevent scroll timeouts.
+
+
+ ``_
:param task_id: The ID for the task.
:param requests_per_second: The throttle for this request in sub-requests per
- second.
+ second. To turn off throttling, set it to `-1`.
"""
if task_id in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'task_id'")
diff --git a/elasticsearch/_async/client/_base.py b/elasticsearch/_async/client/_base.py
index dd0b0f44e..cc090671c 100644
--- a/elasticsearch/_async/client/_base.py
+++ b/elasticsearch/_async/client/_base.py
@@ -298,7 +298,6 @@ async def _perform_request(
def mimetype_header_to_compat(header: str) -> None:
# Converts all parts of a Accept/Content-Type headers
# from application/X -> application/vnd.elasticsearch+X
- nonlocal request_headers
mimetype = request_headers.get(header, None)
if mimetype:
request_headers[header] = _COMPAT_MIMETYPE_RE.sub(
diff --git a/elasticsearch/_async/client/async_search.py b/elasticsearch/_async/client/async_search.py
index 74bfdc0fc..c34530efc 100644
--- a/elasticsearch/_async/client/async_search.py
+++ b/elasticsearch/_async/client/async_search.py
@@ -36,13 +36,15 @@ async def delete(
pretty: t.Optional[bool] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Deletes an async search by identifier. If the search is still running, the search
- request will be cancelled. Otherwise, the saved search results are deleted. If
- the Elasticsearch security features are enabled, the deletion of a specific async
- search is restricted to: the authenticated user that submitted the original search
- request; users that have the `cancel_task` cluster privilege.
+ .. raw:: html
- ``_
+ Delete an async search.
+ If the asynchronous search is still running, it is cancelled.
+ Otherwise, the saved search results are deleted.
+ If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the cancel_task cluster privilege.
+
+
+ ``_
:param id: A unique identifier for the async search.
"""
@@ -85,16 +87,18 @@ async def get(
] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Retrieves the results of a previously submitted async search request given its
- identifier. If the Elasticsearch security features are enabled, access to the
- results of a specific async search is restricted to the user or API key that
- submitted it.
+ .. raw:: html
+
+ Get async search results.
+ Retrieve the results of a previously submitted asynchronous search request.
+ If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.
+
- ``_
+ ``_
:param id: A unique identifier for the async search.
- :param keep_alive: Specifies how long the async search should be available in
- the cluster. When not specified, the `keep_alive` set with the corresponding
+ :param keep_alive: The length of time that the async search should be available
+ in the cluster. When not specified, the `keep_alive` set with the corresponding
submit async request will be used. Otherwise, it is possible to override
the value and extend the validity of the request. When this period expires,
the search, if still running, is cancelled. If the search is completed, its
@@ -145,17 +149,27 @@ async def status(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
+ keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Get async search status Retrieves the status of a previously submitted async
- search request given its identifier, without retrieving search results. If the
- Elasticsearch security features are enabled, use of this API is restricted to
- the `monitoring_user` role.
+ .. raw:: html
+
+ Get the async search status.
+ Get the status of a previously submitted async search request given its identifier, without retrieving search results.
+ If the Elasticsearch security features are enabled, the access to the status of a specific async search is restricted to:
+
+ - The user or API key that submitted the original async search request.
+ - Users that have the
monitor cluster privilege or greater privileges.
+
+
- ``_
+ ``_
:param id: A unique identifier for the async search.
+ :param keep_alive: The length of time that the async search needs to be available.
+ Ongoing async searches and any saved search results are deleted after this
+ period.
"""
if id in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'id'")
@@ -168,6 +182,8 @@ async def status(
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
+ if keep_alive is not None:
+ __query["keep_alive"] = keep_alive
if pretty is not None:
__query["pretty"] = pretty
__headers = {"accept": "application/json"}
@@ -265,11 +281,9 @@ async def submit(
] = None,
lenient: t.Optional[bool] = None,
max_concurrent_shard_requests: t.Optional[int] = None,
- min_compatible_shard_node: t.Optional[str] = None,
min_score: t.Optional[float] = None,
pit: t.Optional[t.Mapping[str, t.Any]] = None,
post_filter: t.Optional[t.Mapping[str, t.Any]] = None,
- pre_filter_shard_size: t.Optional[int] = None,
preference: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
profile: t.Optional[bool] = None,
@@ -283,7 +297,6 @@ async def submit(
routing: t.Optional[str] = None,
runtime_mappings: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
script_fields: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
- scroll: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
search_after: t.Optional[
t.Sequence[t.Union[None, bool, float, int, str, t.Any]]
] = None,
@@ -323,17 +336,16 @@ async def submit(
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Runs a search request asynchronously. When the primary sort of the results is
- an indexed field, shards get sorted based on minimum and maximum value that they
- hold for that field, hence partial results become available following the sort
- criteria that was requested. Warning: Async search does not support scroll nor
- search requests that only include the suggest section. By default, Elasticsearch
- doesn’t allow you to store an async search response larger than 10Mb and an attempt
- to do this results in an error. The maximum allowed size for a stored async search
- response can be set by changing the `search.max_async_search_response_size` cluster
- level setting.
+ .. raw:: html
+
+ Run an async search.
+ When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field. Partial results become available following the sort criteria that was requested.
+ Warning: Asynchronous search does not support scroll or search requests that include only the suggest section.
+ By default, Elasticsearch does not allow you to store an async search response larger than 10Mb and an attempt to do this results in an error.
+ The maximum allowed size for a stored async search response can be set by changing the search.max_async_search_response_size cluster level setting.
+
- ``_
+ ``_
:param index: A comma-separated list of index names to search; use `_all` or
empty string to perform the operation on all indices
@@ -388,16 +400,11 @@ async def submit(
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
- :param min_compatible_shard_node:
:param min_score: Minimum _score for matching documents. Documents with a lower
- _score are not included in the search results.
+ _score are not included in search results and results collected by aggregations.
:param pit: Limits the search to a point in time (PIT). If you provide a PIT,
you cannot specify an in the request path.
:param post_filter:
- :param pre_filter_shard_size: The default value cannot be changed, which enforces
- the execution of a pre-filter roundtrip to retrieve statistics from each
- shard so that the ones that surely don’t hold any document matching the query
- get skipped.
:param preference: Specify the node or shard the operation should be performed
on (default: random)
:param profile:
@@ -406,13 +413,13 @@ async def submit(
:param request_cache: Specify if request cache should be used for this request
or not, defaults to true
:param rescore:
- :param rest_total_hits_as_int:
+ :param rest_total_hits_as_int: Indicates whether hits.total should be rendered
+ as an integer or an object in the rest search response
:param routing: A comma-separated list of specific routing values
:param runtime_mappings: Defines one or more runtime fields in the search request.
These fields take precedence over mapped fields with the same name.
:param script_fields: Retrieve a script evaluation (based on different fields)
for each hit.
- :param scroll:
:param search_after:
:param search_type: Search operation type
:param seq_no_primary_term: If true, returns sequence number and primary term
@@ -517,10 +524,6 @@ async def submit(
__query["lenient"] = lenient
if max_concurrent_shard_requests is not None:
__query["max_concurrent_shard_requests"] = max_concurrent_shard_requests
- if min_compatible_shard_node is not None:
- __query["min_compatible_shard_node"] = min_compatible_shard_node
- if pre_filter_shard_size is not None:
- __query["pre_filter_shard_size"] = pre_filter_shard_size
if preference is not None:
__query["preference"] = preference
if pretty is not None:
@@ -533,8 +536,6 @@ async def submit(
__query["rest_total_hits_as_int"] = rest_total_hits_as_int
if routing is not None:
__query["routing"] = routing
- if scroll is not None:
- __query["scroll"] = scroll
if search_type is not None:
__query["search_type"] = search_type
if source_excludes is not None:
diff --git a/elasticsearch/_async/client/autoscaling.py b/elasticsearch/_async/client/autoscaling.py
index b558e94a5..8de430f83 100644
--- a/elasticsearch/_async/client/autoscaling.py
+++ b/elasticsearch/_async/client/autoscaling.py
@@ -33,15 +33,25 @@ async def delete_autoscaling_policy(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
+ master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
+ timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Deletes an autoscaling policy. Designed for indirect use by ECE/ESS and ECK.
- Direct use is not supported.
+ .. raw:: html
- ``_
+ Delete an autoscaling policy.
+ NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
+
+
+ ``_
:param name: the name of the autoscaling policy
+ :param master_timeout: 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.
+ :param timeout: Period to wait for a response. If no response is received before
+ the timeout expires, the request fails and returns an error.
"""
if name in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'name'")
@@ -54,8 +64,12 @@ async def delete_autoscaling_policy(
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
+ if master_timeout is not None:
+ __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
+ if timeout is not None:
+ __query["timeout"] = timeout
__headers = {"accept": "application/json"}
return await self.perform_request( # type: ignore[return-value]
"DELETE",
@@ -73,13 +87,28 @@ async def get_autoscaling_capacity(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
+ master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Gets the current autoscaling capacity based on the configured autoscaling policy.
- Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.
+ .. raw:: html
+
+ Get the autoscaling capacity.
+ NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
+ This API gets the current autoscaling capacity based on the configured autoscaling policy.
+ It will return information to size the cluster appropriately to the current workload.
+ The required_capacity is calculated as the maximum of the required_capacity result of all individual deciders that are enabled for the policy.
+ The operator should verify that the current_nodes match the operator’s knowledge of the cluster to avoid making autoscaling decisions based on stale or incomplete information.
+ The response contains decider-specific information you can use to diagnose how and why autoscaling determined a certain capacity was required.
+ This information is provided for diagnosis only.
+ Do not use this information to make autoscaling decisions.
+
+
+ ``_
- ``_
+ :param master_timeout: 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.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_autoscaling/capacity"
@@ -90,6 +119,8 @@ async def get_autoscaling_capacity(
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
+ if master_timeout is not None:
+ __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
__headers = {"accept": "application/json"}
@@ -110,15 +141,22 @@ async def get_autoscaling_policy(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
+ master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Retrieves an autoscaling policy. Designed for indirect use by ECE/ESS and ECK.
- Direct use is not supported.
+ .. raw:: html
- ``_
+ Get an autoscaling policy.
+ NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
+
+
+ ``_
:param name: the name of the autoscaling policy
+ :param master_timeout: 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.
"""
if name in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'name'")
@@ -131,6 +169,8 @@ async def get_autoscaling_policy(
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
+ if master_timeout is not None:
+ __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
__headers = {"accept": "application/json"}
@@ -155,16 +195,26 @@ async def put_autoscaling_policy(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
+ master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
+ timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Creates a new autoscaling policy. Designed for indirect use by ECE/ESS and ECK.
- Direct use is not supported.
+ .. raw:: html
+
+ Create or update an autoscaling policy.
+ NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
+
- ``_
+ ``_
:param name: the name of the autoscaling policy
:param policy:
+ :param master_timeout: 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.
+ :param timeout: Period to wait for a response. If no response is received before
+ the timeout expires, the request fails and returns an error.
"""
if name in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'name'")
@@ -183,8 +233,12 @@ async def put_autoscaling_policy(
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
+ if master_timeout is not None:
+ __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
+ if timeout is not None:
+ __query["timeout"] = timeout
__body = policy if policy is not None else body
__headers = {"accept": "application/json", "content-type": "application/json"}
return await self.perform_request( # type: ignore[return-value]
diff --git a/elasticsearch/_async/client/cat.py b/elasticsearch/_async/client/cat.py
index 83a393e7a..8a048de5f 100644
--- a/elasticsearch/_async/client/cat.py
+++ b/elasticsearch/_async/client/cat.py
@@ -20,7 +20,13 @@
from elastic_transport import ObjectApiResponse, TextApiResponse
from ._base import NamespacedClient
-from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters
+from .utils import (
+ SKIP_IN_PATH,
+ Stability,
+ _quote,
+ _rewrite_parameters,
+ _stability_warning,
+)
class CatClient(NamespacedClient):
@@ -30,6 +36,9 @@ async def aliases(
self,
*,
name: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
expand_wildcards: t.Optional[
t.Union[
@@ -41,41 +50,88 @@ async def aliases(
] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "alias",
+ "filter",
+ "index",
+ "is_write_index",
+ "routing.index",
+ "routing.search",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "alias",
+ "filter",
+ "index",
+ "is_write_index",
+ "routing.index",
+ "routing.search",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Get aliases. Retrieves the cluster’s index aliases, including filter and routing
- information. The API does not return data stream aliases. CAT APIs are only intended
- for human consumption using the command line or the Kibana console. They are
- not intended for use by applications. For application consumption, use the aliases
- API.
+ .. raw:: html
- ``_
+ Get aliases.
+ Get the cluster's index aliases, including filter and routing information.
+ This API does not return data stream aliases.
+ IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
+
+
+ ``_
:param name: A comma-separated list of aliases to retrieve. Supports wildcards
(`*`). To retrieve all aliases, omit this parameter or use `*` or `_all`.
- :param expand_wildcards: Whether to expand wildcard expression to concrete indices
- that are open, closed or both.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
+ :param expand_wildcards: The 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. It supports comma-separated
+ values, such as `open,hidden`.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
the local cluster state. If `false` the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -86,6 +142,8 @@ async def aliases(
__path_parts = {}
__path = "/_cat/aliases"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if expand_wildcards is not None:
@@ -102,12 +160,12 @@ async def aliases(
__query["human"] = human
if local is not None:
__query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -131,28 +189,83 @@ async def allocation(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "disk.avail",
+ "disk.indices",
+ "disk.indices.forecast",
+ "disk.percent",
+ "disk.total",
+ "disk.used",
+ "host",
+ "ip",
+ "node",
+ "node.role",
+ "shards",
+ "shards.undesired",
+ "write_load.forecast",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "disk.avail",
+ "disk.indices",
+ "disk.indices.forecast",
+ "disk.percent",
+ "disk.total",
+ "disk.used",
+ "host",
+ "ip",
+ "node",
+ "node.role",
+ "shards",
+ "shards.undesired",
+ "write_load.forecast",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Provides a snapshot of the number of shards allocated to each data node and their
- disk space. IMPORTANT: cat APIs are only intended for human consumption using
- the command line or Kibana console. They are not intended for use by applications.
+ .. raw:: html
+
+ Get shard allocation information.
+ Get a snapshot of the number of shards allocated to each data node and their disk space.
+ IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
- ``_
- :param node_id: Comma-separated list of node identifiers or names used to limit
+ ``_
+
+ :param node_id: A comma-separated list of node identifiers or names used to limit
the returned information.
- :param bytes: The unit used to display byte values.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
@@ -163,6 +276,12 @@ async def allocation(
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -195,6 +314,8 @@ async def allocation(
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -212,43 +333,95 @@ async def component_templates(
self,
*,
name: t.Optional[str] = None,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "alias_count",
+ "included_in",
+ "mapping_count",
+ "metadata_count",
+ "name",
+ "settings_count",
+ "version",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "alias_count",
+ "included_in",
+ "mapping_count",
+ "metadata_count",
+ "name",
+ "settings_count",
+ "version",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Get component templates. Returns information about component templates in a cluster.
- Component templates are building blocks for constructing index templates that
- specify index mappings, settings, and aliases. CAT APIs are only intended for
- human consumption using the command line or Kibana console. They are not intended
- for use by applications. For application consumption, use the get component template
- API.
+ .. raw:: html
+
+ Get component templates.
+ Get information about component templates in a cluster.
+ Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
+ IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console.
+ They are not intended for use by applications. For application consumption, use the get component template API.
- ``_
- :param name: The name of the component template. Accepts wildcard expressions.
- If omitted, all component templates are returned.
+ ``_
+
+ :param name: The name of the component template. It accepts wildcard expressions.
+ If it is omitted, all component templates are returned.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
the local cluster state. If `false` the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
+ :param master_timeout: The period to wait for a connection to the master node.
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -259,6 +432,8 @@ async def component_templates(
__path_parts = {}
__path = "/_cat/component_templates"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -279,6 +454,8 @@ async def component_templates(
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -296,44 +473,65 @@ async def count(
self,
*,
index: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[t.Union[str, t.Literal["count", "epoch", "timestamp"]]],
+ t.Union[str, t.Literal["count", "epoch", "timestamp"]],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Get a document count. Provides quick access to a document count for a data stream,
- an index, or an entire cluster. The document count only includes live documents,
- not deleted documents which have not yet been removed by the merge process. CAT
- APIs are only intended for human consumption using the command line or Kibana
- console. They are not intended for use by applications. For application consumption,
- use the count API.
+ .. raw:: html
- ``_
+ Get a document count.
+ Get quick access to a document count for a data stream, an index, or an entire cluster.
+ The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.
+ IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console.
+ They are not intended for use by applications. For application consumption, use the count API.
- :param index: Comma-separated list of data streams, indices, and aliases used
- to limit the request. Supports wildcards (`*`). To target all data streams
+
+ ``_
+
+ :param index: A comma-separated list of data streams, indices, and aliases used
+ to limit the request. It supports wildcards (`*`). To target all data streams
and indices, omit this parameter or use `*` or `_all`.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -344,6 +542,8 @@ async def count(
__path_parts = {}
__path = "/_cat/count"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -356,14 +556,12 @@ async def count(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -387,39 +585,59 @@ async def fielddata(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[str, t.Literal["field", "host", "id", "ip", "node", "size"]]
+ ],
+ t.Union[str, t.Literal["field", "host", "id", "ip", "node", "size"]],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns the amount of heap memory currently used by the field data cache on every
- data node in the cluster. IMPORTANT: cat APIs are only intended for human consumption
- using the command line or Kibana console. They are not intended for use by applications.
- For application consumption, use the nodes stats API.
+ .. raw:: html
+
+ Get field data cache information.
+ Get the amount of heap memory currently used by the field data cache on every data node in the cluster.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+ They are not intended for use by applications. For application consumption, use the nodes stats API.
+
- ``_
+ ``_
:param fields: Comma-separated list of fields used to limit returned information.
To retrieve all fields, omit this parameter.
- :param bytes: The unit used to display byte values.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -444,14 +662,12 @@ async def fielddata(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -468,14 +684,15 @@ async def fielddata(
async def health(
self,
*,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
time: t.Optional[
@@ -485,40 +702,52 @@ async def health(
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns the health status of a cluster, similar to the cluster health API. IMPORTANT:
- cat APIs are only intended for human consumption using the command line or Kibana
- console. They are not intended for use by applications. For application consumption,
- use the cluster health API. This API is often used to check malfunctioning clusters.
- To help you track cluster health alongside log files and alerting systems, the
- API returns timestamps in two formats: `HH:MM:SS`, which is human-readable but
- includes no date information; `Unix epoch time`, which is machine-sortable and
- includes date information. The latter format is useful for cluster recoveries
- that take multiple days. You can use the cat health API to verify cluster health
- across multiple nodes. You also can use the API to track the recovery of a large
- cluster over a longer period of time.
-
- ``_
+ .. raw:: html
+
+ Get the cluster health status.
+ IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console.
+ They are not intended for use by applications. For application consumption, use the cluster health API.
+ This API is often used to check malfunctioning clusters.
+ To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats:
+ HH:MM:SS, which is human-readable but includes no date information;
+ Unix epoch time, which is machine-sortable and includes date information.
+ The latter format is useful for cluster recoveries that take multiple days.
+ You can use the cat health API to verify cluster health across multiple nodes.
+ You also can use the API to track the recovery of a large cluster over a longer period of time.
+
+
+ ``_
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: List of columns to appear in the response. Supports simple wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
- :param time: The unit used to display time values.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param ts: If true, returns `HH:MM:SS` and Unix epoch timestamps.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_cat/health"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -531,10 +760,6 @@ async def health(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
@@ -556,66 +781,19 @@ async def health(
)
@_rewrite_parameters()
- async def help(
- self,
- *,
- error_trace: t.Optional[bool] = None,
- filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
- format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
- help: t.Optional[bool] = None,
- human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
- pretty: t.Optional[bool] = None,
- s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
- v: t.Optional[bool] = None,
- ) -> TextApiResponse:
+ async def help(self) -> TextApiResponse:
"""
- Get CAT help. Returns help for the CAT APIs.
+ .. raw:: html
- ``_
+ Get CAT help.
+ Get help for the CAT APIs.
- :param format: Specifies the format to return the columnar data in, can be set
- to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
- :param help: When set to `true` will output available columns. This option can't
- be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
- :param v: When set to `true` will enable verbose output.
+
+ ``_
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_cat"
__query: t.Dict[str, t.Any] = {}
- if error_trace is not None:
- __query["error_trace"] = error_trace
- if filter_path is not None:
- __query["filter_path"] = filter_path
- if format is not None:
- __query["format"] = format
- if h is not None:
- __query["h"] = h
- if help is not None:
- __query["help"] = help
- if human is not None:
- __query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
- if pretty is not None:
- __query["pretty"] = pretty
- if s is not None:
- __query["s"] = s
- if v is not None:
- __query["v"] = v
__headers = {"accept": "text/plain"}
return await self.perform_request( # type: ignore[return-value]
"GET",
@@ -646,11 +824,12 @@ async def indices(
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
- health: t.Optional[t.Union[str, t.Literal["green", "red", "yellow"]]] = None,
+ health: t.Optional[
+ t.Union[str, t.Literal["green", "red", "unavailable", "unknown", "yellow"]]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
include_unloaded_segments: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
pri: t.Optional[bool] = None,
@@ -661,23 +840,37 @@ async def indices(
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Get index information. Returns high-level information about indices in a cluster,
- including backing indices for data streams. Use this request to get the following
- information for each index in a cluster: - shard count - document count - deleted
- document count - primary store size - total store size of all shards, including
- shard replicas These metrics are retrieved directly from Lucene, which Elasticsearch
- uses internally to power indexing and search. As a result, all document counts
- include hidden nested documents. To get an accurate count of Elasticsearch documents,
- use the cat count or count APIs. CAT APIs are only intended for human consumption
- using the command line or Kibana console. They are not intended for use by applications.
- For application consumption, use an index endpoint.
-
- ``_
+ .. raw:: html
+
+ Get index information.
+ Get high-level information about indices in a cluster, including backing indices for data streams.
+ Use this request to get the following information for each index in a cluster:
+
+ - shard count
+ - document count
+ - deleted document count
+ - primary store size
+ - total store size of all shards, including shard replicas
+
+ These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents.
+ To get an accurate count of Elasticsearch documents, use the cat count or count APIs.
+ CAT APIs are only intended for human consumption using the command line or Kibana console.
+ They are not intended for use by applications. For application consumption, use an index endpoint.
+
+
+ ``_
:param index: 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`.
- :param bytes: The unit used to display byte values.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param expand_wildcards: The type of index that wildcard patterns can match.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
@@ -688,16 +881,17 @@ async def indices(
be combined with any other query string option.
:param include_unloaded_segments: If true, the response includes information
from segments that are not loaded into memory.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
:param master_timeout: Period to wait for a connection to the master node.
:param pri: If true, the response only includes information from primary shards.
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
- :param time: The unit used to display time values.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -728,8 +922,6 @@ async def indices(
__query["human"] = human
if include_unloaded_segments is not None:
__query["include_unloaded_segments"] = include_unloaded_segments
- if local is not None:
- __query["local"] = local
if master_timeout is not None:
__query["master_timeout"] = master_timeout
if pretty is not None:
@@ -756,6 +948,9 @@ async def indices(
async def master(
self,
*,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
@@ -766,16 +961,29 @@ async def master(
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns information about the master node, including the ID, bound IP address,
- and name. IMPORTANT: cat APIs are only intended for human consumption using the
- command line or Kibana console. They are not intended for use by applications.
- For application consumption, use the nodes info API.
+ .. raw:: html
+
+ Get master node information.
+ Get information about the master node, including the ID, bound IP address, and name.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
- ``_
+ ``_
+
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: List of columns to appear in the response. Supports simple wildcards.
@@ -789,11 +997,19 @@ async def master(
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_cat/master"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -814,6 +1030,8 @@ async def master(
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -888,8 +1106,6 @@ async def ml_data_frame_analytics(
] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[
t.Union[
@@ -939,35 +1155,47 @@ async def ml_data_frame_analytics(
],
]
] = None,
- time: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Get data frame analytics jobs. Returns configuration and usage information about
- data frame analytics jobs. CAT APIs are only intended for human consumption using
- the Kibana console or command line. They are not intended for use by applications.
- For application consumption, use the get data frame analytics jobs statistics
- API.
+ .. raw:: html
+
+ Get data frame analytics jobs.
+ Get configuration and usage information about data frame analytics jobs.
+ IMPORTANT: CAT APIs are only intended for human consumption using the Kibana
+ console or command line. They are not intended for use by applications. For
+ application consumption, use the get data frame analytics jobs statistics API.
+
- ``_
+ ``_
:param id: The ID of the data frame analytics to fetch
:param allow_no_match: Whether to ignore if a wildcard expression matches no
- configs. (This includes `_all` string or when no configs have been specified)
- :param bytes: The unit in which to display byte values
+ configs. (This includes `_all` string or when no configs have been specified.)
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: Comma-separated list of column names to display.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
:param s: Comma-separated list of column names or column aliases used to sort
the response.
- :param time: Unit used to display time values.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -994,10 +1222,6 @@ async def ml_data_frame_analytics(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
@@ -1022,6 +1246,9 @@ async def ml_datafeeds(
*,
datafeed_id: t.Optional[str] = None,
allow_no_match: t.Optional[bool] = None,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
@@ -1067,8 +1294,6 @@ async def ml_datafeeds(
] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[
t.Union[
@@ -1116,14 +1341,19 @@ async def ml_datafeeds(
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Get datafeeds. Returns configuration and usage information about datafeeds. This
- API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features
- are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage`
- cluster privileges to use this API. CAT APIs are only intended for human consumption
- using the Kibana console or command line. They are not intended for use by applications.
- For application consumption, use the get datafeed statistics API.
+ .. raw:: html
+
+ Get datafeeds.
+ Get configuration and usage information about datafeeds.
+ This API returns a maximum of 10,000 datafeeds.
+ If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage
+ cluster privileges to use this API.
+ IMPORTANT: CAT APIs are only intended for human consumption using the Kibana
+ console or command line. They are not intended for use by applications. For
+ application consumption, use the get datafeed statistics API.
- ``_
+
+ ``_
:param datafeed_id: A numerical character string that uniquely identifies the
datafeed.
@@ -1134,19 +1364,27 @@ async def ml_datafeeds(
array when there are no matches and the subset of results when there are
partial matches. If `false`, the API returns a 404 status code when there
are no matches or only partial matches.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: Comma-separated list of column names to display.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
:param s: Comma-separated list of column names or column aliases used to sort
the response.
- :param time: The unit used to display time values.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -1159,6 +1397,8 @@ async def ml_datafeeds(
__query: t.Dict[str, t.Any] = {}
if allow_no_match is not None:
__query["allow_no_match"] = allow_no_match
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -1171,10 +1411,6 @@ async def ml_datafeeds(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
@@ -1343,8 +1579,6 @@ async def ml_jobs(
] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[
t.Union[
@@ -1488,15 +1722,19 @@ async def ml_jobs(
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Get anomaly detection jobs. Returns configuration and usage information for anomaly
- detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch
- security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`,
- or `manage` cluster privileges to use this API. CAT APIs are only intended for
- human consumption using the Kibana console or command line. They are not intended
- for use by applications. For application consumption, use the get anomaly detection
- job statistics API.
+ .. raw:: html
+
+ Get anomaly detection jobs.
+ Get configuration and usage information for anomaly detection jobs.
+ This API returns a maximum of 10,000 jobs.
+ If the Elasticsearch security features are enabled, you must have monitor_ml,
+ monitor, manage_ml, or manage cluster privileges to use this API.
+ IMPORTANT: CAT APIs are only intended for human consumption using the Kibana
+ console or command line. They are not intended for use by applications. For
+ application consumption, use the get anomaly detection job statistics API.
- ``_
+
+ ``_
:param job_id: Identifier for the anomaly detection job.
:param allow_no_match: Specifies what to do when the request: * Contains wildcard
@@ -1506,20 +1744,27 @@ async def ml_jobs(
array when there are no matches and the subset of results when there are
partial matches. If `false`, the API returns a 404 status code when there
are no matches or only partial matches.
- :param bytes: The unit used to display byte values.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: Comma-separated list of column names to display.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
:param s: Comma-separated list of column names or column aliases used to sort
the response.
- :param time: The unit used to display time values.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -1546,10 +1791,6 @@ async def ml_jobs(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
@@ -1629,8 +1870,6 @@ async def ml_trained_models(
] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[
t.Union[
@@ -1677,15 +1916,22 @@ async def ml_trained_models(
]
] = None,
size: t.Optional[int] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Get trained models. Returns configuration and usage information about inference
- trained models. CAT APIs are only intended for human consumption using the Kibana
- console or command line. They are not intended for use by applications. For application
- consumption, use the get trained models statistics API.
+ .. raw:: html
+
+ Get trained models.
+ Get configuration and usage information about inference trained models.
+ IMPORTANT: CAT APIs are only intended for human consumption using the Kibana
+ console or command line. They are not intended for use by applications. For
+ application consumption, use the get trained models statistics API.
+
- ``_
+ ``_
:param model_id: A unique identifier for the trained model.
:param allow_no_match: Specifies what to do when the request: contains wildcard
@@ -1695,21 +1941,29 @@ async def ml_trained_models(
when there are no matches and the subset of results when there are partial
matches. If `false`, the API returns a 404 status code when there are no
matches or only partial matches.
- :param bytes: The unit used to display byte values.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param from_: Skips the specified number of transforms.
:param h: A comma-separated list of column names to display.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
:param s: A comma-separated list of column names or aliases used to sort the
response.
:param size: The maximum number of transforms to display.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -1738,16 +1992,14 @@ async def ml_trained_models(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
if size is not None:
__query["size"] = size
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -1764,6 +2016,9 @@ async def ml_trained_models(
async def nodeattrs(
self,
*,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
@@ -1774,16 +2029,29 @@ async def nodeattrs(
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns information about custom node attributes. IMPORTANT: cat APIs are only
- intended for human consumption using the command line or Kibana console. They
- are not intended for use by applications. For application consumption, use the
- nodes info API.
+ .. raw:: html
+
+ Get node attribute information.
+ Get information about custom node attributes.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
- ``_
+ ``_
+
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: List of columns to appear in the response. Supports simple wildcards.
@@ -1797,11 +2065,19 @@ async def nodeattrs(
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_cat/nodeattrs"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -1822,6 +2098,8 @@ async def nodeattrs(
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -1845,42 +2123,249 @@ async def nodes(
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
full_id: t.Optional[t.Union[bool, str]] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "build",
+ "completion.size",
+ "cpu",
+ "disk.avail",
+ "disk.total",
+ "disk.used",
+ "disk.used_percent",
+ "fielddata.evictions",
+ "fielddata.memory_size",
+ "file_desc.current",
+ "file_desc.max",
+ "file_desc.percent",
+ "flush.total",
+ "flush.total_time",
+ "get.current",
+ "get.exists_time",
+ "get.exists_total",
+ "get.missing_time",
+ "get.missing_total",
+ "get.time",
+ "get.total",
+ "heap.current",
+ "heap.max",
+ "heap.percent",
+ "http_address",
+ "id",
+ "indexing.delete_current",
+ "indexing.delete_time",
+ "indexing.delete_total",
+ "indexing.index_current",
+ "indexing.index_failed",
+ "indexing.index_failed_due_to_version_conflict",
+ "indexing.index_time",
+ "indexing.index_total",
+ "ip",
+ "jdk",
+ "load_15m",
+ "load_1m",
+ "load_5m",
+ "mappings.total_count",
+ "mappings.total_estimated_overhead_in_bytes",
+ "master",
+ "merges.current",
+ "merges.current_docs",
+ "merges.current_size",
+ "merges.total",
+ "merges.total_docs",
+ "merges.total_size",
+ "merges.total_time",
+ "name",
+ "node.role",
+ "pid",
+ "port",
+ "query_cache.evictions",
+ "query_cache.hit_count",
+ "query_cache.memory_size",
+ "query_cache.miss_count",
+ "ram.current",
+ "ram.max",
+ "ram.percent",
+ "refresh.time",
+ "refresh.total",
+ "request_cache.evictions",
+ "request_cache.hit_count",
+ "request_cache.memory_size",
+ "request_cache.miss_count",
+ "script.cache_evictions",
+ "script.compilations",
+ "search.fetch_current",
+ "search.fetch_time",
+ "search.fetch_total",
+ "search.open_contexts",
+ "search.query_current",
+ "search.query_time",
+ "search.query_total",
+ "search.scroll_current",
+ "search.scroll_time",
+ "search.scroll_total",
+ "segments.count",
+ "segments.fixed_bitset_memory",
+ "segments.index_writer_memory",
+ "segments.memory",
+ "segments.version_map_memory",
+ "shard_stats.total_count",
+ "suggest.current",
+ "suggest.time",
+ "suggest.total",
+ "uptime",
+ "version",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "build",
+ "completion.size",
+ "cpu",
+ "disk.avail",
+ "disk.total",
+ "disk.used",
+ "disk.used_percent",
+ "fielddata.evictions",
+ "fielddata.memory_size",
+ "file_desc.current",
+ "file_desc.max",
+ "file_desc.percent",
+ "flush.total",
+ "flush.total_time",
+ "get.current",
+ "get.exists_time",
+ "get.exists_total",
+ "get.missing_time",
+ "get.missing_total",
+ "get.time",
+ "get.total",
+ "heap.current",
+ "heap.max",
+ "heap.percent",
+ "http_address",
+ "id",
+ "indexing.delete_current",
+ "indexing.delete_time",
+ "indexing.delete_total",
+ "indexing.index_current",
+ "indexing.index_failed",
+ "indexing.index_failed_due_to_version_conflict",
+ "indexing.index_time",
+ "indexing.index_total",
+ "ip",
+ "jdk",
+ "load_15m",
+ "load_1m",
+ "load_5m",
+ "mappings.total_count",
+ "mappings.total_estimated_overhead_in_bytes",
+ "master",
+ "merges.current",
+ "merges.current_docs",
+ "merges.current_size",
+ "merges.total",
+ "merges.total_docs",
+ "merges.total_size",
+ "merges.total_time",
+ "name",
+ "node.role",
+ "pid",
+ "port",
+ "query_cache.evictions",
+ "query_cache.hit_count",
+ "query_cache.memory_size",
+ "query_cache.miss_count",
+ "ram.current",
+ "ram.max",
+ "ram.percent",
+ "refresh.time",
+ "refresh.total",
+ "request_cache.evictions",
+ "request_cache.hit_count",
+ "request_cache.memory_size",
+ "request_cache.miss_count",
+ "script.cache_evictions",
+ "script.compilations",
+ "search.fetch_current",
+ "search.fetch_time",
+ "search.fetch_total",
+ "search.open_contexts",
+ "search.query_current",
+ "search.query_time",
+ "search.query_total",
+ "search.scroll_current",
+ "search.scroll_time",
+ "search.scroll_total",
+ "segments.count",
+ "segments.fixed_bitset_memory",
+ "segments.index_writer_memory",
+ "segments.memory",
+ "segments.version_map_memory",
+ "shard_stats.total_count",
+ "suggest.current",
+ "suggest.time",
+ "suggest.total",
+ "uptime",
+ "version",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
include_unloaded_segments: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns information about the nodes in a cluster. IMPORTANT: cat APIs are only
- intended for human consumption using the command line or Kibana console. They
- are not intended for use by applications. For application consumption, use the
- nodes info API.
+ .. raw:: html
+
+ Get node information.
+ Get information about the nodes in a cluster.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
+
- ``_
+ ``_
- :param bytes: The unit used to display byte values.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param full_id: If `true`, return the full node ID. If `false`, return the shortened
node ID.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param include_unloaded_segments: If true, the response includes information
from segments that are not loaded into memory.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
+ :param master_timeout: The period to wait for a connection to the master node.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str] = {}
@@ -1904,14 +2389,14 @@ async def nodes(
__query["human"] = human
if include_unloaded_segments is not None:
__query["include_unloaded_segments"] = include_unloaded_segments
- if local is not None:
- __query["local"] = local
if master_timeout is not None:
__query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -1928,6 +2413,9 @@ async def nodes(
async def pending_tasks(
self,
*,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
@@ -1938,16 +2426,29 @@ async def pending_tasks(
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns cluster-level changes that have not yet been executed. IMPORTANT: cat
- APIs are only intended for human consumption using the command line or Kibana
- console. They are not intended for use by applications. For application consumption,
- use the pending cluster tasks API.
+ .. raw:: html
+
+ Get pending task information.
+ Get information about cluster-level changes that have not yet taken effect.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the pending cluster tasks API.
+
- ``_
+ ``_
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: List of columns to appear in the response. Supports simple wildcards.
@@ -1961,11 +2462,19 @@ async def pending_tasks(
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_cat/pending_tasks"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -1986,6 +2495,8 @@ async def pending_tasks(
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -2002,31 +2513,49 @@ async def pending_tasks(
async def plugins(
self,
*,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
+ include_bootstrap: t.Optional[bool] = None,
local: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns a list of plugins running on each node of a cluster. IMPORTANT: cat APIs
- are only intended for human consumption using the command line or Kibana console.
- They are not intended for use by applications. For application consumption, use
- the nodes info API.
+ .. raw:: html
+
+ Get plugin information.
+ Get a list of plugins running on each node of a cluster.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
+
- ``_
+ ``_
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: List of columns to appear in the response. Supports simple wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
+ :param include_bootstrap: Include bootstrap plugins in the response
:param local: If `true`, the request computes the list of selected nodes from
the local cluster state. If `false` the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
@@ -2035,11 +2564,19 @@ async def plugins(
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_cat/plugins"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -2052,6 +2589,8 @@ async def plugins(
__query["help"] = help
if human is not None:
__query["human"] = human
+ if include_bootstrap is not None:
+ __query["include_bootstrap"] = include_bootstrap
if local is not None:
__query["local"] = local
if master_timeout is not None:
@@ -2060,6 +2599,8 @@ async def plugins(
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -2085,47 +2626,124 @@ async def recovery(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "bytes",
+ "bytes_percent",
+ "bytes_recovered",
+ "bytes_total",
+ "files",
+ "files_percent",
+ "files_recovered",
+ "files_total",
+ "index",
+ "repository",
+ "shard",
+ "snapshot",
+ "source_host",
+ "source_node",
+ "stage",
+ "start_time",
+ "start_time_millis",
+ "stop_time",
+ "stop_time_millis",
+ "target_host",
+ "target_node",
+ "time",
+ "translog_ops",
+ "translog_ops_percent",
+ "translog_ops_recovered",
+ "type",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "bytes",
+ "bytes_percent",
+ "bytes_recovered",
+ "bytes_total",
+ "files",
+ "files_percent",
+ "files_recovered",
+ "files_total",
+ "index",
+ "repository",
+ "shard",
+ "snapshot",
+ "source_host",
+ "source_node",
+ "stage",
+ "start_time",
+ "start_time_millis",
+ "stop_time",
+ "stop_time_millis",
+ "target_host",
+ "target_node",
+ "time",
+ "translog_ops",
+ "translog_ops_percent",
+ "translog_ops_recovered",
+ "type",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns information about ongoing and completed shard recoveries. Shard recovery
- is the process of initializing a shard copy, such as restoring a primary shard
- from a snapshot or syncing a replica shard from a primary shard. When a shard
- recovery completes, the recovered shard is available for search and indexing.
- For data streams, the API returns information about the stream’s backing indices.
- IMPORTANT: cat APIs are only intended for human consumption using the command
- line or Kibana console. They are not intended for use by applications. For application
- consumption, use the index recovery API.
+ .. raw:: html
- ``_
+ Get shard recovery information.
+ Get information about ongoing and completed shard recoveries.
+ Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing.
+ For data streams, the API returns information about the stream’s backing indices.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index recovery API.
+
+
+ ``_
:param index: A 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`.
:param active_only: If `true`, the response only includes ongoing shard recoveries.
- :param bytes: The unit used to display byte values.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param detailed: If `true`, the response includes detailed information about
shard recoveries.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -2154,14 +2772,12 @@ async def recovery(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -2178,6 +2794,9 @@ async def recovery(
async def repositories(
self,
*,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
@@ -2188,16 +2807,29 @@ async def repositories(
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns the snapshot repositories for a cluster. IMPORTANT: cat APIs are only
- intended for human consumption using the command line or Kibana console. They
- are not intended for use by applications. For application consumption, use the
- get snapshot repository API.
+ .. raw:: html
+
+ Get snapshot repository information.
+ Get a list of snapshot repositories for a cluster.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot repository API.
- ``_
+ ``_
+
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: List of columns to appear in the response. Supports simple wildcards.
@@ -2211,11 +2843,19 @@ async def repositories(
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_cat/repositories"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -2236,6 +2876,8 @@ async def repositories(
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -2259,31 +2901,89 @@ async def segments(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "committed",
+ "compound",
+ "docs.count",
+ "docs.deleted",
+ "generation",
+ "id",
+ "index",
+ "ip",
+ "prirep",
+ "searchable",
+ "segment",
+ "shard",
+ "size",
+ "size.memory",
+ "version",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "committed",
+ "compound",
+ "docs.count",
+ "docs.deleted",
+ "generation",
+ "id",
+ "index",
+ "ip",
+ "prirep",
+ "searchable",
+ "segment",
+ "shard",
+ "size",
+ "size.memory",
+ "version",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns low-level information about the Lucene segments in index shards. For
- data streams, the API returns information about the backing indices. IMPORTANT:
- cat APIs are only intended for human consumption using the command line or Kibana
- console. They are not intended for use by applications. For application consumption,
- use the index segments API.
+ .. raw:: html
+
+ Get segment information.
+ Get low-level information about the Lucene segments in index shards.
+ For data streams, the API returns information about the backing indices.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index segments API.
- ``_
+
+ ``_
:param index: A 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`.
- :param bytes: The unit used to display byte values.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
@@ -2291,9 +2991,15 @@ async def segments(
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
:param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -2326,6 +3032,8 @@ async def segments(
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -2349,40 +3057,209 @@ async def shards(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "completion.size",
+ "dataset.size",
+ "dense_vector.value_count",
+ "docs",
+ "dsparse_vector.value_count",
+ "fielddata.evictions",
+ "fielddata.memory_size",
+ "flush.total",
+ "flush.total_time",
+ "get.current",
+ "get.exists_time",
+ "get.exists_total",
+ "get.missing_time",
+ "get.missing_total",
+ "get.time",
+ "get.total",
+ "id",
+ "index",
+ "indexing.delete_current",
+ "indexing.delete_time",
+ "indexing.delete_total",
+ "indexing.index_current",
+ "indexing.index_failed",
+ "indexing.index_failed_due_to_version_conflict",
+ "indexing.index_time",
+ "indexing.index_total",
+ "ip",
+ "merges.current",
+ "merges.current_docs",
+ "merges.current_size",
+ "merges.total",
+ "merges.total_docs",
+ "merges.total_size",
+ "merges.total_time",
+ "node",
+ "prirep",
+ "query_cache.evictions",
+ "query_cache.memory_size",
+ "recoverysource.type",
+ "refresh.time",
+ "refresh.total",
+ "search.fetch_current",
+ "search.fetch_time",
+ "search.fetch_total",
+ "search.open_contexts",
+ "search.query_current",
+ "search.query_time",
+ "search.query_total",
+ "search.scroll_current",
+ "search.scroll_time",
+ "search.scroll_total",
+ "segments.count",
+ "segments.fixed_bitset_memory",
+ "segments.index_writer_memory",
+ "segments.memory",
+ "segments.version_map_memory",
+ "seq_no.global_checkpoint",
+ "seq_no.local_checkpoint",
+ "seq_no.max",
+ "shard",
+ "state",
+ "store",
+ "suggest.current",
+ "suggest.time",
+ "suggest.total",
+ "sync_id",
+ "unassigned.at",
+ "unassigned.details",
+ "unassigned.for",
+ "unassigned.reason",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "completion.size",
+ "dataset.size",
+ "dense_vector.value_count",
+ "docs",
+ "dsparse_vector.value_count",
+ "fielddata.evictions",
+ "fielddata.memory_size",
+ "flush.total",
+ "flush.total_time",
+ "get.current",
+ "get.exists_time",
+ "get.exists_total",
+ "get.missing_time",
+ "get.missing_total",
+ "get.time",
+ "get.total",
+ "id",
+ "index",
+ "indexing.delete_current",
+ "indexing.delete_time",
+ "indexing.delete_total",
+ "indexing.index_current",
+ "indexing.index_failed",
+ "indexing.index_failed_due_to_version_conflict",
+ "indexing.index_time",
+ "indexing.index_total",
+ "ip",
+ "merges.current",
+ "merges.current_docs",
+ "merges.current_size",
+ "merges.total",
+ "merges.total_docs",
+ "merges.total_size",
+ "merges.total_time",
+ "node",
+ "prirep",
+ "query_cache.evictions",
+ "query_cache.memory_size",
+ "recoverysource.type",
+ "refresh.time",
+ "refresh.total",
+ "search.fetch_current",
+ "search.fetch_time",
+ "search.fetch_total",
+ "search.open_contexts",
+ "search.query_current",
+ "search.query_time",
+ "search.query_total",
+ "search.scroll_current",
+ "search.scroll_time",
+ "search.scroll_total",
+ "segments.count",
+ "segments.fixed_bitset_memory",
+ "segments.index_writer_memory",
+ "segments.memory",
+ "segments.version_map_memory",
+ "seq_no.global_checkpoint",
+ "seq_no.local_checkpoint",
+ "seq_no.max",
+ "shard",
+ "state",
+ "store",
+ "suggest.current",
+ "suggest.time",
+ "suggest.total",
+ "sync_id",
+ "unassigned.at",
+ "unassigned.details",
+ "unassigned.for",
+ "unassigned.reason",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns information about the shards in a cluster. For data streams, the API
- returns information about the backing indices. IMPORTANT: cat APIs are only intended
- for human consumption using the command line or Kibana console. They are not
- intended for use by applications.
+ .. raw:: html
+
+ Get shard information.
+ Get information about the shards in a cluster.
+ For data streams, the API returns information about the backing indices.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
+
- ``_
+ ``_
:param index: A 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`.
- :param bytes: The unit used to display byte values.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: List of columns to appear in the response. Supports simple wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
+ :param master_timeout: The period to wait for a connection to the master node.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -2407,14 +3284,14 @@ async def shards(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
if master_timeout is not None:
__query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -2432,46 +3309,105 @@ async def snapshots(
self,
*,
repository: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "duration",
+ "end_epoch",
+ "end_time",
+ "failed_shards",
+ "id",
+ "indices",
+ "reason",
+ "repository",
+ "start_epoch",
+ "start_time",
+ "status",
+ "successful_shards",
+ "total_shards",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "duration",
+ "end_epoch",
+ "end_time",
+ "failed_shards",
+ "id",
+ "indices",
+ "reason",
+ "repository",
+ "start_epoch",
+ "start_time",
+ "status",
+ "successful_shards",
+ "total_shards",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
ignore_unavailable: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns information about the snapshots stored in one or more repositories. A
- snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT:
- cat APIs are only intended for human consumption using the command line or Kibana
- console. They are not intended for use by applications. For application consumption,
- use the get snapshot API.
+ .. raw:: html
- ``_
+ Get snapshot information.
+ Get information about the snapshots stored in one or more repositories.
+ A snapshot is a backup of an index or running Elasticsearch cluster.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API.
+
+
+ ``_
:param repository: A comma-separated list of snapshot repositories used to limit
the request. Accepts wildcard expressions. `_all` returns all repositories.
If any repository fails during the request, Elasticsearch returns an error.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param ignore_unavailable: If `true`, the response does not include information
from unavailable snapshots.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
:param master_timeout: Period to wait for a connection to the master node.
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -2482,6 +3418,8 @@ async def snapshots(
__path_parts = {}
__path = "/_cat/snapshots"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -2496,14 +3434,14 @@ async def snapshots(
__query["human"] = human
if ignore_unavailable is not None:
__query["ignore_unavailable"] = ignore_unavailable
- if local is not None:
- __query["local"] = local
if master_timeout is not None:
__query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -2517,10 +3455,14 @@ async def snapshots(
)
@_rewrite_parameters()
+ @_stability_warning(Stability.EXPERIMENTAL)
async def tasks(
self,
*,
actions: t.Optional[t.Sequence[str]] = None,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
detailed: t.Optional[bool] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
@@ -2528,23 +3470,36 @@ async def tasks(
h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
- node_id: t.Optional[t.Sequence[str]] = None,
+ nodes: t.Optional[t.Sequence[str]] = None,
parent_task_id: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
+ timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
v: t.Optional[bool] = None,
+ wait_for_completion: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns information about tasks currently executing in the cluster. IMPORTANT:
- cat APIs are only intended for human consumption using the command line or Kibana
- console. They are not intended for use by applications. For application consumption,
- use the task management API.
+ .. raw:: html
+
+ Get task information.
+ Get information about tasks currently running in the cluster.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the task management API.
- ``_
+
+ ``_
:param actions: The task action names, which are used to limit the response.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param detailed: If `true`, the response includes detailed information about
shard recoveries.
:param format: Specifies the format to return the columnar data in, can be set
@@ -2552,24 +3507,31 @@ async def tasks(
:param h: List of columns to appear in the response. Supports simple wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
- :param node_id: Unique node identifiers, which are used to limit the response.
+ :param nodes: Unique node identifiers, which are used to limit the response.
:param parent_task_id: The parent task identifier, which is used to limit the
response.
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
+ :param timeout: Period to wait for a response. If no response is received before
+ the timeout expires, the request fails and returns an error.
:param v: When set to `true` will enable verbose output.
+ :param wait_for_completion: If `true`, the request blocks until the task has
+ completed.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_cat/tasks"
__query: t.Dict[str, t.Any] = {}
if actions is not None:
__query["actions"] = actions
+ if bytes is not None:
+ __query["bytes"] = bytes
if detailed is not None:
__query["detailed"] = detailed
if error_trace is not None:
@@ -2584,20 +3546,22 @@ async def tasks(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
- if node_id is not None:
- __query["node_id"] = node_id
+ if nodes is not None:
+ __query["nodes"] = nodes
if parent_task_id is not None:
__query["parent_task_id"] = parent_task_id
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
+ if timeout is not None:
+ __query["timeout"] = timeout
if v is not None:
__query["v"] = v
+ if wait_for_completion is not None:
+ __query["wait_for_completion"] = wait_for_completion
__headers = {"accept": "text/plain,application/json"}
return await self.perform_request( # type: ignore[return-value]
"GET",
@@ -2613,6 +3577,9 @@ async def templates(
self,
*,
name: t.Optional[str] = None,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
@@ -2623,19 +3590,32 @@ async def templates(
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ time: t.Optional[
+ t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]]
+ ] = None,
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns information about index templates in a cluster. You can use index templates
- to apply index settings and field mappings to new indices at creation. IMPORTANT:
- cat APIs are only intended for human consumption using the command line or Kibana
- console. They are not intended for use by applications. For application consumption,
- use the get index template API.
+ .. raw:: html
+
+ Get index template information.
+ Get information about the index templates in a cluster.
+ You can use index templates to apply index settings and field mappings to new indices at creation.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get index template API.
+
- ``_
+ ``_
:param name: The name of the template to return. Accepts wildcard expressions.
If omitted, all templates are returned.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: List of columns to appear in the response. Supports simple wildcards.
@@ -2649,6 +3629,12 @@ async def templates(
:param s: List of columns that determine how the table should be sorted. Sorting
defaults to ascending and can be changed by setting `:asc` or `:desc` as
a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -2659,6 +3645,8 @@ async def templates(
__path_parts = {}
__path = "/_cat/templates"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -2679,6 +3667,8 @@ async def templates(
__query["pretty"] = pretty
if s is not None:
__query["s"] = s
+ if time is not None:
+ __query["time"] = time
if v is not None:
__query["v"] = v
__headers = {"accept": "text/plain,application/json"}
@@ -2696,10 +3686,68 @@ async def thread_pool(
self,
*,
thread_pool_patterns: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "active",
+ "completed",
+ "core",
+ "ephemeral_id",
+ "host",
+ "ip",
+ "keep_alive",
+ "largest",
+ "max",
+ "name",
+ "node_id",
+ "node_name",
+ "pid",
+ "pool_size",
+ "port",
+ "queue",
+ "queue_size",
+ "rejected",
+ "size",
+ "type",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "active",
+ "completed",
+ "core",
+ "ephemeral_id",
+ "host",
+ "ip",
+ "keep_alive",
+ "largest",
+ "max",
+ "name",
+ "node_id",
+ "node_name",
+ "pid",
+ "pool_size",
+ "port",
+ "queue",
+ "queue_size",
+ "rejected",
+ "size",
+ "type",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
@@ -2712,16 +3760,26 @@ async def thread_pool(
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Returns thread pool statistics for each node in a cluster. Returned information
- includes all built-in thread pools and custom thread pools. IMPORTANT: cat APIs
- are only intended for human consumption using the command line or Kibana console.
- They are not intended for use by applications. For application consumption, use
- the nodes info API.
+ .. raw:: html
+
+ Get thread pool statistics.
+ Get thread pool statistics for each node in a cluster.
+ Returned information includes all built-in thread pools and custom thread pools.
+ IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
+
- ``_
+ ``_
:param thread_pool_patterns: A comma-separated list of thread pool names used
to limit the request. Accepts wildcard expressions.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param h: List of columns to appear in the response. Supports simple wildcards.
@@ -2731,11 +3789,16 @@ async def thread_pool(
the local cluster state. If `false` the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
- :param time: The unit used to display time values.
+ :param master_timeout: The period to wait for a connection to the master node.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -2746,6 +3809,8 @@ async def thread_pool(
__path_parts = {}
__path = "/_cat/thread_pool"
__query: t.Dict[str, t.Any] = {}
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -2788,6 +3853,9 @@ async def transforms(
*,
transform_id: t.Optional[str] = None,
allow_no_match: t.Optional[bool] = None,
+ bytes: t.Optional[
+ t.Union[str, t.Literal["b", "gb", "kb", "mb", "pb", "tb"]]
+ ] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
@@ -2876,8 +3944,6 @@ async def transforms(
] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
- local: t.Optional[bool] = None,
- master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
s: t.Optional[
t.Union[
@@ -2968,12 +4034,16 @@ async def transforms(
v: t.Optional[bool] = None,
) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]:
"""
- Get transforms. Returns configuration and usage information about transforms.
- CAT APIs are only intended for human consumption using the Kibana console or
- command line. They are not intended for use by applications. For application
- consumption, use the get transform statistics API.
+ .. raw:: html
+
+ Get transform information.
+ Get configuration and usage information about transforms.
+ CAT APIs are only intended for human consumption using the Kibana
+ console or command line. They are not intended for use by applications. For
+ application consumption, use the get transform statistics API.
- ``_
+
+ ``_
:param transform_id: A transform identifier or a wildcard expression. If you
do not specify one of these options, the API returns information for all
@@ -2985,21 +4055,29 @@ async def transforms(
array when there are no matches and the subset of results when there are
partial matches. If `false`, the request returns a 404 status code when there
are no matches or only partial matches.
+ :param bytes: Sets the units for columns that contain a byte-size value. Note
+ that byte-size value units work in terms of powers of 1024. For instance
+ `1kb` means 1024 bytes, not 1000 bytes. If omitted, byte-size values are
+ rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the
+ numeric value of the column is as small as possible whilst still being at
+ least `1.0`. If given, byte-size values are rendered as an integer with no
+ suffix, representing the value of the column in the chosen unit. Values that
+ are not an exact multiple of the chosen unit are rounded down.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param from_: Skips the specified number of transforms.
:param h: Comma-separated list of column names to display.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param local: If `true`, the request computes the list of selected nodes from
- the local cluster state. If `false` the list of selected nodes are computed
- from the cluster state of the master node. In both cases the coordinating
- node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
:param s: Comma-separated list of column names or column aliases used to sort
the response.
:param size: The maximum number of transforms to obtain.
- :param time: The unit used to display time values.
+ :param time: Sets the units for columns that contain a time duration. If omitted,
+ time duration values are rendered with a suffix such as `ms`, `s`, `m` or
+ `h`, chosen such that the numeric value of the column is as small as possible
+ whilst still being at least `1.0`. If given, time duration values are rendered
+ as an integer with no suffix. Values that are not an exact multiple of the
+ chosen unit are rounded down.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -3012,6 +4090,8 @@ async def transforms(
__query: t.Dict[str, t.Any] = {}
if allow_no_match is not None:
__query["allow_no_match"] = allow_no_match
+ if bytes is not None:
+ __query["bytes"] = bytes
if error_trace is not None:
__query["error_trace"] = error_trace
if filter_path is not None:
@@ -3026,10 +4106,6 @@ async def transforms(
__query["help"] = help
if human is not None:
__query["human"] = human
- if local is not None:
- __query["local"] = local
- if master_timeout is not None:
- __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if s is not None:
diff --git a/elasticsearch/_async/client/ccr.py b/elasticsearch/_async/client/ccr.py
index c4f7b0c05..eeef7c7ab 100644
--- a/elasticsearch/_async/client/ccr.py
+++ b/elasticsearch/_async/client/ccr.py
@@ -33,14 +33,23 @@ async def delete_auto_follow_pattern(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
+ master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Deletes auto-follow patterns.
+ .. raw:: html
- ``_
+ Delete auto-follow patterns.
+ Delete a collection of cross-cluster replication auto-follow patterns.
- :param name: The name of the auto follow pattern.
+
+ ``_
+
+ :param name: The auto-follow pattern collection to delete.
+ :param master_timeout: The period to wait for a connection to the master node.
+ If the master node is not available before the timeout expires, the request
+ fails and returns an error. It can also be set to `-1` to indicate that the
+ request should never timeout.
"""
if name in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'name'")
@@ -53,6 +62,8 @@ async def delete_auto_follow_pattern(
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
+ if master_timeout is not None:
+ __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
__headers = {"accept": "application/json"}
@@ -68,6 +79,8 @@ async def delete_auto_follow_pattern(
@_rewrite_parameters(
body_fields=(
"leader_index",
+ "remote_cluster",
+ "data_stream_name",
"max_outstanding_read_requests",
"max_outstanding_write_requests",
"max_read_request_operation_count",
@@ -78,59 +91,93 @@ async def delete_auto_follow_pattern(
"max_write_request_operation_count",
"max_write_request_size",
"read_poll_timeout",
- "remote_cluster",
+ "settings",
),
)
async def follow(
self,
*,
index: str,
+ leader_index: t.Optional[str] = None,
+ remote_cluster: t.Optional[str] = None,
+ data_stream_name: t.Optional[str] = None,
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
- leader_index: t.Optional[str] = None,
+ master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
max_outstanding_read_requests: t.Optional[int] = None,
max_outstanding_write_requests: t.Optional[int] = None,
max_read_request_operation_count: t.Optional[int] = None,
- max_read_request_size: t.Optional[str] = None,
+ max_read_request_size: t.Optional[t.Union[int, str]] = None,
max_retry_delay: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
max_write_buffer_count: t.Optional[int] = None,
- max_write_buffer_size: t.Optional[str] = None,
+ max_write_buffer_size: t.Optional[t.Union[int, str]] = None,
max_write_request_operation_count: t.Optional[int] = None,
- max_write_request_size: t.Optional[str] = None,
+ max_write_request_size: t.Optional[t.Union[int, str]] = None,
pretty: t.Optional[bool] = None,
read_poll_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
- remote_cluster: t.Optional[str] = None,
+ settings: t.Optional[t.Mapping[str, t.Any]] = None,
wait_for_active_shards: t.Optional[
t.Union[int, t.Union[str, t.Literal["all", "index-setting"]]]
] = None,
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Creates a new follower index configured to follow the referenced leader index.
+ .. raw:: html
- ``_
+ Create a follower.
+ Create a cross-cluster replication follower index that follows a specific leader index.
+ When the API returns, the follower index exists and cross-cluster replication starts replicating operations from the leader index to the follower index.
- :param index: The name of the follower index
- :param leader_index:
- :param max_outstanding_read_requests:
- :param max_outstanding_write_requests:
- :param max_read_request_operation_count:
- :param max_read_request_size:
- :param max_retry_delay:
- :param max_write_buffer_count:
- :param max_write_buffer_size:
- :param max_write_request_operation_count:
- :param max_write_request_size:
- :param read_poll_timeout:
- :param remote_cluster:
- :param wait_for_active_shards: Sets the number of shard copies that must be active
- before returning. Defaults to 0. Set to `all` for all shard copies, otherwise
- set to any non-negative value less than or equal to the total number of copies
- for the shard (number of replicas + 1)
+
+ ``_
+
+ :param index: The name of the follower index.
+ :param leader_index: The name of the index in the leader cluster to follow.
+ :param remote_cluster: The remote cluster containing the leader index.
+ :param data_stream_name: If the leader index is part of a data stream, the name
+ to which the local data stream for the followed index should be renamed.
+ :param master_timeout: Period to wait for a connection to the master node.
+ :param max_outstanding_read_requests: The maximum number of outstanding reads
+ requests from the remote cluster.
+ :param max_outstanding_write_requests: The maximum number of outstanding write
+ requests on the follower.
+ :param max_read_request_operation_count: The maximum number of operations to
+ pull per read from the remote cluster.
+ :param max_read_request_size: The maximum size in bytes of per read of a batch
+ of operations pulled from the remote cluster.
+ :param max_retry_delay: The maximum time to wait before retrying an operation
+ that failed exceptionally. An exponential backoff strategy is employed when
+ retrying.
+ :param max_write_buffer_count: The maximum number of operations that can be queued
+ for writing. When this limit is reached, reads from the remote cluster will
+ be deferred until the number of queued operations goes below the limit.
+ :param max_write_buffer_size: The maximum total bytes of operations that can
+ be queued for writing. When this limit is reached, reads from the remote
+ cluster will be deferred until the total bytes of queued operations goes
+ below the limit.
+ :param max_write_request_operation_count: The maximum number of operations per
+ bulk write request executed on the follower.
+ :param max_write_request_size: The maximum total bytes of operations per bulk
+ write request executed on the follower.
+ :param read_poll_timeout: The maximum time to wait for new operations on the
+ remote cluster when the follower index is synchronized with the leader index.
+ When the timeout has elapsed, the poll for operations will return to the
+ follower so that it can update some statistics. Then the follower will immediately
+ attempt to read from the leader again.
+ :param settings: Settings to override from the leader index.
+ :param wait_for_active_shards: Specifies the number of shards to wait on being
+ active before responding. This defaults to waiting on none of the shards
+ to be active. A shard must be restored from the leader index before being
+ active. Restoring a follower shard requires transferring all the remote Lucene
+ segment files to the follower index.
"""
if index in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'index'")
+ if leader_index is None and body is None:
+ raise ValueError("Empty value passed for parameter 'leader_index'")
+ if remote_cluster is None and body is None:
+ raise ValueError("Empty value passed for parameter 'remote_cluster'")
__path_parts: t.Dict[str, str] = {"index": _quote(index)}
__path = f'/{__path_parts["index"]}/_ccr/follow'
__query: t.Dict[str, t.Any] = {}
@@ -141,6 +188,8 @@ async def follow(
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
+ if master_timeout is not None:
+ __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
if wait_for_active_shards is not None:
@@ -148,6 +197,10 @@ async def follow(
if not __body:
if leader_index is not None:
__body["leader_index"] = leader_index
+ if remote_cluster is not None:
+ __body["remote_cluster"] = remote_cluster
+ if data_stream_name is not None:
+ __body["data_stream_name"] = data_stream_name
if max_outstanding_read_requests is not None:
__body["max_outstanding_read_requests"] = max_outstanding_read_requests
if max_outstanding_write_requests is not None:
@@ -174,8 +227,8 @@ async def follow(
__body["max_write_request_size"] = max_write_request_size
if read_poll_timeout is not None:
__body["read_poll_timeout"] = read_poll_timeout
- if remote_cluster is not None:
- __body["remote_cluster"] = remote_cluster
+ if settings is not None:
+ __body["settings"] = settings
__headers = {"accept": "application/json", "content-type": "application/json"}
return await self.perform_request( # type: ignore[return-value]
"PUT",
@@ -195,16 +248,24 @@ async def follow_info(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
+ master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Retrieves information about all follower indices, including parameters and status
- for each follower index
+ .. raw:: html
+
+ Get follower information.
+ Get information about all cross-cluster replication follower indices.
+ For example, the results include follower index names, leader index names, replication options, and whether the follower indices are active or paused.
+
- ``_
+ ``_
- :param index: A comma-separated list of index patterns; use `_all` to perform
- the operation on all indices
+ :param index: A comma-delimited list of follower index patterns.
+ :param master_timeout: The period to wait for a connection to the master node.
+ If the master node is not available before the timeout expires, the request
+ fails and returns an error. It can also be set to `-1` to indicate that the
+ request should never timeout.
"""
if index in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'index'")
@@ -217,6 +278,8 @@ async def follow_info(
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
+ if master_timeout is not None:
+ __query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
__headers = {"accept": "application/json"}
@@ -238,15 +301,21 @@ async def follow_stats(
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
pretty: t.Optional[bool] = None,
+ timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Retrieves follower stats. return shard-level stats about the following tasks
- associated with each shard for the specified indices.
+ .. raw:: html
- ``_
+ Get follower stats.
+ Get cross-cluster replication follower stats.
+ The API returns shard-level stats about the "following tasks" associated with each shard for the specified indices.
- :param index: A comma-separated list of index patterns; use `_all` to perform
- the operation on all indices
+
+ ``_
+
+ :param index: A comma-delimited list of index patterns.
+ :param timeout: The period to wait for a response. If no response is received
+ before the timeout expires, the request fails and returns an error.
"""
if index in SKIP_IN_PATH:
raise ValueError("Empty value passed for parameter 'index'")
@@ -261,6 +330,8 @@ async def follow_stats(
__query["human"] = human
if pretty is not None:
__query["pretty"] = pretty
+ if timeout is not None:
+ __query["timeout"] = timeout
__headers = {"accept": "application/json"}
return await self.perform_request( # type: ignore[return-value]
"GET",
@@ -291,12 +362,25 @@ async def forget_follower(
human: t.Optional[bool] = None,
leader_remote_cluster: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
+ timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
- Removes the follower retention leases from the leader.
+ .. raw:: html
+
+ Forget a follower.
+ Remove the cross-cluster replication follower retention leases from the leader.
+ A following index takes out retention leases on its leader index.
+ These leases are used to increase the likelihood that the shards of the leader index retain the history of operations that the shards of the following index need to run replication.
+ When a follower index is converted to a regular index by the unfollow API (either by directly calling the API or by index lifecycle management tasks), these leases are removed.
+ However, removal of the leases can fail, for example when the remote cluster containing the leader index is unavailable.
+ While the leases will eventually expire on their own, their extended existence can cause the leader index to hold more history than necessary and prevent index lifecycle management from performing some operations on the leader index.
+ This API exists to enable manually removing the leases when the unfollow API is unable to do so.
+ NOTE: This API does not stop replication by a following index. If you use this API with a follower index that is still actively following, the following index will add back retention leases on the leader.
+ The only purpose of this API is to handle the case of failure to remove the following retention leases after the unfollow API is invoked.
- ``_
+
+ `
+ 