diff --git a/.buildkite/Dockerfile b/.buildkite/Dockerfile index a68ad997d..2c6bfbe6c 100644 --- a/.buildkite/Dockerfile +++ b/.buildkite/Dockerfile @@ -1,4 +1,4 @@ -ARG PYTHON_VERSION=3.13 +ARG PYTHON_VERSION=3.14 FROM python:${PYTHON_VERSION} # Default UID/GID to 1000 diff --git a/.buildkite/functions/imports.sh b/.buildkite/functions/imports.sh index e732ebba0..ad7a20269 100755 --- a/.buildkite/functions/imports.sh +++ b/.buildkite/functions/imports.sh @@ -43,7 +43,7 @@ if [[ -z $es_node_name ]]; then fi - export script_path=$(dirname $(realpath -s $0)) + export script_path=$(dirname $(realpath $0)) source $script_path/functions/cleanup.sh source $script_path/functions/wait-for-container.sh trap "cleanup_trap ${network_name}" EXIT diff --git a/.buildkite/pipeline.yml b/.buildkite/pipeline.yml index ac7c6b60a..16641c858 100644 --- a/.buildkite/pipeline.yml +++ b/.buildkite/pipeline.yml @@ -5,7 +5,7 @@ steps: env: PYTHON_VERSION: "{{ matrix.python }}" TEST_SUITE: "platinum" - STACK_VERSION: "9.1.0-SNAPSHOT" + STACK_VERSION: "9.1.9-SNAPSHOT" PYTHON_CONNECTION_CLASS: "{{ matrix.connection }}" NOX_SESSION: "{{ matrix.nox_session }}" matrix: @@ -16,6 +16,7 @@ steps: - "3.11" - "3.12" - "3.13" + - "3.14" connection: - "urllib3" - "requests" @@ -23,11 +24,11 @@ steps: - "test" adjustments: - with: - python: "3.9" + python: "3.10" connection: "urllib3" nox_session: "test_otel" - with: - python: "3.13" + python: "3.14" connection: "urllib3" nox_session: "test_otel" command: ./.buildkite/run-tests diff --git a/.buildkite/run-elasticsearch.sh b/.buildkite/run-elasticsearch.sh index 2f73ea8d1..2dda5b4af 100755 --- a/.buildkite/run-elasticsearch.sh +++ b/.buildkite/run-elasticsearch.sh @@ -21,7 +21,7 @@ # - Moved ELASTIC_PASSWORD and xpack.security.enabled to the base arguments for "Security On by default" # - Use https only when TEST_SUITE is "platinum", when "free" use http -script_path=$(dirname $(realpath -s $0)) +script_path=$(dirname $(realpath $0)) source $script_path/functions/imports.sh set -euo pipefail diff --git a/.buildkite/run-repository.sh b/.buildkite/run-repository.sh index ce9344e8d..04d4440f0 100755 --- a/.buildkite/run-repository.sh +++ b/.buildkite/run-repository.sh @@ -21,6 +21,7 @@ echo -e "\033[34;1mINFO:\033[0m TEST_SUITE ${TEST_SUITE}\033[0m" echo -e "\033[34;1mINFO:\033[0m NOX_SESSION ${NOX_SESSION}\033[0m" echo -e "\033[34;1mINFO:\033[0m PYTHON_VERSION ${PYTHON_VERSION}\033[0m" echo -e "\033[34;1mINFO:\033[0m PYTHON_CONNECTION_CLASS ${PYTHON_CONNECTION_CLASS}\033[0m" +echo -e "\033[34;1mINFO:\033[0m ES_YAML_TESTS_BRANCH ${ES_YAML_TESTS_BRANCH}\033[0m" echo -e "\033[1m>>>>> Build [elastic/elasticsearch-py container] >>>>>>>>>>>>>>>>>>>>>>>>>>>>>\033[0m" @@ -42,6 +43,7 @@ docker run \ --env "ELASTICSEARCH_URL=${elasticsearch_url}" \ --env "TEST_SUITE=${TEST_SUITE}" \ --env "PYTHON_CONNECTION_CLASS=${PYTHON_CONNECTION_CLASS}" \ + --env "ES_YAML_TESTS_BRANCH=${ES_YAML_TESTS_BRANCH}" \ --env "TEST_TYPE=server" \ --env "FORCE_COLOR=1" \ --name elasticsearch-py \ diff --git a/.buildkite/run-tests b/.buildkite/run-tests index 5d6b38039..d2403c3a9 100755 --- a/.buildkite/run-tests +++ b/.buildkite/run-tests @@ -7,10 +7,14 @@ # Default environment variables export STACK_VERSION="${STACK_VERSION:=8.0.0-SNAPSHOT}" export TEST_SUITE="${TEST_SUITE:=platinum}" -export PYTHON_VERSION="${PYTHON_VERSION:=3.13}" +export PYTHON_VERSION="${PYTHON_VERSION:=3.14}" export PYTHON_CONNECTION_CLASS="${PYTHON_CONNECTION_CLASS:=urllib3}" +export ES_YAML_TESTS_BRANCH="${BUILDKITE_PULL_REQUEST_BASE_BRANCH}" +if [[ ! -n "$ES_YAML_TESTS_BRANCH" ]]; then + export ES_YAML_TESTS_BRANCH="${BUILDKITE_BRANCH}" +fi -script_path=$(dirname $(realpath -s $0)) +script_path=$(dirname $(realpath $0)) source $script_path/functions/imports.sh set -euo pipefail diff --git a/.github/make.sh b/.github/make.sh index 79d785957..4a363e524 100755 --- a/.github/make.sh +++ b/.github/make.sh @@ -11,12 +11,13 @@ # # Targets: # --------------------------- -# assemble : build client artefacts with version -# bump : bump client internals to version -# codegen : generate endpoints -# docsgen : generate documentation -# examplegen : generate the doc examples -# clean : clean workspace +# assemble : build client artefacts with version +# bump : bump client internals to version +# bumpmatrix : bump stack version in test matrix to version +# codegen : generate endpoints +# docsgen : generate documentation +# examplegen : generate the doc examples +# clean : clean workspace # # ------------------------------------------------------- # @@ -24,7 +25,7 @@ # Bootstrap # ------------------------------------------------------- # -script_path=$(dirname "$(realpath -s "$0")") +script_path=$(dirname "$(realpath "$0")") repo=$(realpath "$script_path/../") # shellcheck disable=SC1090 @@ -100,6 +101,15 @@ case $CMD in # VERSION is BRANCH here for now TASK_ARGS=("$VERSION") ;; + bumpmatrix) + if [ -v $VERSION ]; then + echo -e "\033[31;1mTARGET: bumpmatrix -> missing version parameter\033[0m" + exit 1 + fi + echo -e "\033[36;1mTARGET: bump stack in test matrix to version $VERSION\033[0m" + TASK=bumpmatrix + TASK_ARGS=("$VERSION") + ;; *) echo -e "\nUsage:\n\t $CMD is not supported right now\n" exit 1 @@ -160,6 +170,13 @@ if [[ "$CMD" == "bump" ]]; then exit 0 fi +if [[ "$CMD" == "bumpmatrix" ]]; then + TEST_CONFIG_FILE=.buildkite/pipeline.yml + sed -E -i.bak 's/[0-9]+\.[0-9]+\.[0-9]+-SNAPSHOT/'$VERSION'/g' $TEST_CONFIG_FILE + rm ${TEST_CONFIG_FILE}.bak + exit 0 +fi + if [[ "$CMD" == "codegen" ]]; then docker run \ --rm -v $repo:/code/elasticsearch-py \ diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0bc43d985..20663c601 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,7 +8,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout Repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Set up Python 3.x uses: actions/setup-python@v5 with: @@ -23,7 +23,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout Repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Set up Python 3.x uses: actions/setup-python@v5 with: @@ -38,7 +38,7 @@ jobs: strategy: fail-fast: false matrix: - python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"] + python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"] nox-session: [""] runs-on: ["ubuntu-latest"] @@ -47,7 +47,7 @@ jobs: continue-on-error: false steps: - name: Checkout Repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Set Up Python - ${{ matrix.python-version }} uses: actions/setup-python@v5 with: diff --git a/docs/reference/connecting.md b/docs/reference/connecting.md index 27f7fecbc..56b3aaee7 100644 --- a/docs/reference/connecting.md +++ b/docs/reference/connecting.md @@ -277,13 +277,6 @@ client = Elasticsearch( ``` -## Enabling the Compatibility Mode [compatibility-mode] - -The {{es}} server version 8.0 is introducing a new compatibility mode that allows you a smoother upgrade experience from 7 to 8. In a nutshell, you can use the latest 7.x Python {{es}} {{es}} client with an 8.x {{es}} server, giving more room to coordinate the upgrade of your codebase to the next major version. - -If you want to leverage this functionality, please make sure that you are using the latest 7.x Python {{es}} client and set the environment variable `ELASTIC_CLIENT_APIVERSIONING` to `true`. The client is handling the rest internally. For every 8.0 and beyond Python {{es}} client, you’re all set! The compatibility mode is enabled by default. - - ## Using the Client in a Function-as-a-Service Environment [connecting-faas] This section illustrates the best practices for leveraging the {{es}} client in a Function-as-a-Service (FaaS) environment. diff --git a/docs/reference/dsl_how_to_guides.md b/docs/reference/dsl_how_to_guides.md index ce128528a..d5a3dd74e 100644 --- a/docs/reference/dsl_how_to_guides.md +++ b/docs/reference/dsl_how_to_guides.md @@ -917,7 +917,7 @@ first = Post.get(id=42) first.update(published=True, published_by='me') ``` -In case you wish to use a `painless` script to perform the update you can pass in the script string as `script` or the `id` of a [stored script](docs-content://explore-analyze/scripting/modules-scripting-using.md#script-stored-scripts) via `script_id`. All additional keyword arguments to the `update` method will then be passed in as parameters of the script. The document will not be updated in place. +In case you wish to use a `painless` script to perform the update you can pass in the script string as `script` or the `id` of a [stored script](docs-content://explore-analyze/scripting/modules-scripting-store-and-retrieve.md) via `script_id`. All additional keyword arguments to the `update` method will then be passed in as parameters of the script. The document will not be updated in place. ```python # retrieve the document @@ -1425,6 +1425,127 @@ print(response.took) If you want to inspect the contents of the `response` objects, just use its `to_dict` method to get access to the raw data for pretty printing. +## ES|QL Queries + +When working with `Document` classes, you can use the ES|QL query language to retrieve documents. For this you can use the `esql_from()` and `esql_execute()` methods available to all sub-classes of `Document`. + +Consider the following `Employee` document definition: + +```python +from elasticsearch.dsl import Document, InnerDoc, M + +class Address(InnerDoc): + address: M[str] + city: M[str] + zip_code: M[str] + +class Employee(Document): + emp_no: M[int] + first_name: M[str] + last_name: M[str] + height: M[float] + still_hired: M[bool] + address: M[Address] + + class Index: + name = 'employees' +``` + +The `esql_from()` method creates a base ES|QL query for the index associated with the document class. The following example creates a base query for the `Employee` class: + +```python +query = Employee.esql_from() +``` + +This query includes a `FROM` command with the index name, and a `KEEP` command that retrieves all the document attributes. + +To execute this query and receive the results, you can pass the query to the `esql_execute()` method: + +```python +for emp in Employee.esql_execute(query): + print(f"{emp.name} from {emp.address.city} is {emp.height:.2f}m tall") +``` + +In this example, the `esql_execute()` class method runs the query and returns all the documents in the index, up to the maximum of 1000 results allowed by ES|QL. Here is a possible output from this example: + +``` +Kevin Macias from North Robert is 1.60m tall +Drew Harris from Boltonshire is 1.68m tall +Julie Williams from Maddoxshire is 1.99m tall +Christopher Jones from Stevenbury is 1.98m tall +Anthony Lopez from Port Sarahtown is 2.42m tall +Tricia Stone from North Sueshire is 2.39m tall +Katherine Ramirez from Kimberlyton is 1.83m tall +... +``` + +To search for specific documents you can extend the base query with additional ES|QL commands that narrow the search criteria. The next example searches for documents that include only employees that are taller than 2 meters, sorted by their last name. It also limits the results to 4 people: + +```python +query = ( + Employee.esql_from() + .where(Employee.height > 2) + .sort(Employee.last_name) + .limit(4) +) +``` + +When running this query with the same for-loop shown above, possible results would be: + +``` +Michael Adkins from North Stacey is 2.48m tall +Kimberly Allen from Toddside is 2.24m tall +Crystal Austin from East Michaelchester is 2.30m tall +Rebecca Berger from Lake Adrianside is 2.40m tall +``` + +### Additional fields + +ES|QL provides a few ways to add new fields to a query, for example through the `EVAL` command. The following example shows a query that adds an evaluated field: + +```python +from elasticsearch.esql import E, functions + +query = ( + Employee.esql_from() + .eval(height_cm=functions.round(Employee.height * 100)) + .where(E("height_cm") >= 200) + .sort(Employee.last_name) + .limit(10) +) +``` + +In this example we are adding the height in centimeters to the query, calculated from the `height` document field, which is in meters. The `height_cm` calculated field is available to use in other query clauses, and in particular is referenced in `where()` in this example. Note how the new field is given as `E("height_cm")` in this clause. The `E()` wrapper tells the query builder that the argument is an ES|QL field name and not a string literal. This is done automatically for document fields that are given as class attributes, such as `Employee.height` in the `eval()`. The `E()` wrapper is only needed for fields that are not in the document. + +By default, the `esql_execute()` method returns only document instances. To receive any additional fields that are not part of the document in the query results, the `return_additional=True` argument can be passed to it, and then the results are returned as tuples with the document as first element, and a dictionary with the additional fields as second element: + +```python +for emp, additional in Employee.esql_execute(query, return_additional=True): + print(emp.name, additional) +``` + +Example output from the query given above: + +``` +Michael Adkins {'height_cm': 248.0} +Kimberly Allen {'height_cm': 224.0} +Crystal Austin {'height_cm': 230.0} +Rebecca Berger {'height_cm': 240.0} +Katherine Blake {'height_cm': 214.0} +Edward Butler {'height_cm': 246.0} +Steven Carlson {'height_cm': 242.0} +Mark Carter {'height_cm': 240.0} +Joseph Castillo {'height_cm': 229.0} +Alexander Cohen {'height_cm': 245.0} +``` + +### Missing fields + +The base query returned by the `esql_from()` method includes a `KEEP` command with the complete list of fields that are part of the document. If any subsequent clauses added to the query remove fields that are part of the document, then the `esql_execute()` method will raise an exception, because it will not be able construct complete document instances to return as results. + +To prevent errors, it is recommended that the `keep()` and `drop()` clauses are not used when working with `Document` instances. + +If a query has missing fields, it can be forced to execute without errors by passing the `ignore_missing_fields=True` argument to `esql_execute()`. When this option is used, returned documents will have any missing fields set to `None`. ## Using asyncio with Elasticsearch Python DSL [asyncio] diff --git a/docs/reference/dsl_tutorials.md b/docs/reference/dsl_tutorials.md index 77992587b..16224a13f 100644 --- a/docs/reference/dsl_tutorials.md +++ b/docs/reference/dsl_tutorials.md @@ -83,7 +83,7 @@ Let’s have a simple Python class representing an article in a blogging system: ```python from datetime import datetime -from elasticsearch.dsl import Document, Date, Integer, Keyword, Text, connections +from elasticsearch.dsl import Document, Date, Integer, Keyword, Text, connections, mapped_field # Define a default Elasticsearch client connections.create_connection(hosts="https://localhost:9200/") @@ -91,7 +91,7 @@ connections.create_connection(hosts="https://localhost:9200/") class Article(Document): title: str = mapped_field(Text(analyzer='snowball', fields={'raw': Keyword()})) body: str = mapped_field(Text(analyzer='snowball')) - tags: str = mapped_field(Keyword()) + tags: list[str] = mapped_field(Keyword()) published_from: datetime lines: int @@ -216,6 +216,20 @@ response = ubq.execute() As you can see, the `Update By Query` object provides many of the savings offered by the `Search` object, and additionally allows one to update the results of the search based on a script assigned in the same manner. +## ES|QL Queries + +The DSL module features an integration with the ES|QL query builder, consisting of two methods available in all `Document` sub-classes: `esql_from()` and `esql_execute()`. Using the `Article` document from above, we can search for up to ten articles that include `"world"` in their titles with the following ES|QL query: + +```python +from elasticsearch.esql import functions + +query = Article.esql_from().where(functions.match(Article.title, 'world')).limit(10) +for a in Article.esql_execute(query): + print(a.title) +``` + +Review the [ES|QL Query Builder section](esql-query-builder.md) to learn more about building ES|QL queries in Python. + ## Migration from the standard client [_migration_from_the_standard_client] You don’t have to port your entire application to get the benefits of the DSL module, you can start gradually by creating a `Search` object from your existing `dict`, modifying it using the API and serializing it back to a `dict`: diff --git a/docs/reference/esql-query-builder.md b/docs/reference/esql-query-builder.md index 1cdc0c5b3..7ef9a0960 100644 --- a/docs/reference/esql-query-builder.md +++ b/docs/reference/esql-query-builder.md @@ -20,7 +20,7 @@ The ES|QL Query Builder allows you to construct ES|QL queries using Python synta You can then see the assembled ES|QL query by printing the resulting query object: ```python ->>> query +>>> print(query) FROM employees | SORT emp_no | KEEP first_name, last_name, height @@ -28,12 +28,12 @@ FROM employees | LIMIT 3 ``` -To execute this query, you can cast it to a string and pass the string to the `client.esql.query()` endpoint: +To execute this query, you can pass it to the `client.esql.query()` endpoint: ```python >>> from elasticsearch import Elasticsearch >>> client = Elasticsearch(hosts=[os.environ['ELASTICSEARCH_URL']]) ->>> response = client.esql.query(query=str(query)) +>>> response = client.esql.query(query=query) ``` The response body contains a `columns` attribute with the list of columns included in the results, and a `values` attribute with the list of results for the query, each given as a list of column values. Here is a possible response body returned by the example query given above: @@ -203,6 +203,26 @@ query = ( ) ``` +### Preventing injection attacks + +ES|QL, like most query languages, is vulnerable to [code injection attacks](https://en.wikipedia.org/wiki/Code_injection) if untrusted data provided by users is added to a query. To eliminate this risk, ES|QL allows untrusted data to be given separately from the query as parameters. + +Continuing with the example above, let's assume that the application needs a `find_employee_by_name()` function that searches for the name given as an argument. If this argument is received by the application from users, then it is considered untrusted and should not be added to the query directly. Here is how to code the function in a secure manner: + +```python +def find_employee_by_name(name): + query = ( + ESQL.from_("employees") + .keep("first_name", "last_name", "height") + .where(E("first_name") == E("?")) + ) + return client.esql.query(query=query, params=[name]) +``` + +Here the part of the query in which the untrusted data needs to be inserted is replaced with a parameter, which in ES|QL is defined by the question mark. When using Python expressions, the parameter must be given as `E("?")` so that it is treated as an expression and not as a literal string. + +The list of values given in the `params` argument to the query endpoint are assigned in order to the parameters defined in the query. + ## Using ES|QL functions The ES|QL language includes a rich set of functions that can be used in expressions and conditionals. These can be included in expressions given as strings, as shown in the example below: @@ -235,6 +255,6 @@ query = ( ) ``` -Note that arguments passed to functions are assumed to be literals. When passing field names, it is necessary to wrap them with the `E()` helper function so that they are interpreted correctly. +Note that arguments passed to functions are assumed to be literals. When passing field names, parameters or other ES|QL expressions, it is necessary to wrap them with the `E()` helper function so that they are interpreted correctly. You can find the complete list of available functions in the Python client's [ES|QL API reference documentation](https://elasticsearch-py.readthedocs.io/en/stable/esql.html#module-elasticsearch.esql.functions). diff --git a/docs/reference/index.md b/docs/reference/index.md index 6046d7801..afc7064a3 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,17 +1,18 @@ --- +navigation_title: "Python" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html - https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/overview.html --- -# Python [overview] +# {{es}} Python client [overview] -This is the official Python client for {{es}}. Its goal is to provide common ground for all {{es}}-related code in Python. For this reason, the client is designed to be unopinionated and extendable. API reference documentation for this client is available on [Read the Docs](https://elasticsearch-py.readthedocs.io). +This documentation covers the [official Python client for {{es}}](https://github.com/elastic/elasticsearch-py). The goal of the Python client is to provide common ground for all {{es}}-related code in Python. The client is designed to be unopinionated and extendable. +API reference documentation is provided on [Read the Docs](https://elasticsearch-py.readthedocs.io). -## Example use [_example_use] -Simple use-case: +The following example shows a simple Python client use case: ```python >>> from datetime import datetime @@ -29,14 +30,12 @@ Simple use-case: {'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'} ``` -::::{tip} -For an elaborate example of how to ingest data into Elastic Cloud, refer to [this page](docs-content://manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md). -:::: + ## Features [_features] -The client’s features include: +The client's features include: * Translating basic Python data types to and from JSON * Configurable automatic discovery of cluster nodes @@ -46,31 +45,41 @@ The client’s features include: * Thread safety * Pluggable architecture -The client also contains a convenient set of [helpers](client-helpers.md) for some of the more engaging tasks like bulk indexing and reindexing. +The client also provides a convenient set of [helpers](client-helpers.md) for tasks like bulk indexing and reindexing. +::::{tip} +To get started, try this walkthrough: [Ingest data with Python](docs-content://manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md) +:::: -## Elasticsearch Python DSL [_elasticsearch_python_dsl] +### Elasticsearch Python DSL [_elasticsearch_python_dsl] -For a higher level access with more limited scope, have a look at the DSL module, which provides a more convenient and idiomatic way to write and manipulate queries. +The [Python DSL module](../reference/elasticsearch-dsl.md) offers a convenient and idiomatic way to write and manipulate queries. +## {{es}} version compatibility [_compatibility] -## Compatibility [_compatibility] +Language clients are **forward compatible**: each client version works with equivalent and later minor versions of the **same or next major** version of {{es}}. For full compatibility, the client and {{es}} minor versions should match. -Language clients are _forward compatible:_ each client version works with equivalent and later minor versions of {{es}} without breaking. +| Client version | {{es}} `8.x` | {{es}} `9.x` | {{es}} `10.x` | +|----------------|---------------------------------|---------------------------------|----------------------------------| +| 9.x client | ❌ Not compatible with {{es}} 8.x | ✅ Compatible with {{es}} 9.x | ✅ Compatible with {{es}} 10.x | +| 8.x client | ✅ Compatible with {{es}} 8.x | ✅ Compatible with {{es}} 9.x | ❌ Not compatible with {{es}} 10.x | -Compatibility does not imply full feature parity. New {{es}} features are supported only in equivalent client versions. For example, an 8.12 client fully supports {{es}} 8.12 features and works with 8.13 without breaking; however, it does not support new {{es}} 8.13 features. An 8.13 client fully supports {{es}} 8.13 features. +Compatibility does not imply feature parity. New {{es}} features are supported only in equivalent client versions. For example, an 8.12 client fully supports {{es}} 8.12 features and works with 8.13 without breaking, but it does not support new {{es}} 8.13 features. An 8.13 client fully supports {{es}} 8.13 features. -| Elasticsearch version | elasticsearch-py branch | -| --- | --- | -| main | main | -| 9.x | 9.x | -| 9.x | 8.x | -| 8.x | 8.x | +{{es}} language clients are also **backward compatible** across minor versions, with default distributions and without guarantees. -{{es}} language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees. +### Major version upgrades -:::{tip} -To upgrade to a new major version, first upgrade {{es}}, then upgrade the Python {{es}} client. +:::{important} +To upgrade to a new major version, first [upgrade {{es}}](docs-content://deploy-manage/upgrade.md), then upgrade the Python client. ::: -If you need to work with multiple client versions, note that older versions are also released as `elasticsearch7` and `elasticsearch8`. +As of version 8.0, {{es}} offers a [compatibility mode](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) for smoother upgrades. In compatibility mode, you can upgrade your {{es}} cluster to the next major version while continuing to use your existing client during the transition. + +For example, if you're upgrading {{es}} from 8.x to 9.x, you can continue to use the 8.x Python client during and after the {{es}} server upgrade, with the exception of [breaking changes](../release-notes/breaking-changes.md). + +In the Python client, compatibility mode is always enabled. + +:::{tip} +To support working with multiple client versions, the Python client is also released under the package names `elasticsearch8` and `elasticsearch9` (to prevent name collisions). +::: \ No newline at end of file diff --git a/docs/release-notes/breaking-changes.md b/docs/release-notes/breaking-changes.md index 640a57036..0a354b9ce 100644 --- a/docs/release-notes/breaking-changes.md +++ b/docs/release-notes/breaking-changes.md @@ -28,7 +28,7 @@ For more information, check [PR #2840](https://github.com/elastic/elasticsearch- * `host_info_callback` is now `sniffed_node_callback` * `sniffer_timeout` is now `min_delay_between_sniffing` * `sniff_on_connection_fail` is now `sniff_on_node_failure` - * `maxsize` is now `connection_per_node` + * `maxsize` is now `connections_per_node` :::: ::::{dropdown} Remove deprecated url_prefix and use_ssl host keys @@ -50,4 +50,4 @@ Elasticsearch 9 removed the kNN search and Unfreeze index APIs. **Action**
* The kNN search API has been replaced by the `knn` option in the search API since Elasticsearch 8.4. * The Unfreeze index API was deprecated in Elasticsearch 7.14 and has been removed in Elasticsearch 9. - :::: \ No newline at end of file + :::: diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md index 314030cdd..35574d918 100644 --- a/docs/release-notes/index.md +++ b/docs/release-notes/index.md @@ -18,6 +18,105 @@ To check for security updates, go to [Security announcements for the Elastic sta % * % ### Fixes [elasticsearch-python-client-next-fixes] +## 9.1.2 (2025-10-28) + +### Enhancements + +* Add `flush_after_seconds` option to `streaming_bulk()` ([#3064](https://github.com/elastic/elasticsearch-py/pull/3064)) + +### Bug Fixes + +* DSL: support passing inner documents as `AttrDict` instances ([#3080](https://github.com/elastic/elasticsearch-py/pull/3080)) +* DSL: add some recently added field classes as top-level exports for the package ([#3078](https://github.com/elastic/elasticsearch-py/pull/3078)) + +### API + +- Add `streams` namespace with `streams.logs_disable`, `streams.logs_enable`, `streams.status` APIs +- Add `bytes` and `time` parameters to various APIs in the `cat` namespace. +- Add `index_template` parameter to `indices.simulate_index_template` API +- Add `input_type` parameter to `inference.text_embedding` API + +### DSL + +- New `CartesianBounds`, `CartesianCentroid`, `ChangePoint` aggregations +- Add `p_value` parameter to `SignificantTerms` aggregation +- Add `index_options` and `fields` parameters to `SemanticText` field +- Add `visit_percentage` parameter to `Knn` query +- Add `on_disk_rescore` field to `DenseVectorIndexOptions` type + +### Other + +* Add 3.14 to CI builds ([#3103](https://github.com/elastic/elasticsearch-py/pull/3103))dd + +## 9.1.1 (2025-09-11) + +* ES|QL query builder integration with the DSL module ([#3058](https://github.com/elastic/elasticsearch-py/pull/3058)) +* ES|QL query builder robustness fixes ([#3017](https://github.com/elastic/elasticsearch-py/pull/3017)) +* Fix ES|QL `multi_match()` signature ([#3052](https://github.com/elastic/elasticsearch-py/pull/3052)) + +API +* Add support for ES|QL query builder objects to ES|QL Query and Async Query APIs +* Add Transform Set Upgrade Mode API +* Fix type of `fields` parameter of Term Vectors API to array of strings +* Fix type of `params` parameter of SQL Query API to array + +DSL +* Preserve the `skip_empty` setting in `to_dict()` recursive serializations ([#3041](https://github.com/elastic/elasticsearch-py/pull/3041)) +* Add `separator_group` and `separators` attributes to `ChunkingSettings` type +* Add `primary` attribute to `ShardFailure` type +* Fix type of `key` attribute of `ArrayPercentilesItem` to float + + +## 9.1.0 (2025-07-30) + +Enhancements + +* ES|QL query builder (technical preview) ([#2997](https://github.com/elastic/elasticsearch-py/pull/2997)) +* Update OpenTelemetry conventions ([#2999](https://github.com/elastic/elasticsearch-py/pull/2999)) +* Add option to disable accurate reporting of file and line location in warnings (Fixes #3003) ([#3006](https://github.com/elastic/elasticsearch-py/pull/3006)) + +APIs + +* Remove `if_primary_term`, `if_seq_no` and `op_type` from Create API +* Remove `master_timeout` from Ingest Get Ip Location Database API +* Remove `application`, `priviledge` and `username` from the Security Get User API +* Rename `type_query_string` to `type` in License Post Start Trial API +* Add `require_data_stream` to Index API +* Add `settings_filter` to Cluster Get Component Template API +* Add `cause` to Cluster Put Component Template API +* Add `master_timeout` to Cluster State API +* Add `ccs_minimize_roundtrips` to EQL Search API +* Add `keep_alive` and `keep_on_completion` to ES|QL Async Query API +* Add `format` to ES|QL Async Query Get API +* Add ES|QL Get Query and List Queries APIs +* Add Indices Delete Data Stream Options API +* Add Indices Get Data Stream Options and Put Data Stream Options APIS +* Add Indices Get Data Stream Settings and Put Data Stream Settings APIs +* Add `allow_no_indices`, `expand_wildcards` and `ignore_available` to Indices Recovery API +* Add Indices Remove Block API +* Add Amazon Sagemaker to Inference API +* Add `input_type` to Inference API +* Add `timeout` to all Inference Put APIs +* Add Inference Put Custom API +* Add Inference Put DeepSeek API +* Add `task_settings` to Put HuggingFace API +* Add `refresh` to Security Grant API Key API +* Add `wait_for_completion` to the Snapshot Delete API +* Add `state` to Snapshot Get API +* Add `refresh` to Synonyms Put Synonym, Put Synonym Rule and Delete Synonym Rule APIs + +DSL + +* Handle lists in `copy_to` option in DSL field declarations correctly (Fixes #2992) ([#2993](https://github.com/elastic/elasticsearch-py/pull/2993)) +* Add `index_options` to SparseVector type +* Add SparseVectorIndexOptions type +* Add `key` to FiltersBucket type + +Other changes + +* Drop support for Python 3.8 ([#3001](https://github.com/elastic/elasticsearch-py/pull/3001)) + + ## 9.0.2 (2025-06-05) [elasticsearch-python-client-902-release-notes] diff --git a/docs/sphinx/api/indices.rst b/docs/sphinx/api/indices.rst index 9523a3558..8d310a3b8 100644 --- a/docs/sphinx/api/indices.rst +++ b/docs/sphinx/api/indices.rst @@ -6,4 +6,4 @@ Indices :no-index: .. autoclass:: IndicesClient - :members: \ No newline at end of file + :members: diff --git a/docs/sphinx/api/streams.rst b/docs/sphinx/api/streams.rst new file mode 100644 index 000000000..d5f45b6e7 --- /dev/null +++ b/docs/sphinx/api/streams.rst @@ -0,0 +1,9 @@ +.. _streams: + +Streams +------- +.. py:module:: elasticsearch.client + :no-index: + +.. autoclass:: StreamsClient + :members: diff --git a/docs/sphinx/es_api.rst b/docs/sphinx/es_api.rst index d246ec6f5..0711a10eb 100644 --- a/docs/sphinx/es_api.rst +++ b/docs/sphinx/es_api.rst @@ -50,6 +50,7 @@ arguments are required for all calls. api/snapshots api/snapshottable-features api/sql + api/streams api/synonyms api/tls-ssl api/tasks diff --git a/elasticsearch/_async/client/__init__.py b/elasticsearch/_async/client/__init__.py index 0874e120f..34f6d58ee 100644 --- a/elasticsearch/_async/client/__init__.py +++ b/elasticsearch/_async/client/__init__.py @@ -74,6 +74,7 @@ from .snapshot import SnapshotClient from .sql import SqlClient from .ssl import SslClient +from .streams import StreamsClient from .synonyms import SynonymsClient from .tasks import TasksClient from .text_structure import TextStructureClient @@ -83,9 +84,9 @@ CLIENT_META_SERVICE, SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, client_node_configs, is_requests_http_auth, is_requests_node_class, @@ -378,6 +379,7 @@ def __init__( self.shutdown = ShutdownClient(self) self.sql = SqlClient(self) self.ssl = SslClient(self) + self.streams = StreamsClient(self) self.synonyms = SynonymsClient(self) self.text_structure = TextStructureClient(self) self.transform = TransformClient(self) @@ -500,6 +502,7 @@ async def ping( """ __path = "/" __query: t.Dict[str, t.Any] = {} + __path_parts: t.Dict[str, str] = {} if error_trace is not None: __query["error_trace"] = error_trace if filter_path is not None: @@ -511,7 +514,12 @@ async def ping( __headers = {"accept": "application/json"} try: await self.perform_request( - "HEAD", __path, params=__query, headers=__headers + "HEAD", + __path, + params=__query, + headers=__headers, + endpoint_id="ping", + path_parts=__path_parts, ) return True except (ApiError, TransportError): @@ -557,8 +565,8 @@ async def bulk( """ .. raw:: html -

Bulk index or delete documents. - Perform multiple index, create, delete, and update actions in a single request. +

Bulk index or delete documents.

+

Perform multiple index, create, delete, and update actions in a single request. This reduces overhead and can greatly increase indexing speed.

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

    @@ -608,6 +616,7 @@ async def bulk(
  • JavaScript: Check out client.helpers.*
  • .NET: Check out BulkAllObservable
  • PHP: Check out bulk indexing.
  • +
  • Ruby: Check out Elasticsearch::Helpers::BulkHelper

Submitting bulk requests with cURL

If you're providing text file input to curl, you must use the --data-binary flag instead of plain -d. @@ -762,8 +771,8 @@ async def clear_scroll( """ .. raw:: html -

Clear a scrolling search. - Clear the search context and results for a scrolling search.

+

Clear a scrolling search.

+

Clear the search context and results for a scrolling search.

``_ @@ -816,8 +825,8 @@ async def close_point_in_time( """ .. raw:: html -

Close a point in time. - A point in time must be opened explicitly before being used in search requests. +

Close a point in time.

+

A point in time must be opened explicitly before being used in search requests. The keep_alive parameter tells Elasticsearch how long it should persist. A point in time is automatically closed when the keep_alive period has elapsed. However, keeping points in time has a cost; close them as soon as they are no longer required for search requests.

@@ -844,11 +853,7 @@ async def close_point_in_time( if not __body: if id is not None: __body["id"] = id - 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] "DELETE", __path, @@ -897,8 +902,8 @@ async def count( """ .. raw:: html -

Count search results. - Get the number of documents matching a query.

+

Count search results.

+

Get the number of documents matching a query.

The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body. The query is optional. When no query is provided, the API uses match_all to count all the documents.

The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.

@@ -1326,7 +1331,7 @@ async def delete( ) @_rewrite_parameters( - body_fields=("max_docs", "query", "slice"), + body_fields=("max_docs", "query", "slice", "sort"), parameter_aliases={"from": "from_"}, ) async def delete_by_query( @@ -1370,7 +1375,12 @@ async def delete_by_query( ] = None, slice: t.Optional[t.Mapping[str, t.Any]] = None, slices: t.Optional[t.Union[int, t.Union[str, t.Literal["auto"]]]] = None, - sort: t.Optional[t.Sequence[str]] = None, + sort: t.Optional[ + t.Union[ + t.Sequence[t.Union[str, t.Mapping[str, t.Any]]], + t.Union[str, t.Mapping[str, t.Any]], + ] + ] = None, stats: t.Optional[t.Sequence[str]] = None, terminate_after: t.Optional[int] = None, timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, @@ -1502,7 +1512,7 @@ async def delete_by_query( :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 sort: A sort object that specifies the order of deleted documents. :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. @@ -1592,8 +1602,6 @@ async def delete_by_query( __query["search_type"] = search_type if slices is not None: __query["slices"] = slices - if sort is not None: - __query["sort"] = sort if stats is not None: __query["stats"] = stats if terminate_after is not None: @@ -1613,6 +1621,8 @@ async def delete_by_query( __body["query"] = query if slice is not None: __body["slice"] = slice + if sort is not None: + __body["sort"] = sort __headers = {"accept": "application/json", "content-type": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", @@ -1629,11 +1639,11 @@ async def delete_by_query_rethrottle( self, *, task_id: str, + requests_per_second: float, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, - requests_per_second: t.Optional[float] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html @@ -1651,9 +1661,13 @@ async def delete_by_query_rethrottle( """ if task_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'task_id'") + if requests_per_second is None: + raise ValueError("Empty value passed for parameter 'requests_per_second'") __path_parts: t.Dict[str, str] = {"task_id": _quote(task_id)} __path = f'/_delete_by_query/{__path_parts["task_id"]}/_rethrottle' __query: t.Dict[str, t.Any] = {} + if requests_per_second is not None: + __query["requests_per_second"] = requests_per_second if error_trace is not None: __query["error_trace"] = error_trace if filter_path is not None: @@ -1662,8 +1676,6 @@ async def delete_by_query_rethrottle( __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if requests_per_second is not None: - __query["requests_per_second"] = requests_per_second __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", @@ -1689,8 +1701,8 @@ async def delete_script( """ .. raw:: html -

Delete a script or search template. - Deletes a stored script or search template.

+

Delete a script or search template.

+

Deletes a stored script or search template.

``_ @@ -2001,8 +2013,8 @@ async def explain( """ .. raw:: html -

Explain a document match result. - Get information about why a specific document matches, or doesn't match, a query. +

Explain a document match result.

+

Get information about why a specific document matches, or doesn't match, a query. It computes a score explanation for a query and a specific document.

@@ -2234,7 +2246,6 @@ async def field_caps( @_rewrite_parameters( parameter_aliases={ "_source": "source", - "_source_exclude_vectors": "source_exclude_vectors", "_source_excludes": "source_excludes", "_source_includes": "source_includes", }, @@ -2254,7 +2265,6 @@ async def get( refresh: t.Optional[bool] = None, routing: t.Optional[str] = None, source: t.Optional[t.Union[bool, t.Union[str, t.Sequence[str]]]] = None, - source_exclude_vectors: t.Optional[bool] = None, source_excludes: t.Optional[t.Union[str, t.Sequence[str]]] = None, source_includes: t.Optional[t.Union[str, t.Sequence[str]]] = None, stored_fields: t.Optional[t.Union[str, t.Sequence[str]]] = None, @@ -2328,7 +2338,6 @@ async def get( :param routing: A custom value used to route operations to a specific shard. :param source: Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. - :param source_exclude_vectors: Whether vectors should be excluded from _source :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` @@ -2374,8 +2383,6 @@ async def get( __query["routing"] = routing if source is not None: __query["_source"] = source - if source_exclude_vectors is not None: - __query["_source_exclude_vectors"] = source_exclude_vectors if source_excludes is not None: __query["_source_excludes"] = source_excludes if source_includes is not None: @@ -2410,8 +2417,8 @@ async def get_script( """ .. raw:: html -

Get a script or search template. - Retrieves a stored script or search template.

+

Get a script or search template.

+

Retrieves a stored script or search template.

``_ @@ -2647,8 +2654,8 @@ async def health_report( """ .. raw:: html -

Get the cluster health. - Get a report with the health status of an Elasticsearch cluster. +

Get the cluster health.

+

Get a report with the health status of an Elasticsearch cluster. The report contains a list of indicators that compose Elasticsearch functionality.

Each indicator has a health status of: green, unknown, yellow or red. The indicator will provide an explanation and metadata describing the reason for its current health status.

@@ -2819,13 +2826,11 @@ async def index( "id": "elkbee" } } - - In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1. - If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code). - - A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used. - Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order. +

In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1. + If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).

+

A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used. + Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.

``_ @@ -2960,8 +2965,8 @@ async def info( """ .. raw:: html -

Get cluster info. - Get basic build, version, and cluster information. +

Get cluster info.

+

Get basic build, version, and cluster information. ::: In Serverless, this API is retained for backward compatibility only. Some response fields, such as the version number, should be ignored.

@@ -3655,8 +3660,8 @@ async def put_script( """ .. raw:: html -

Create or update a script or search template. - Creates or updates a stored script or search template.

+

Create or update a script or search template.

+

Creates or updates a stored script or search template.

``_ @@ -3875,6 +3880,13 @@ async def reindex( 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.

+

It's recommended to reindex on indices with a green status. Reindexing can fail when a node shuts down or crashes.

+
    +
  • When requested with wait_for_completion=true (default), the request fails if the node shuts down.
  • +
  • When requested with wait_for_completion=false, a task id is returned, for use with the task management APIs. The task may disappear or fail if the node shuts down. + When retrying a failed reindex operation, it might be necessary to set conflicts=proceed or to first delete the partial destination index. + Additionally, dry runs, checking disk space, and fetching index recovery information can help address the root cause.
  • +

Refer to the linked documentation for examples of how to reindex documents.

@@ -3983,11 +3995,11 @@ async def reindex_rethrottle( self, *, task_id: str, + requests_per_second: float, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, - requests_per_second: t.Optional[float] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html @@ -4011,9 +4023,13 @@ async def reindex_rethrottle( """ if task_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'task_id'") + if requests_per_second is None: + raise ValueError("Empty value passed for parameter 'requests_per_second'") __path_parts: t.Dict[str, str] = {"task_id": _quote(task_id)} __path = f'/_reindex/{__path_parts["task_id"]}/_rethrottle' __query: t.Dict[str, t.Any] = {} + if requests_per_second is not None: + __query["requests_per_second"] = requests_per_second if error_trace is not None: __query["error_trace"] = error_trace if filter_path is not None: @@ -4022,8 +4038,6 @@ async def reindex_rethrottle( __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if requests_per_second is not None: - __query["requests_per_second"] = requests_per_second __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", @@ -4093,11 +4107,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, @@ -4111,7 +4121,7 @@ async def render_search_template( @_rewrite_parameters( body_fields=("context", "context_setup", "script"), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def scripts_painless_execute( self, *, @@ -4180,11 +4190,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, @@ -4309,7 +4315,6 @@ async def scroll( ), parameter_aliases={ "_source": "source", - "_source_exclude_vectors": "source_exclude_vectors", "_source_excludes": "source_excludes", "_source_includes": "source_includes", "from": "from_", @@ -4393,7 +4398,6 @@ async def search( ] ] = None, source: t.Optional[t.Union[bool, t.Mapping[str, t.Any]]] = None, - source_exclude_vectors: t.Optional[bool] = None, source_excludes: t.Optional[t.Union[str, t.Sequence[str]]] = None, source_includes: t.Optional[t.Union[str, t.Sequence[str]]] = None, stats: t.Optional[t.Sequence[str]] = None, @@ -4588,7 +4592,6 @@ async def search( 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_exclude_vectors: Whether vectors should be excluded from _source :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` @@ -4713,8 +4716,6 @@ async def search( __query["scroll"] = scroll if search_type is not None: __query["search_type"] = search_type - if source_exclude_vectors is not None: - __query["_source_exclude_vectors"] = source_exclude_vectors if source_excludes is not None: __query["_source_excludes"] = source_excludes if source_includes is not None: @@ -5141,11 +5142,19 @@ async def search_mvt( ``_ - :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 index: A list of indices, data streams, or aliases to search. It supports + wildcards (`*`). To search all data streams and indices, omit this parameter + or use `*` or `_all`. To search a remote cluster, use the `:` + syntax. + :param field: A field that contains the geospatial data to return. It must be + a `geo_point` or `geo_shape` field. The field must have doc values enabled. + It cannot be a nested field. NOTE: Vector tiles do not natively support geometry + collections. For `geometrycollection` values in a `geo_shape` field, the + API returns a hits layer feature for each element of the collection. This + behavior may change in a future release. + :param zoom: The zoom level of the vector tile to search. It accepts `0` to `29`. + :param x: The X coordinate for the vector tile to search. + :param y: The Y coordinate for the vector tile to search. :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` @@ -5620,11 +5629,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, @@ -5659,7 +5664,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, @@ -6059,8 +6064,8 @@ async def update_by_query( """ .. raw:: html -

Update documents. - Updates documents that match the specified query. +

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:

    @@ -6339,11 +6344,11 @@ async def update_by_query_rethrottle( self, *, task_id: str, + requests_per_second: float, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, - requests_per_second: t.Optional[float] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html @@ -6361,9 +6366,13 @@ async def update_by_query_rethrottle( """ if task_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'task_id'") + if requests_per_second is None: + raise ValueError("Empty value passed for parameter 'requests_per_second'") __path_parts: t.Dict[str, str] = {"task_id": _quote(task_id)} __path = f'/_update_by_query/{__path_parts["task_id"]}/_rethrottle' __query: t.Dict[str, t.Any] = {} + if requests_per_second is not None: + __query["requests_per_second"] = requests_per_second if error_trace is not None: __query["error_trace"] = error_trace if filter_path is not None: @@ -6372,8 +6381,6 @@ async def update_by_query_rethrottle( __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if requests_per_second is not None: - __query["requests_per_second"] = requests_per_second __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", diff --git a/elasticsearch/_async/client/async_search.py b/elasticsearch/_async/client/async_search.py index 4d1c32974..36fe765b9 100644 --- a/elasticsearch/_async/client/async_search.py +++ b/elasticsearch/_async/client/async_search.py @@ -357,7 +357,7 @@ async def submit( :param allow_partial_search_results: Indicate if an error should be returned if there is a partial search failure or timeout :param analyze_wildcard: Specify whether wildcard and prefix queries should be - analyzed (default: false) + analyzed :param analyzer: The analyzer to use for the query string :param batched_reduce_size: Affects how often partial results become available, which happens whenever shard results are reduced. A partial reduction is @@ -373,7 +373,7 @@ async def submit( values for field names matching these patterns in the hits.fields property of the response. :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. + that are open, closed or both :param explain: If true, returns detailed information about score computation as part of a hit. :param ext: Configuration of search extensions defined by Elasticsearch plugins. @@ -406,7 +406,7 @@ async def submit( you cannot specify an in the request path. :param post_filter: :param preference: Specify the node or shard the operation should be performed - on (default: random) + on :param profile: :param q: Query in the Lucene query string syntax :param query: Defines the search definition using the Query DSL. diff --git a/elasticsearch/_async/client/autoscaling.py b/elasticsearch/_async/client/autoscaling.py index 5b41caa38..692e7c3be 100644 --- a/elasticsearch/_async/client/autoscaling.py +++ b/elasticsearch/_async/client/autoscaling.py @@ -20,7 +20,11 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + _quote, + _rewrite_parameters, +) class AutoscalingClient(NamespacedClient): @@ -46,7 +50,7 @@ async def delete_autoscaling_policy( ``_ - :param name: the name of the autoscaling policy + :param name: 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. @@ -153,7 +157,7 @@ async def get_autoscaling_policy( ``_ - :param name: the name of the autoscaling policy + :param name: 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. @@ -208,7 +212,7 @@ async def put_autoscaling_policy( ``_ - :param name: the name of the autoscaling policy + :param name: 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 diff --git a/elasticsearch/_async/client/cat.py b/elasticsearch/_async/client/cat.py index 148ed721f..473b43be9 100644 --- a/elasticsearch/_async/client/cat.py +++ b/elasticsearch/_async/client/cat.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -36,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[ @@ -47,12 +50,42 @@ 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, 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]: """ @@ -68,13 +101,22 @@ async def aliases( :param name: A comma-separated list of aliases to retrieve. Supports wildcards (`*`). To retrieve all aliases, 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 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 master_timeout: The period to wait for a connection to the master node. @@ -84,6 +126,12 @@ async def aliases( :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] @@ -94,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: @@ -114,6 +164,8 @@ async def aliases( __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"} @@ -137,13 +189,57 @@ 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]: """ @@ -158,10 +254,18 @@ async def allocation( :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 @@ -172,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] @@ -204,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"} @@ -221,16 +333,51 @@ 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]: """ @@ -247,9 +394,18 @@ async def component_templates( :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 @@ -260,6 +416,12 @@ async def component_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] @@ -270,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: @@ -290,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"} @@ -307,14 +473,25 @@ 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, 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]: """ @@ -332,14 +509,29 @@ async def count( :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 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] @@ -350,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: @@ -366,6 +560,8 @@ async def count( __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"} @@ -389,11 +585,21 @@ 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, 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]: """ @@ -409,15 +615,29 @@ async def fielddata( :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 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] @@ -446,6 +666,8 @@ async def fielddata( __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"} @@ -462,10 +684,58 @@ 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, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal[ + "active_shards_percent", + "cluster", + "epoch", + "init", + "max_task_wait_time", + "node.data", + "node.total", + "pending_tasks", + "pri", + "relo", + "shards", + "status", + "timestamp", + "unassign", + "unassign.pri", + ], + ] + ], + t.Union[ + str, + t.Literal[ + "active_shards_percent", + "cluster", + "epoch", + "init", + "max_task_wait_time", + "node.data", + "node.total", + "pending_tasks", + "pri", + "relo", + "shards", + "status", + "timestamp", + "unassign", + "unassign.pri", + ], + ], + ] + ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, @@ -493,21 +763,37 @@ async def health( ``_ + :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 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: @@ -578,12 +864,321 @@ async def indices( t.Sequence[ t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]] ], - t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]], + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]], + ] + ] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + format: t.Optional[str] = None, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal[ + "bulk.avg_size_in_bytes", + "bulk.avg_time", + "bulk.total_operations", + "bulk.total_size_in_bytes", + "bulk.total_time", + "completion.size", + "creation.date", + "creation.date.string", + "dataset.size", + "dense_vector.value_count", + "docs.count", + "docs.deleted", + "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", + "health", + "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", + "memory.total", + "merges.current", + "merges.current_docs", + "merges.current_size", + "merges.total", + "merges.total_docs", + "merges.total_size", + "merges.total_time", + "pri", + "pri.bulk.avg_size_in_bytes", + "pri.bulk.avg_time", + "pri.bulk.total_operations", + "pri.bulk.total_size_in_bytes", + "pri.bulk.total_time", + "pri.completion.size", + "pri.dense_vector.value_count", + "pri.fielddata.evictions", + "pri.fielddata.memory_size", + "pri.flush.total", + "pri.flush.total_time", + "pri.get.current", + "pri.get.exists_time", + "pri.get.exists_total", + "pri.get.missing_time", + "pri.get.missing_total", + "pri.get.time", + "pri.get.total", + "pri.indexing.delete_current", + "pri.indexing.delete_time", + "pri.indexing.delete_total", + "pri.indexing.index_current", + "pri.indexing.index_failed", + "pri.indexing.index_failed_due_to_version_conflict", + "pri.indexing.index_time", + "pri.indexing.index_total", + "pri.memory.total", + "pri.merges.current", + "pri.merges.current_docs", + "pri.merges.current_size", + "pri.merges.total", + "pri.merges.total_docs", + "pri.merges.total_size", + "pri.merges.total_time", + "pri.query_cache.evictions", + "pri.query_cache.memory_size", + "pri.refresh.external_time", + "pri.refresh.external_total", + "pri.refresh.listeners", + "pri.refresh.time", + "pri.refresh.total", + "pri.request_cache.evictions", + "pri.request_cache.hit_count", + "pri.request_cache.memory_size", + "pri.request_cache.miss_count", + "pri.search.fetch_current", + "pri.search.fetch_time", + "pri.search.fetch_total", + "pri.search.open_contexts", + "pri.search.query_current", + "pri.search.query_time", + "pri.search.query_total", + "pri.search.scroll_current", + "pri.search.scroll_time", + "pri.search.scroll_total", + "pri.segments.count", + "pri.segments.fixed_bitset_memory", + "pri.segments.index_writer_memory", + "pri.segments.memory", + "pri.segments.version_map_memory", + "pri.sparse_vector.value_count", + "pri.store.size", + "pri.suggest.current", + "pri.suggest.time", + "pri.suggest.total", + "pri.warmer.current", + "pri.warmer.total", + "pri.warmer.total_time", + "query_cache.evictions", + "query_cache.memory_size", + "refresh.external_time", + "refresh.external_total", + "refresh.listeners", + "refresh.time", + "refresh.total", + "rep", + "request_cache.evictions", + "request_cache.hit_count", + "request_cache.memory_size", + "request_cache.miss_count", + "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", + "sparse_vector.value_count", + "status", + "store.size", + "suggest.current", + "suggest.time", + "suggest.total", + "uuid", + "warmer.current", + "warmer.total", + "warmer.total_time", + ], + ] + ], + t.Union[ + str, + t.Literal[ + "bulk.avg_size_in_bytes", + "bulk.avg_time", + "bulk.total_operations", + "bulk.total_size_in_bytes", + "bulk.total_time", + "completion.size", + "creation.date", + "creation.date.string", + "dataset.size", + "dense_vector.value_count", + "docs.count", + "docs.deleted", + "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", + "health", + "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", + "memory.total", + "merges.current", + "merges.current_docs", + "merges.current_size", + "merges.total", + "merges.total_docs", + "merges.total_size", + "merges.total_time", + "pri", + "pri.bulk.avg_size_in_bytes", + "pri.bulk.avg_time", + "pri.bulk.total_operations", + "pri.bulk.total_size_in_bytes", + "pri.bulk.total_time", + "pri.completion.size", + "pri.dense_vector.value_count", + "pri.fielddata.evictions", + "pri.fielddata.memory_size", + "pri.flush.total", + "pri.flush.total_time", + "pri.get.current", + "pri.get.exists_time", + "pri.get.exists_total", + "pri.get.missing_time", + "pri.get.missing_total", + "pri.get.time", + "pri.get.total", + "pri.indexing.delete_current", + "pri.indexing.delete_time", + "pri.indexing.delete_total", + "pri.indexing.index_current", + "pri.indexing.index_failed", + "pri.indexing.index_failed_due_to_version_conflict", + "pri.indexing.index_time", + "pri.indexing.index_total", + "pri.memory.total", + "pri.merges.current", + "pri.merges.current_docs", + "pri.merges.current_size", + "pri.merges.total", + "pri.merges.total_docs", + "pri.merges.total_size", + "pri.merges.total_time", + "pri.query_cache.evictions", + "pri.query_cache.memory_size", + "pri.refresh.external_time", + "pri.refresh.external_total", + "pri.refresh.listeners", + "pri.refresh.time", + "pri.refresh.total", + "pri.request_cache.evictions", + "pri.request_cache.hit_count", + "pri.request_cache.memory_size", + "pri.request_cache.miss_count", + "pri.search.fetch_current", + "pri.search.fetch_time", + "pri.search.fetch_total", + "pri.search.open_contexts", + "pri.search.query_current", + "pri.search.query_time", + "pri.search.query_total", + "pri.search.scroll_current", + "pri.search.scroll_time", + "pri.search.scroll_total", + "pri.segments.count", + "pri.segments.fixed_bitset_memory", + "pri.segments.index_writer_memory", + "pri.segments.memory", + "pri.segments.version_map_memory", + "pri.sparse_vector.value_count", + "pri.store.size", + "pri.suggest.current", + "pri.suggest.time", + "pri.suggest.total", + "pri.warmer.current", + "pri.warmer.total", + "pri.warmer.total_time", + "query_cache.evictions", + "query_cache.memory_size", + "refresh.external_time", + "refresh.external_total", + "refresh.listeners", + "refresh.time", + "refresh.total", + "rep", + "request_cache.evictions", + "request_cache.hit_count", + "request_cache.memory_size", + "request_cache.miss_count", + "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", + "sparse_vector.value_count", + "status", + "store.size", + "suggest.current", + "suggest.time", + "suggest.total", + "uuid", + "warmer.current", + "warmer.total", + "warmer.total_time", + ], + ], ] ] = 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, health: t.Optional[ t.Union[str, t.Literal["green", "red", "unavailable", "unknown", "yellow"]] ] = None, @@ -623,11 +1218,19 @@ async def indices( :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`. - :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 health: The health status used to limit returned indices. By default, the response includes indices of any health status. :param help: When set to `true` will output available columns. This option can't @@ -639,7 +1242,12 @@ async def indices( :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] @@ -696,16 +1304,27 @@ 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, - h: t.Optional[t.Union[str, t.Sequence[str]]] = None, + h: t.Optional[ + t.Union[ + t.Sequence[t.Union[str, t.Literal["host", "id", "ip", "node"]]], + t.Union[str, t.Literal["host", "id", "ip", "node"]], + ] + ] = 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]: """ @@ -718,9 +1337,18 @@ async def master( ``_ + :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 @@ -731,11 +1359,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: @@ -756,6 +1392,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"} @@ -898,8 +1536,15 @@ async def ml_data_frame_analytics( :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. @@ -907,7 +1552,12 @@ async def ml_data_frame_analytics( be combined with any other query string option. :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] @@ -958,6 +1608,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, @@ -1073,6 +1726,14 @@ 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. @@ -1080,7 +1741,12 @@ async def ml_datafeeds( be combined with any other query string option. :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] @@ -1093,6 +1759,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: @@ -1438,7 +2106,14 @@ 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. @@ -1446,7 +2121,12 @@ async def ml_jobs( be combined with any other query string option. :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] @@ -1623,7 +2303,14 @@ 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. @@ -1633,7 +2320,12 @@ async def ml_trained_models( :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: 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] @@ -1686,16 +2378,39 @@ 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, - h: t.Optional[t.Union[str, t.Sequence[str]]] = None, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal[ + "attr", "host", "id", "ip", "node", "pid", "port", "value" + ], + ] + ], + t.Union[ + str, + t.Literal[ + "attr", "host", "id", "ip", "node", "pid", "port", "value" + ], + ], + ] + ] = 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]: """ @@ -1708,9 +2423,18 @@ async def nodeattrs( ``_ + :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 @@ -1721,11 +2445,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: @@ -1746,6 +2478,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"} @@ -1984,7 +2718,14 @@ async def nodes( ``_ - :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 @@ -1999,7 +2740,12 @@ async def nodes( :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: 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] = {} @@ -2047,10 +2793,25 @@ 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, - h: t.Optional[t.Union[str, t.Sequence[str]]] = None, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal["insertOrder", "priority", "source", "timeInQueue"], + ] + ], + t.Union[ + str, t.Literal["insertOrder", "priority", "source", "timeInQueue"] + ], + ] + ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, local: t.Optional[bool] = None, @@ -2072,9 +2833,18 @@ async def pending_tasks( ``_ + :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 @@ -2085,12 +2855,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: 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] = {} __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: @@ -2129,10 +2906,25 @@ 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, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal["component", "description", "id", "name", "version"], + ] + ], + t.Union[ + str, t.Literal["component", "description", "id", "name", "version"] + ], + ] + ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, include_bootstrap: t.Optional[bool] = None, @@ -2140,6 +2932,9 @@ async def plugins( 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]: """ @@ -2152,9 +2947,18 @@ async def plugins( ``_ + :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 include_bootstrap: Include bootstrap plugins in the response @@ -2166,11 +2970,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: @@ -2193,6 +3005,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"} @@ -2311,7 +3125,14 @@ async def recovery( 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 @@ -2323,7 +3144,12 @@ async def recovery( :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: 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] @@ -2374,6 +3200,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, @@ -2384,6 +3213,9 @@ 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]: """ @@ -2396,6 +3228,14 @@ async def repositories( ``_ + :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. @@ -2409,11 +3249,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: @@ -2434,6 +3282,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"} @@ -2451,10 +3301,20 @@ async def segments( self, *, index: t.Optional[t.Union[str, t.Sequence[str]]] = None, + allow_closed: t.Optional[bool] = None, + allow_no_indices: 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, + expand_wildcards: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]] + ], + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]], + ] + ] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, format: t.Optional[str] = None, h: t.Optional[ @@ -2505,10 +3365,15 @@ async def segments( ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, + ignore_throttled: 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]: """ @@ -2525,13 +3390,36 @@ async def segments( :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 allow_closed: If true, allow closed indices to be returned in the response + otherwise if false, keep the legacy behaviour of throwing an exception if + index pattern matches closed indices + :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 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: Type of index that wildcard expressions can match. If + the request can target data streams, this argument determines whether wildcard + expressions match hidden data streams. 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: 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_throttled: If true, concrete, expanded or aliased indices are ignored + when frozen. + :param ignore_unavailable: If true, missing or closed indices are not included + 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 @@ -2540,6 +3428,12 @@ async def segments( :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] @@ -2550,10 +3444,16 @@ async def segments( __path_parts = {} __path = "/_cat/segments" __query: t.Dict[str, t.Any] = {} + if allow_closed is not None: + __query["allow_closed"] = allow_closed + if allow_no_indices is not None: + __query["allow_no_indices"] = allow_no_indices 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: + __query["expand_wildcards"] = expand_wildcards if filter_path is not None: __query["filter_path"] = filter_path if format is not None: @@ -2564,6 +3464,10 @@ async def segments( __query["help"] = help if human is not None: __query["human"] = human + if ignore_throttled is not None: + __query["ignore_throttled"] = ignore_throttled + 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: @@ -2572,6 +3476,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"} @@ -2775,7 +3681,14 @@ async def shards( :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. @@ -2785,7 +3698,12 @@ async def shards( :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: 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] @@ -2835,6 +3753,9 @@ 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, @@ -2905,6 +3826,14 @@ async def snapshots( :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: A comma-separated list of columns names to display. It supports simple @@ -2917,7 +3846,12 @@ async def snapshots( :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: 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] @@ -2928,6 +3862,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: @@ -2963,16 +3899,64 @@ async def snapshots( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_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, 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[ + "action", + "id", + "ip", + "node", + "node_id", + "parent_task_id", + "port", + "running_time", + "running_time_ns", + "start_time", + "task_id", + "timestamp", + "type", + "version", + "x_opaque_id", + ], + ] + ], + t.Union[ + str, + t.Literal[ + "action", + "id", + "ip", + "node", + "node_id", + "parent_task_id", + "port", + "running_time", + "running_time_ns", + "start_time", + "task_id", + "timestamp", + "type", + "version", + "x_opaque_id", + ], + ], + ] + ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, nodes: t.Optional[t.Sequence[str]] = None, @@ -2997,11 +3981,20 @@ async def tasks( ``_ :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 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 nodes: Unique node identifiers, which are used to limit the response. @@ -3010,7 +4003,12 @@ async def 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: 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 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. @@ -3022,6 +4020,8 @@ async def 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: @@ -3067,16 +4067,39 @@ 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, - h: t.Optional[t.Union[str, t.Sequence[str]]] = None, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal[ + "composed_of", "index_patterns", "name", "order", "version" + ], + ] + ], + t.Union[ + str, + t.Literal[ + "composed_of", "index_patterns", "name", "order", "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]: """ @@ -3092,9 +4115,18 @@ async def templates( :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. + :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 @@ -3105,6 +4137,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] @@ -3115,6 +4153,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: @@ -3135,6 +4175,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"} @@ -3152,6 +4194,9 @@ 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, @@ -3235,6 +4280,14 @@ async def thread_pool( :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. @@ -3248,7 +4301,12 @@ async def thread_pool( :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: 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] @@ -3259,6 +4317,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: @@ -3301,6 +4361,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, @@ -3500,6 +4563,14 @@ 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. @@ -3509,7 +4580,12 @@ async def transforms( :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] @@ -3522,6 +4598,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: diff --git a/elasticsearch/_async/client/ccr.py b/elasticsearch/_async/client/ccr.py index a98428ffb..f87ce10cf 100644 --- a/elasticsearch/_async/client/ccr.py +++ b/elasticsearch/_async/client/ccr.py @@ -125,8 +125,8 @@ async def follow( """ .. raw:: html -

    Create a follower. - Create a cross-cluster replication follower index that follows a specific leader index. +

    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.

    @@ -368,8 +368,8 @@ async def forget_follower( """ .. raw:: html -

    Forget a follower. - Remove the cross-cluster replication follower retention leases from the leader.

    +

    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. @@ -382,7 +382,7 @@ async def forget_follower( ``_ - :param index: the name of the leader index for which specified follower retention + :param index: Name of the leader index for which specified follower retention leases should be removed :param follower_cluster: :param follower_index: @@ -640,8 +640,8 @@ async def put_auto_follow_pattern( """ .. raw:: html -

    Create or update auto-follow patterns. - Create a collection of cross-cluster replication auto-follow patterns for a remote cluster. +

    Create or update auto-follow patterns.

    +

    Create a collection of cross-cluster replication auto-follow patterns for a remote cluster. Newly created indices on the remote cluster that match any of the patterns are automatically configured as follower indices. Indices on the remote cluster that were created before the auto-follow pattern was created will not be auto-followed even if they match the pattern.

    This API can also be used to update auto-follow patterns. @@ -853,8 +853,8 @@ async def resume_follow( """ .. raw:: html -

    Resume a follower. - Resume a cross-cluster replication follower index that was paused. +

    Resume a follower.

    +

    Resume a cross-cluster replication follower index that was paused. The follower index could have been paused with the pause follower API. Alternatively it could be paused due to replication that cannot be retried due to failures during following tasks. When this API returns, the follower index will resume fetching operations from the leader index.

    @@ -862,7 +862,7 @@ async def resume_follow( ``_ - :param index: The name of the follow index to resume following. + :param index: Name of the follow index to resume following :param master_timeout: Period to wait for a connection to the master node. :param max_outstanding_read_requests: :param max_outstanding_write_requests: diff --git a/elasticsearch/_async/client/cluster.py b/elasticsearch/_async/client/cluster.py index 91956f7c4..7f1cdad32 100644 --- a/elasticsearch/_async/client/cluster.py +++ b/elasticsearch/_async/client/cluster.py @@ -47,9 +47,8 @@ async def allocation_explain( """ .. raw:: html -

    Explain the shard allocations. - Get explanations for shard allocations in the cluster. - This API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time. +

    Explain the shard allocations.

    +

    Get explanations for shard allocations in the cluster. For unassigned shards, it provides an explanation for why the shard is unassigned. For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise. @@ -58,16 +57,17 @@ async def allocation_explain( ``_ - :param current_node: Explain a shard only if it is currently located on the specified - node name or node ID. + :param current_node: Specifies the node ID or the name of the node to only explain + a shard that is currently located on the specified node. :param include_disk_info: If true, returns information about disk usage and shard sizes. :param include_yes_decisions: If true, returns YES decisions in explanation. - :param index: The name of the index that you would like an explanation for. + :param index: Specifies the name of the index that you would like an explanation + for. :param master_timeout: Period to wait for a connection to the master node. - :param primary: If true, returns an explanation for the primary shard for the - specified shard ID. - :param shard: An identifier for the shard that you would like an explanation + :param primary: If true, returns explanation for the primary shard for the given + shard ID. + :param shard: Specifies the ID of the shard that you would like an explanation for. """ __path_parts: t.Dict[str, str] = {} @@ -127,8 +127,8 @@ async def delete_component_template( """ .. raw:: html -

    Delete component templates. - Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

    +

    Delete component templates.

    +

    Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

    ``_ @@ -182,8 +182,8 @@ async def delete_voting_config_exclusions( """ .. raw:: html -

    Clear cluster voting config exclusions. - Remove master-eligible nodes from the voting configuration exclusion list.

    +

    Clear cluster voting config exclusions.

    +

    Remove master-eligible nodes from the voting configuration exclusion list.

    ``_ @@ -236,8 +236,8 @@ async def exists_component_template( """ .. raw:: html -

    Check component templates. - Returns information about whether a particular component template exists.

    +

    Check component templates.

    +

    Returns information about whether a particular component template exists.

    ``_ @@ -296,8 +296,8 @@ async def get_component_template( """ .. raw:: html -

    Get component templates. - Get information about component templates.

    +

    Get component templates.

    +

    Get information about component templates.

    ``_ @@ -306,7 +306,7 @@ async def get_component_template( request. Wildcard (`*`) expressions are supported. :param flat_settings: If `true`, returns settings in flat format. :param include_defaults: Return all default configurations for the component - template (default: false) + template :param local: If `true`, the request retrieves information from the local node only. If `false`, information is retrieved from the master node. :param master_timeout: Period to wait for a connection to the master node. If @@ -374,8 +374,13 @@ async def get_settings( ``_ :param flat_settings: If `true`, returns settings in flat format. - :param include_defaults: If `true`, returns default cluster settings from the - local node. + :param include_defaults: If `true`, also returns default values for all other + cluster settings, reflecting the values in the `elasticsearch.yml` file of + one of the nodes in the cluster. If the nodes in your cluster do not all + have the same values in their `elasticsearch.yml` config files then the values + returned by this API may vary from invocation to invocation and may not reflect + the values that Elasticsearch uses in all situations. Use the `GET _nodes/settings` + API to fetch the settings for each individual node in your cluster. :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. @@ -567,8 +572,8 @@ async def info( """ .. raw:: html -

    Get cluster info. - Returns basic information about the cluster.

    +

    Get cluster info.

    +

    Returns basic information about the cluster.

    ``_ @@ -613,8 +618,8 @@ async def pending_tasks( """ .. raw:: html -

    Get the pending cluster tasks. - Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.

    +

    Get the pending cluster tasks.

    +

    Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.

    NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.

    @@ -669,8 +674,8 @@ async def post_voting_config_exclusions( """ .. raw:: html -

    Update voting configuration exclusions. - Update the cluster voting config exclusions by node IDs or node names. +

    Update voting configuration exclusions.

    +

    Update the cluster voting config exclusions by node IDs or node names. By default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks. If you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, use this API to remove departing nodes from the voting configuration manually. The API adds an entry for each specified node to the cluster’s voting configuration exclusions list. @@ -752,8 +757,8 @@ async def put_component_template( """ .. raw:: html -

    Create or update a component template. - Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

    +

    Create or update a component template.

    +

    Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

    An index template can be composed of multiple component templates. To use a component template, specify it in an index template’s composed_of list. Component templates are only applied to new data streams and indices as part of a matching index template.

    @@ -878,10 +883,10 @@ async def put_settings( ``_ - :param flat_settings: Return settings in flat format (default: false) - :param master_timeout: Explicit operation timeout for connection to master node + :param flat_settings: Return settings in flat format + :param master_timeout: The period to wait for a connection to the master node. :param persistent: The settings that persist after the cluster restarts. - :param timeout: Explicit operation timeout + :param timeout: The period to wait for a response. :param transient: The settings that do not persist after the cluster restarts. """ __path_parts: t.Dict[str, str] = {} @@ -987,8 +992,8 @@ async def reroute( """ .. raw:: html -

    Reroute the cluster. - Manually change the allocation of individual shards in the cluster. +

    Reroute the cluster.

    +

    Manually change the allocation of individual shards in the cluster. For example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node.

    It is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as cluster.routing.rebalance.enable) in order to remain in a balanced state. For example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.

    @@ -1088,8 +1093,8 @@ async def state( """ .. raw:: html -

    Get the cluster state. - Get comprehensive information about the state of the cluster.

    +

    Get the cluster state.

    +

    Get comprehensive information about the state of the cluster.

    The cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.

    The elected master node ensures that every node in the cluster has a copy of the same cluster state. This API lets you retrieve a representation of this internal state for debugging or diagnostic purposes. @@ -1106,19 +1111,19 @@ async def state( ``_ - :param metric: Limit the information returned to the specified metrics + :param metric: Limit the information returned to the specified metrics. :param index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices :param allow_no_indices: Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified) :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. - :param flat_settings: Return settings in flat format (default: false) + that are open, closed or both + :param flat_settings: Return settings in flat format :param ignore_unavailable: Whether specified concrete indices should be ignored when unavailable (missing or closed) :param local: Return local information, do not retrieve the state from master - node (default: false) + node :param master_timeout: Timeout for waiting for new cluster state in case it is blocked :param wait_for_metadata_version: Wait for the metadata version to be equal or @@ -1189,8 +1194,8 @@ async def stats( """ .. raw:: html -

    Get cluster statistics. - Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).

    +

    Get cluster statistics.

    +

    Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).

    ``_ diff --git a/elasticsearch/_async/client/connector.py b/elasticsearch/_async/client/connector.py index 6c4bca043..19a4c382b 100644 --- a/elasticsearch/_async/client/connector.py +++ b/elasticsearch/_async/client/connector.py @@ -23,16 +23,17 @@ from .utils import ( SKIP_IN_PATH, Stability, + Visibility, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class ConnectorClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def check_in( self, *, @@ -77,7 +78,7 @@ async def check_in( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def delete( self, *, @@ -103,7 +104,7 @@ async def delete( :param connector_id: The unique identifier of the connector to be deleted :param delete_sync_jobs: A flag indicating if associated sync jobs should be - also removed. Defaults to false. + also removed. :param hard: A flag indicating if the connector should be hard deleted. """ if connector_id in SKIP_IN_PATH: @@ -134,7 +135,7 @@ async def delete( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def get( self, *, @@ -199,7 +200,7 @@ async def get( "sync_cursor", ), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL, Visibility.PRIVATE) async def last_sync( self, *, @@ -333,7 +334,7 @@ async def last_sync( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def list( self, *, @@ -360,7 +361,7 @@ async def list( :param connector_name: A comma-separated list of connector names to fetch connector documents for - :param from_: Starting offset (default: 0) + :param from_: Starting offset :param include_deleted: A flag to indicate if the desired connector should be fetched, even if it was soft-deleted. :param index_name: A comma-separated list of connector index names to fetch connector @@ -416,7 +417,7 @@ async def list( "service_type", ), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def post( self, *, @@ -500,7 +501,7 @@ async def post( "service_type", ), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def put( self, *, @@ -580,7 +581,7 @@ async def put( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def sync_job_cancel( self, *, @@ -630,7 +631,7 @@ async def sync_job_cancel( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def sync_job_check_in( self, *, @@ -643,8 +644,8 @@ async def sync_job_check_in( """ .. raw:: html -

    Check in a connector sync job. - Check in a connector sync job and set the last_seen field to the current time before updating it in the internal index.

    +

    Check in a connector sync job.

    +

    Check in a connector sync job and set the last_seen field to the current time before updating it in the internal index.

    To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

    @@ -684,7 +685,7 @@ async def sync_job_check_in( @_rewrite_parameters( body_fields=("worker_hostname", "sync_cursor"), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def sync_job_claim( self, *, @@ -700,8 +701,8 @@ async def sync_job_claim( """ .. raw:: html -

    Claim a connector sync job. - This action updates the job status to in_progress and sets the last_seen and started_at timestamps to the current time. +

    Claim a connector sync job.

    +

    This action updates the job status to in_progress and sets the last_seen and started_at timestamps to the current time. Additionally, it can set the sync_cursor property for the sync job.

    This API is not intended for direct connector management by users. It supports the implementation of services that utilize the connector protocol to communicate with Elasticsearch.

    @@ -753,7 +754,7 @@ async def sync_job_claim( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def sync_job_delete( self, *, @@ -804,7 +805,7 @@ async def sync_job_delete( @_rewrite_parameters( body_fields=("error",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def sync_job_error( self, *, @@ -819,8 +820,8 @@ async def sync_job_error( """ .. raw:: html -

    Set a connector sync job error. - Set the error field for a connector sync job and set its status to error.

    +

    Set a connector sync job error.

    +

    Set the error field for a connector sync job and set its status to error.

    To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

    @@ -863,7 +864,7 @@ async def sync_job_error( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def sync_job_get( self, *, @@ -911,7 +912,7 @@ async def sync_job_get( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def sync_job_list( self, *, @@ -955,7 +956,7 @@ async def sync_job_list( ``_ :param connector_id: A connector id to fetch connector sync jobs for - :param from_: Starting offset (default: 0) + :param from_: Starting offset :param job_type: A comma-separated list of job types to fetch the sync jobs for :param size: Specifies a max number of results to get :param status: A sync job status to fetch connector sync jobs for @@ -994,7 +995,7 @@ async def sync_job_list( @_rewrite_parameters( body_fields=("id", "job_type", "trigger_method"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def sync_job_post( self, *, @@ -1066,7 +1067,7 @@ async def sync_job_post( "total_document_count", ), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def sync_job_update_stats( self, *, @@ -1086,8 +1087,8 @@ async def sync_job_update_stats( """ .. raw:: html -

    Set the connector sync job stats. - Stats include: deleted_document_count, indexed_document_count, indexed_document_volume, and total_document_count. +

    Set the connector sync job stats.

    +

    Stats include: deleted_document_count, indexed_document_count, indexed_document_volume, and total_document_count. You can also update last_seen. This API is mainly used by the connector service for updating sync job information.

    To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. @@ -1160,7 +1161,7 @@ async def sync_job_update_stats( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def update_active_filtering( self, *, @@ -1207,7 +1208,7 @@ async def update_active_filtering( @_rewrite_parameters( body_fields=("api_key_id", "api_key_secret_id"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def update_api_key_id( self, *, @@ -1269,7 +1270,7 @@ async def update_api_key_id( @_rewrite_parameters( body_fields=("configuration", "values"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def update_configuration( self, *, @@ -1328,7 +1329,7 @@ async def update_configuration( @_rewrite_parameters( body_fields=("error",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def update_error( self, *, @@ -1387,7 +1388,7 @@ async def update_error( @_rewrite_parameters( body_fields=("features",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def update_features( self, *, @@ -1402,8 +1403,8 @@ async def update_features( """ .. raw:: html -

    Update the connector features. - Update the connector features in the connector document. +

    Update the connector features.

    +

    Update the connector features in the connector document. This API can be used to control the following aspects of a connector:

    • document-level security
    • @@ -1455,7 +1456,7 @@ async def update_features( @_rewrite_parameters( body_fields=("advanced_snippet", "filtering", "rules"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def update_filtering( self, *, @@ -1520,7 +1521,7 @@ async def update_filtering( @_rewrite_parameters( body_fields=("validation",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def update_filtering_validation( self, *, @@ -1577,7 +1578,7 @@ async def update_filtering_validation( @_rewrite_parameters( body_fields=("index_name",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def update_index_name( self, *, @@ -1634,7 +1635,7 @@ async def update_index_name( @_rewrite_parameters( body_fields=("description", "name"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def update_name( self, *, @@ -1692,7 +1693,7 @@ async def update_name( @_rewrite_parameters( body_fields=("is_native",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def update_native( self, *, @@ -1748,7 +1749,7 @@ async def update_native( @_rewrite_parameters( body_fields=("pipeline",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def update_pipeline( self, *, @@ -1805,7 +1806,7 @@ async def update_pipeline( @_rewrite_parameters( body_fields=("scheduling",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def update_scheduling( self, *, @@ -1861,7 +1862,7 @@ async def update_scheduling( @_rewrite_parameters( body_fields=("service_type",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def update_service_type( self, *, @@ -1917,7 +1918,7 @@ async def update_service_type( @_rewrite_parameters( body_fields=("status",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def update_status( self, *, diff --git a/elasticsearch/_async/client/dangling_indices.py b/elasticsearch/_async/client/dangling_indices.py index 57289c91a..cc69bb046 100644 --- a/elasticsearch/_async/client/dangling_indices.py +++ b/elasticsearch/_async/client/dangling_indices.py @@ -30,7 +30,7 @@ async def delete_dangling_index( self, *, index_uuid: str, - accept_data_loss: bool, + accept_data_loss: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, @@ -41,8 +41,8 @@ async def delete_dangling_index( """ .. raw:: html -

      Delete a dangling index. - If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. +

      Delete a dangling index.

      +

      If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. For example, this can happen if you delete more than cluster.indices.tombstones.size indices while an Elasticsearch node is offline.

      @@ -52,13 +52,11 @@ async def delete_dangling_index( API to find the UUID. :param accept_data_loss: This parameter must be set to true to acknowledge that it will no longer be possible to recove data from the dangling index. - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit operation timeout + :param master_timeout: The period to wait for a connection to the master node. + :param timeout: The period to wait for a response. """ if index_uuid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index_uuid'") - if accept_data_loss is None: - raise ValueError("Empty value passed for parameter 'accept_data_loss'") __path_parts: t.Dict[str, str] = {"index_uuid": _quote(index_uuid)} __path = f'/_dangling/{__path_parts["index_uuid"]}' __query: t.Dict[str, t.Any] = {} @@ -91,7 +89,7 @@ async def import_dangling_index( self, *, index_uuid: str, - accept_data_loss: bool, + accept_data_loss: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, @@ -116,13 +114,11 @@ async def import_dangling_index( from or determine which shard copies are fresh and which are stale, it cannot guarantee that the imported data represents the latest state of the index when it was last in the cluster. - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit operation timeout + :param master_timeout: The period to wait for a connection to the master node. + :param timeout: The period to wait for a response. """ if index_uuid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index_uuid'") - if accept_data_loss is None: - raise ValueError("Empty value passed for parameter 'accept_data_loss'") __path_parts: t.Dict[str, str] = {"index_uuid": _quote(index_uuid)} __path = f'/_dangling/{__path_parts["index_uuid"]}' __query: t.Dict[str, t.Any] = {} diff --git a/elasticsearch/_async/client/enrich.py b/elasticsearch/_async/client/enrich.py index ae37254ca..19dd27f14 100644 --- a/elasticsearch/_async/client/enrich.py +++ b/elasticsearch/_async/client/enrich.py @@ -39,8 +39,8 @@ async def delete_policy( """ .. raw:: html -

      Delete an enrich policy. - Deletes an existing enrich policy and its enrich index.

      +

      Delete an enrich policy.

      +

      Deletes an existing enrich policy and its enrich index.

      ``_ @@ -88,8 +88,8 @@ async def execute_policy( """ .. raw:: html -

      Run an enrich policy. - Create the enrich index for an existing enrich policy.

      +

      Run an enrich policy.

      +

      Create the enrich index for an existing enrich policy.

      ``_ @@ -140,8 +140,8 @@ async def get_policy( """ .. raw:: html -

      Get an enrich policy. - Returns information about an enrich policy.

      +

      Get an enrich policy.

      +

      Returns information about an enrich policy.

      ``_ @@ -198,8 +198,8 @@ async def put_policy( """ .. raw:: html -

      Create an enrich policy. - Creates an enrich policy.

      +

      Create an enrich policy.

      +

      Creates an enrich policy.

      ``_ @@ -259,8 +259,8 @@ async def stats( """ .. raw:: html -

      Get enrich stats. - Returns enrich coordinator statistics and information about enrich policies that are currently executing.

      +

      Get enrich stats.

      +

      Returns enrich coordinator statistics and information about enrich policies that are currently executing.

      ``_ diff --git a/elasticsearch/_async/client/eql.py b/elasticsearch/_async/client/eql.py index 98ee4f4e8..f734cfdc9 100644 --- a/elasticsearch/_async/client/eql.py +++ b/elasticsearch/_async/client/eql.py @@ -38,8 +38,8 @@ async def delete( """ .. raw:: html -

      Delete an async EQL search. - Delete an async EQL search or a stored synchronous EQL search. +

      Delete an async EQL search.

      +

      Delete an async EQL search or a stored synchronous EQL search. The API also deletes results for the search.

      @@ -89,8 +89,8 @@ async def get( """ .. raw:: html -

      Get async EQL search results. - Get the current status and available results for an async EQL search or a stored synchronous EQL search.

      +

      Get async EQL search results.

      +

      Get the current status and available results for an async EQL search or a stored synchronous EQL search.

      ``_ @@ -143,8 +143,8 @@ async def get_status( """ .. raw:: html -

      Get the async EQL status. - Get the current status for an async EQL search or a stored synchronous EQL search without returning results.

      +

      Get the async EQL status.

      +

      Get the current status for an async EQL search or a stored synchronous EQL search without returning results.

      ``_ @@ -242,14 +242,14 @@ async def search( """ .. raw:: html -

      Get EQL search results. - Returns search results for an Event Query Language (EQL) query. +

      Get EQL search results.

      +

      Returns search results for an Event Query Language (EQL) query. EQL assumes each document in a data stream or index corresponds to an event.

      ``_ - :param index: The name of the index to scope the operation + :param index: Comma-separated list of index names to scope the operation :param query: EQL query you wish to run. :param allow_no_indices: Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices @@ -291,7 +291,7 @@ async def search( Defaults to 10 :param tiebreaker_field: Field used to sort hits with the same timestamp in ascending order - :param timestamp_field: Field containing event timestamp. Default "@timestamp" + :param timestamp_field: Field containing event timestamp. :param wait_for_completion_timeout: """ if index in SKIP_IN_PATH: diff --git a/elasticsearch/_async/client/esql.py b/elasticsearch/_async/client/esql.py index 9999f1db1..5e31d3c17 100644 --- a/elasticsearch/_async/client/esql.py +++ b/elasticsearch/_async/client/esql.py @@ -23,11 +23,14 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) +if t.TYPE_CHECKING: + from ...esql import ESQLBase + class EsqlClient(NamespacedClient): @@ -50,7 +53,7 @@ class EsqlClient(NamespacedClient): async def async_query( self, *, - query: t.Optional[str] = None, + query: t.Optional[t.Union[str, "ESQLBase"]] = None, allow_partial_results: t.Optional[bool] = None, columnar: t.Optional[bool] = None, delimiter: t.Optional[str] = None, @@ -85,8 +88,8 @@ async def async_query( """ .. raw:: html -

      Run an async ES|QL query. - Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.

      +

      Run an async ES|QL query.

      +

      Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.

      The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.

      @@ -111,7 +114,12 @@ async def async_query( which has the name of all the columns. :param filter: Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on. - :param format: A short version of the Accept header, for example `json` or `yaml`. + :param format: A short version of the Accept header, e.g. json, yaml. `csv`, + `tsv`, and `txt` formats will return results in a tabular format, excluding + other metadata fields from the response. For async requests, nothing will + be returned if the async query doesn't finish within the timeout. The query + ID and running status are available in the `X-Elasticsearch-Async-Id` and + `X-Elasticsearch-Async-Is-Running` HTTP headers of the response, respectively. :param include_ccs_metadata: When set to `true` and performing a cross-cluster query, the response will include an extra `_clusters` object with information about the clusters that participated in the search along with info such as @@ -165,7 +173,7 @@ async def async_query( __query["pretty"] = pretty if not __body: if query is not None: - __body["query"] = query + __body["query"] = str(query) if columnar is not None: __body["columnar"] = columnar if filter is not None: @@ -210,8 +218,8 @@ async def async_query_delete( """ .. raw:: html -

      Delete an async ES|QL query. - If the query is still running, it is cancelled. +

      Delete an async ES|QL query.

      +

      If the query is still running, it is cancelled. Otherwise, the stored results are deleted.

      If the Elasticsearch security features are enabled, only the following users can use this API to delete a query:

        @@ -276,8 +284,8 @@ async def async_query_get( """ .. raw:: html -

        Get async ES|QL query results. - Get the current status and available results or stored results for an ES|QL asynchronous query. +

        Get async ES|QL query results.

        +

        Get the current status and available results or stored results for an ES|QL asynchronous query. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API.

        @@ -388,7 +396,7 @@ async def async_query_stop( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def get_query( self, *, @@ -401,10 +409,12 @@ async def get_query( """ .. raw:: html -

        Get a specific running ES|QL query information. - Returns an object extended information about a running ES|QL query.

        +

        Get a specific running ES|QL query information.

        +

        Returns an object extended information about a running ES|QL query.

        + ``_ + :param id: The query ID """ if id in SKIP_IN_PATH: @@ -431,7 +441,7 @@ async def get_query( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def list_queries( self, *, @@ -443,9 +453,11 @@ async def list_queries( """ .. raw:: html -

        Get running ES|QL queries information. - Returns an object containing IDs and other information about the running ES|QL queries.

        +

        Get running ES|QL queries information.

        +

        Returns an object containing IDs and other information about the running ES|QL queries.

        + + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_query/queries" @@ -484,7 +496,7 @@ async def list_queries( async def query( self, *, - query: t.Optional[str] = None, + query: t.Optional[t.Union[str, "ESQLBase"]] = None, allow_partial_results: t.Optional[bool] = None, columnar: t.Optional[bool] = None, delimiter: t.Optional[str] = None, @@ -514,8 +526,8 @@ async def query( """ .. raw:: html -

        Run an ES|QL query. - Get search results for an ES|QL (Elasticsearch query language) query.

        +

        Run an ES|QL query.

        +

        Get search results for an ES|QL (Elasticsearch query language) query.

        ``_ @@ -539,7 +551,9 @@ async def query( `all_columns` which has the name of all columns. :param filter: Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on. - :param format: A short version of the Accept header, e.g. json, yaml. + :param format: A short version of the Accept header, e.g. json, yaml. `csv`, + `tsv`, and `txt` formats will return results in a tabular format, excluding + other metadata fields from the response. :param include_ccs_metadata: When set to `true` and performing a cross-cluster query, the response will include an extra `_clusters` object with information about the clusters that participated in the search along with info such as @@ -579,7 +593,7 @@ async def query( __query["pretty"] = pretty if not __body: if query is not None: - __body["query"] = query + __body["query"] = str(query) if columnar is not None: __body["columnar"] = columnar if filter is not None: diff --git a/elasticsearch/_async/client/features.py b/elasticsearch/_async/client/features.py index 2fb86fe23..7dec9cf73 100644 --- a/elasticsearch/_async/client/features.py +++ b/elasticsearch/_async/client/features.py @@ -20,7 +20,7 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import Stability, _rewrite_parameters, _stability_warning +from .utils import Stability, _availability_warning, _rewrite_parameters class FeaturesClient(NamespacedClient): @@ -38,8 +38,8 @@ async def get_features( """ .. raw:: html -

        Get the features. - Get a list of features that can be included in snapshots using the feature_states field when creating a snapshot. +

        Get the features.

        +

        Get a list of features that can be included in snapshots using the feature_states field when creating a snapshot. You can use this API to determine which feature states to include when taking a snapshot. By default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.

        A feature state includes one or more system indices necessary for a given feature to function. @@ -76,7 +76,7 @@ async def get_features( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def reset_features( self, *, @@ -89,8 +89,8 @@ async def reset_features( """ .. raw:: html -

        Reset the features. - Clear all of the state information stored in system indices by Elasticsearch features, including the security and machine learning indices.

        +

        Reset the features.

        +

        Clear all of the state information stored in system indices by Elasticsearch features, including the security and machine learning indices.

        WARNING: Intended for development and testing use only. Do not reset features on a production cluster.

        Return a cluster to the same state as a new installation by resetting the feature state for all Elasticsearch features. This deletes all state information stored in system indices.

        diff --git a/elasticsearch/_async/client/fleet.py b/elasticsearch/_async/client/fleet.py index f1ea60007..27d68fb41 100644 --- a/elasticsearch/_async/client/fleet.py +++ b/elasticsearch/_async/client/fleet.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -101,7 +101,7 @@ async def global_checkpoints( @_rewrite_parameters( body_name="searches", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def msearch( self, *, @@ -138,8 +138,8 @@ async def msearch( """ .. raw:: html -

        Run multiple Fleet searches. - Run several Fleet searches with a single API request. +

        Run multiple Fleet searches.

        +

        Run several Fleet searches with a single API request. The API follows the same structure as the multi search API. However, similar to the Fleet search API, it supports the wait_for_checkpoints parameter.

        @@ -293,7 +293,7 @@ async def msearch( "from": "from_", }, ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def search( self, *, @@ -388,8 +388,8 @@ async def search( """ .. raw:: html -

        Run a Fleet search. - The purpose of the Fleet search API is to provide an API where the search will be run only +

        Run a Fleet search.

        +

        The purpose of the Fleet search API is to provide an API where the search will be run only after the provided checkpoint has been processed and is visible for searches inside of Elasticsearch.

        @@ -642,11 +642,7 @@ async def search( __body["track_total_hits"] = track_total_hits if version is not None: __body["version"] = version - 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, diff --git a/elasticsearch/_async/client/graph.py b/elasticsearch/_async/client/graph.py index a8c35dbfe..ad4ce8a80 100644 --- a/elasticsearch/_async/client/graph.py +++ b/elasticsearch/_async/client/graph.py @@ -47,8 +47,8 @@ async def explore( """ .. raw:: html -

        Explore graph analytics. - Extract and summarize information about the documents and terms in an Elasticsearch data stream or index. +

        Explore graph analytics.

        +

        Extract and summarize information about the documents and terms in an Elasticsearch data stream or index. The easiest way to understand the behavior of this API is to use the Graph UI to explore connections. An initial request to the _explore API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph. Subsequent requests enable you to spider out from one more vertices of interest. @@ -97,11 +97,7 @@ async def explore( __body["query"] = query if vertices is not None: __body["vertices"] = vertices - 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, diff --git a/elasticsearch/_async/client/ilm.py b/elasticsearch/_async/client/ilm.py index c15aaa807..e0784f194 100644 --- a/elasticsearch/_async/client/ilm.py +++ b/elasticsearch/_async/client/ilm.py @@ -40,8 +40,8 @@ async def delete_lifecycle( """ .. raw:: html -

        Delete a lifecycle policy. - You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.

        +

        Delete a lifecycle policy.

        +

        You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.

        ``_ @@ -96,8 +96,8 @@ async def explain_lifecycle( """ .. raw:: html -

        Explain the lifecycle state. - Get the current lifecycle status for one or more indices. +

        Explain the lifecycle state.

        +

        Get the current lifecycle status for one or more indices. For data streams, the API retrieves the current lifecycle status for the stream's backing indices.

        The response indicates when the index entered each lifecycle state, provides the definition of the running phase, and information about any failures.

        @@ -260,8 +260,8 @@ async def migrate_to_data_tiers( """ .. raw:: html -

        Migrate to data tiers routing. - Switch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers. +

        Migrate to data tiers routing.

        +

        Switch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers. Optionally, delete one legacy index template. Using node roles enables ILM to automatically move the indices between data tiers.

        Migrating away from custom node attributes routing can be manually performed. @@ -341,8 +341,8 @@ async def move_to_step( """ .. raw:: html -

        Move to a lifecycle step. - Manually move an index into a specific step in the lifecycle policy and run that step.

        +

        Move to a lifecycle step.

        +

        Manually move an index into a specific step in the lifecycle policy and run that step.

        WARNING: This operation can result in the loss of data. Manually moving an index into a specific step runs that step even if it has already been performed. This is a potentially destructive action and this should be considered an expert level API.

        You must specify both the current step and the step to be executed in the body of the request. The request will fail if the current step does not match the step currently running for the index @@ -383,11 +383,7 @@ async def move_to_step( __body["current_step"] = current_step if next_step is not None: __body["next_step"] = next_step - 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, @@ -417,8 +413,8 @@ async def put_lifecycle( """ .. raw:: html -

        Create or update a lifecycle policy. - If the specified policy exists, it is replaced and the policy version is incremented.

        +

        Create or update a lifecycle policy.

        +

        If the specified policy exists, it is replaced and the policy version is incremented.

        NOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.

        @@ -453,11 +449,7 @@ async def put_lifecycle( if not __body: if policy is not None: __body["policy"] = policy - 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] "PUT", __path, @@ -481,8 +473,8 @@ async def remove_policy( """ .. raw:: html -

        Remove policies from an index. - Remove the assigned lifecycle policies from an index or a data stream's backing indices. +

        Remove policies from an index.

        +

        Remove the assigned lifecycle policies from an index or a data stream's backing indices. It also stops managing the indices.

        @@ -526,8 +518,8 @@ async def retry( """ .. raw:: html -

        Retry a policy. - Retry running the lifecycle policy for an index that is in the ERROR step. +

        Retry a policy.

        +

        Retry running the lifecycle policy for an index that is in the ERROR step. The API sets the policy back to the step where the error occurred and runs the step. Use the explain lifecycle state API to determine whether an index is in the ERROR step.

        @@ -574,8 +566,8 @@ async def start( """ .. raw:: html -

        Start the ILM plugin. - Start the index lifecycle management plugin if it is currently stopped. +

        Start the ILM plugin.

        +

        Start the index lifecycle management plugin if it is currently stopped. ILM is started automatically when the cluster is formed. Restarting ILM is necessary only when it has been stopped using the stop ILM API.

        @@ -627,8 +619,8 @@ async def stop( """ .. raw:: html -

        Stop the ILM plugin. - Halt all lifecycle management operations and stop the index lifecycle management plugin. +

        Stop the ILM plugin.

        +

        Halt all lifecycle management operations and stop the index lifecycle management plugin. This is useful when you are performing maintenance on the cluster and need to prevent ILM from performing any actions on your indices.

        The API returns as soon as the stop request has been acknowledged, but the plugin might continue to run until in-progress operations complete and the plugin can be safely stopped. Use the get ILM status API to check whether ILM is running.

        diff --git a/elasticsearch/_async/client/indices.py b/elasticsearch/_async/client/indices.py index 2a40027c2..c3fab8b84 100644 --- a/elasticsearch/_async/client/indices.py +++ b/elasticsearch/_async/client/indices.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -165,8 +165,8 @@ async def analyze( """ .. raw:: html -

        Get tokens from text analysis. - The analyze API performs analysis on a text string and returns the resulting tokens.

        +

        Get tokens from text analysis.

        +

        The analyze API performs analysis on a text string and returns the resulting tokens.

        Generating excessive amount of tokens may cause a node to run out of memory. The index.analyze.max_token_count setting enables you to limit the number of tokens that can be produced. If more than this limit of tokens gets generated, an error occurs. @@ -232,11 +232,7 @@ async def analyze( __body["text"] = text if tokenizer is not None: __body["tokenizer"] = tokenizer - 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, @@ -248,7 +244,7 @@ async def analyze( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def cancel_migrate_reindex( self, *, @@ -319,8 +315,8 @@ async def clear_cache( """ .. raw:: html -

        Clear the cache. - Clear the cache of one or more indices. +

        Clear the cache.

        +

        Clear the cache of one or more indices. For data streams, the API clears the caches of the stream's backing indices.

        By default, the clear cache API clears all caches. To clear only specific caches, use the fielddata, query, or request parameters. @@ -412,8 +408,8 @@ async def clone( """ .. raw:: html -

        Clone an index. - Clone an existing index into a new index. +

        Clone an index.

        +

        Clone an existing index into a new index. Each original primary shard is cloned into a new primary shard in the new index.

        IMPORTANT: Elasticsearch does not apply index templates to the resulting index. The API also does not copy index metadata from the original index. @@ -537,8 +533,8 @@ async def close( """ .. raw:: html -

        Close an index. - A closed index is blocked for read or write operations and does not allow all operations that opened indices allow. +

        Close an index.

        +

        A closed index is blocked for read or write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. Closed indices do not have to maintain internal data structures for indexing or searching documents, which results in a smaller overhead on the cluster.

        When opening or closing an index, the master node is responsible for restarting the index shards to reflect the new state of the index. @@ -634,8 +630,8 @@ async def create( """ .. raw:: html -

        Create an index. - You can use the create index API to add a new index to an Elasticsearch cluster. +

        Create an index.

        +

        You can use the create index API to add a new index to an Elasticsearch cluster. When creating an index, you can specify the following:

        • Settings for the index.
        • @@ -782,7 +778,7 @@ async def create_data_stream( @_rewrite_parameters( body_name="create_from", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def create_from( self, *, @@ -812,11 +808,7 @@ async def create_from( raise ValueError("Empty value passed for parameter 'source'") if dest in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'dest'") - if create_from is None and body is None: - raise ValueError( - "Empty value passed for parameters 'create_from' and 'body', one of them should be set." - ) - elif create_from is not None and body is not None: + if create_from is not None and body is not None: raise ValueError("Cannot set both 'create_from' and 'body'") __path_parts: t.Dict[str, str] = { "source": _quote(source), @@ -833,7 +825,11 @@ async def create_from( if pretty is not None: __query["pretty"] = pretty __body = create_from if create_from is not None else body - __headers = {"accept": "application/json", "content-type": "application/json"} + if not __body: + __body = None + __headers = {"accept": "application/json"} + if __body is not None: + __headers["content-type"] = "application/json" return await self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -930,8 +926,8 @@ async def delete( """ .. raw:: html -

          Delete indices. - Deleting an index deletes its documents, shards, and metadata. +

          Delete indices.

          +

          Deleting an index deletes its documents, shards, and metadata. It does not delete related Kibana components, such as data views, visualizations, or dashboards.

          You cannot delete the current write index of a data stream. To delete the index, you must roll over the data stream so a new write index is created. @@ -1008,8 +1004,8 @@ async def delete_alias( """ .. raw:: html -

          Delete an alias. - Removes a data stream or index from an alias.

          +

          Delete an alias.

          +

          Removes a data stream or index from an alias.

          ``_ @@ -1076,18 +1072,18 @@ async def delete_data_lifecycle( """ .. raw:: html -

          Delete data stream lifecycles. - Removes the data stream lifecycle from a data stream, rendering it not managed by the data stream lifecycle.

          +

          Delete data stream lifecycles.

          +

          Removes the data stream lifecycle from a data stream, rendering it not managed by the data stream lifecycle.

          ``_ :param name: A comma-separated list of data streams of which the data stream - lifecycle will be deleted; use `*` to get all data streams + lifecycle will be deleted. Use `*` to get all data streams :param expand_wildcards: Whether wildcard expressions should get expanded to open or closed indices (default: open) - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit timestamp for the document + :param master_timeout: The period to wait for a connection to the master node. + :param timeout: The period to wait for a response. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -1140,8 +1136,8 @@ async def delete_data_stream( """ .. raw:: html -

          Delete data streams. - Deletes one or more data streams and their backing indices.

          +

          Delete data streams.

          +

          Deletes one or more data streams and their backing indices.

          ``_ @@ -1204,18 +1200,18 @@ async def delete_data_stream_options( """ .. raw:: html -

          Delete data stream options. - Removes the data stream options from a data stream.

          +

          Delete data stream options.

          +

          Removes the data stream options from a data stream.

          - ``_ + ``_ :param name: A comma-separated list of data streams of which the data stream - options will be deleted; use `*` to get all data streams + options will be deleted. Use `*` to get all data streams :param expand_wildcards: Whether wildcard expressions should get expanded to - open or closed indices (default: open) - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit timestamp for the document + open or closed indices + :param master_timeout: The period to wait for a connection to the master node. + :param timeout: The period to wait for a response. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -1261,8 +1257,8 @@ async def delete_index_template( """ .. raw:: html -

          Delete an index template. - The provided may contain multiple template names separated by a comma. If multiple template +

          Delete an index template.

          +

          The provided may contain multiple template names separated by a comma. If multiple template names are specified then there is no wildcard support and the provided names should match completely with existing templates.

          @@ -1319,8 +1315,8 @@ async def delete_template( """ .. raw:: html -

          Delete a legacy index template. - IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

          +

          Delete a legacy index template.

          +

          IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

          ``_ @@ -1361,7 +1357,7 @@ async def delete_template( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def disk_usage( self, *, @@ -1386,8 +1382,8 @@ async def disk_usage( """ .. raw:: html -

          Analyze the index disk usage. - Analyze the disk usage of each field of an index or data stream. +

          Analyze the index disk usage.

          +

          Analyze the disk usage of each field of an index or data stream. This API might not support indices created in previous Elasticsearch versions. The result of a small index can be inaccurate as some parts of an index might not be analyzed by the API.

          NOTE: The total size of fields of the analyzed shards of the index in the response is usually smaller than the index store_size value because some small metadata files are ignored and some parts of data files might not be scanned by the API. @@ -1453,7 +1449,7 @@ async def disk_usage( @_rewrite_parameters( body_name="config", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def downsample( self, *, @@ -1469,8 +1465,8 @@ async def downsample( """ .. raw:: html -

          Downsample an index. - Aggregate a time series (TSDS) index and store pre-computed statistical summaries (min, max, sum, value_count and avg) for each metric field grouped by a configured time interval. +

          Downsample an index.

          +

          Aggregate a time series (TSDS) index and store pre-computed statistical summaries (min, max, sum, value_count and avg) for each metric field grouped by a configured time interval. For example, a TSDS index that contains metrics sampled every 10 seconds can be downsampled to an hourly index. All documents within an hour interval are summarized and stored as a single document in the downsample index.

          NOTE: Only indices in a time series data stream are supported. @@ -1546,8 +1542,8 @@ async def exists( """ .. raw:: html -

          Check indices. - Check if one or more indices, index aliases, or data streams exist.

          +

          Check indices.

          +

          Check if one or more indices, index aliases, or data streams exist.

          ``_ @@ -1766,8 +1762,8 @@ async def exists_template( """ .. raw:: html -

          Check existence of index templates. - Get information about whether index templates exist. +

          Check existence of index templates.

          +

          Get information about whether index templates exist. Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

          IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

          @@ -1826,16 +1822,16 @@ async def explain_data_lifecycle( """ .. raw:: html -

          Get the status for a data stream lifecycle. - Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.

          +

          Get the status for a data stream lifecycle.

          +

          Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.

          ``_ - :param index: The name of the index to explain - :param include_defaults: indicates if the API should return the default values + :param index: Comma-separated list of index names to explain + :param include_defaults: Indicates if the API should return the default values the system uses for the index's lifecycle - :param master_timeout: Specify timeout for connection to master + :param master_timeout: The period to wait for a connection to the master node. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1865,7 +1861,7 @@ async def explain_data_lifecycle( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def field_usage_stats( self, *, @@ -1889,8 +1885,8 @@ async def field_usage_stats( """ .. raw:: html -

          Get field usage stats. - Get field usage information for each shard and field of an index. +

          Get field usage stats.

          +

          Get field usage information for each shard and field of an index. Field usage statistics are automatically captured when queries are running on a cluster. A shard-level search request that accesses a given field, even if multiple times during that request, is counted as a single use.

          The response body reports the per-shard usage count of the data structures that back the fields in the index. @@ -1971,8 +1967,8 @@ async def flush( """ .. raw:: html -

          Flush data streams or indices. - Flushing a data stream or index is the process of making sure that any data that is currently only stored in the transaction log is also permanently stored in the Lucene index. +

          Flush data streams or indices.

          +

          Flushing a data stream or index is the process of making sure that any data that is currently only stored in the transaction log is also permanently stored in the Lucene index. When restarting, Elasticsearch replays any unflushed operations from the transaction log into the Lucene index to bring it back into the state that it was in before the restart. Elasticsearch automatically triggers flushes as needed, using heuristics that trade off the size of the unflushed transaction log against the cost of performing each flush.

          After each operation has been flushed it is permanently stored in the Lucene index. @@ -2065,8 +2061,8 @@ async def forcemerge( """ .. raw:: html -

          Force a merge. - Perform the force merge operation on the shards of one or more indices. +

          Force a merge.

          +

          Perform the force merge operation on the shards of one or more indices. For data streams, the API forces a merge on the shards of the stream's backing indices.

          Merging reduces the number of segments in each shard by merging some of them together and also frees up the space used by deleted documents. Merging normally happens automatically, but sometimes it is useful to trigger a merge manually.

          @@ -2117,15 +2113,15 @@ async def forcemerge( :param expand_wildcards: Whether to expand wildcard expression to concrete indices that are open, closed or both. :param flush: Specify whether the index should be flushed after performing the - operation (default: true) + operation :param ignore_unavailable: Whether specified concrete indices should be ignored when unavailable (missing or closed) :param max_num_segments: The number of segments the index should be merged into - (default: dynamic) + (defayult: dynamic) :param only_expunge_deletes: Specify whether the operation should only expunge deleted documents :param wait_for_completion: Should the request wait until the force merge is - completed. + completed """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -2200,8 +2196,8 @@ async def get( """ .. raw:: html -

          Get index information. - Get information about one or more indices. For data streams, the API returns information about the +

          Get index information.

          +

          Get information about one or more indices. For data streams, the API returns information about the stream’s backing indices.

          @@ -2294,8 +2290,8 @@ async def get_alias( """ .. raw:: html -

          Get aliases. - Retrieves information for one or more data stream or index aliases.

          +

          Get aliases.

          +

          Retrieves information for one or more data stream or index aliases.

          ``_ @@ -2438,8 +2434,8 @@ async def get_data_lifecycle_stats( """ .. raw:: html -

          Get data stream lifecycle stats. - Get statistics about the data streams that are managed by a data stream lifecycle.

          +

          Get data stream lifecycle stats.

          +

          Get statistics about the data streams that are managed by a data stream lifecycle.

          ``_ @@ -2542,57 +2538,6 @@ async def get_data_stream( path_parts=__path_parts, ) - @_rewrite_parameters() - async def get_data_stream_mappings( - self, - *, - name: t.Union[str, t.Sequence[str]], - 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]: - """ - .. raw:: html - -

          Get data stream mappings.

          -

          Get mapping information for one or more data streams.

          - - - ``_ - - :param name: A comma-separated list of data streams or data stream patterns. - Supports wildcards (`*`). - :param master_timeout: The 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'") - __path_parts: t.Dict[str, str] = {"name": _quote(name)} - __path = f'/_data_stream/{__path_parts["name"]}/_mappings' - __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 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"} - return await self.perform_request( # type: ignore[return-value] - "GET", - __path, - params=__query, - headers=__headers, - endpoint_id="indices.get_data_stream_mappings", - path_parts=__path_parts, - ) - @_rewrite_parameters() async def get_data_stream_options( self, @@ -2619,7 +2564,7 @@ async def get_data_stream_options(

          Get the data stream options configuration of one or more data streams.

          - ``_ + ``_ :param name: Comma-separated list of data streams to limit the request. Supports wildcards (`*`). To target all data streams, omit this parameter or use `*` @@ -2733,8 +2678,8 @@ async def get_field_mapping( """ .. raw:: html -

          Get mapping definitions. - Retrieves mapping definitions for one or more fields. +

          Get mapping definitions.

          +

          Retrieves mapping definitions for one or more fields. For data streams, the API retrieves field mappings for the stream’s backing indices.

          This API is useful if you don't need a complete mapping or if an index mapping contains a large number of fields.

          @@ -2812,14 +2757,14 @@ async def get_index_template( """ .. raw:: html -

          Get index templates. - Get information about one or more index templates.

          +

          Get index templates.

          +

          Get information about one or more index templates.

          ``_ - :param name: Comma-separated list of index template names used to limit the request. - Wildcard (*) expressions are supported. + :param name: Name of index template to retrieve. Wildcard (*) expressions are + supported. :param flat_settings: If true, returns settings in flat format. :param include_defaults: If true, returns all relevant default configurations for the index template. @@ -2889,8 +2834,8 @@ async def get_mapping( """ .. raw:: html -

          Get mapping definitions. - For data streams, the API retrieves mappings for the stream’s backing indices.

          +

          Get mapping definitions.

          +

          For data streams, the API retrieves mappings for the stream’s backing indices.

          ``_ @@ -2950,7 +2895,7 @@ async def get_mapping( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def get_migrate_reindex_status( self, *, @@ -3022,8 +2967,8 @@ async def get_settings( """ .. raw:: html -

          Get index settings. - Get setting information for one or more indices. +

          Get index settings.

          +

          Get setting information for one or more indices. For data streams, it returns setting information for the stream's backing indices.

          @@ -3114,8 +3059,8 @@ async def get_template( """ .. raw:: html -

          Get legacy index templates. - Get information about one or more index templates.

          +

          Get legacy index templates.

          +

          Get information about one or more index templates.

          IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

          @@ -3166,7 +3111,7 @@ async def get_template( @_rewrite_parameters( body_name="reindex", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def migrate_reindex( self, *, @@ -3234,8 +3179,8 @@ async def migrate_to_data_stream( """ .. raw:: html -

          Convert an index alias to a data stream. - Converts an index alias to a data stream. +

          Convert an index alias to a data stream.

          +

          Converts an index alias to a data stream. You must have a matching index template that is data stream enabled. The alias must meet the following criteria: The alias must have a write index; @@ -3299,8 +3244,8 @@ async def modify_data_stream( """ .. raw:: html -

          Update data streams. - Performs one or more data stream modification actions in a single atomic operation.

          +

          Update data streams.

          +

          Performs one or more data stream modification actions in a single atomic operation.

          ``_ @@ -3363,8 +3308,8 @@ async def open( """ .. raw:: html -

          Open a closed index. - For data streams, the API opens any closed backing indices.

          +

          Open a closed index.

          +

          For data streams, the API opens any closed backing indices.

          A closed index is blocked for read/write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. This allows closed indices to not have to maintain internal data structures for indexing or searching documents, resulting in a smaller overhead on the cluster.

          @@ -3457,8 +3402,8 @@ async def promote_data_stream( """ .. raw:: html -

          Promote a data stream. - Promote a data stream from a replicated data stream managed by cross-cluster replication (CCR) to a regular data stream.

          +

          Promote a data stream.

          +

          Promote a data stream from a replicated data stream managed by cross-cluster replication (CCR) to a regular data stream.

          With CCR auto following, a data stream from a remote cluster can be replicated to the local cluster. These data streams can't be rolled over in the local cluster. These replicated data streams roll over only if the upstream data stream rolls over. @@ -3470,7 +3415,7 @@ async def promote_data_stream( ``_ - :param name: The name of the data stream + :param name: The name of the data stream to promote :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. @@ -3530,8 +3475,8 @@ async def put_alias( """ .. raw:: html -

          Create or update an alias. - Adds a data stream or index to an alias.

          +

          Create or update an alias.

          +

          Adds a data stream or index to an alias.

          ``_ @@ -3616,7 +3561,7 @@ async def put_data_lifecycle( *, name: t.Union[str, t.Sequence[str]], data_retention: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, - downsampling: t.Optional[t.Mapping[str, t.Any]] = None, + downsampling: t.Optional[t.Sequence[t.Mapping[str, t.Any]]] = None, enabled: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, expand_wildcards: t.Optional[ @@ -3637,8 +3582,8 @@ async def put_data_lifecycle( """ .. raw:: html -

          Update data stream lifecycles. - Update the data stream lifecycle of the specified data streams.

          +

          Update data stream lifecycles.

          +

          Update the data stream lifecycle of the specified data streams.

          ``_ @@ -3689,87 +3634,6 @@ async def put_data_lifecycle( __body["downsampling"] = downsampling if enabled is not None: __body["enabled"] = enabled - if not __body: - __body = None # type: ignore[assignment] - __headers = {"accept": "application/json"} - if __body is not None: - __headers["content-type"] = "application/json" - return await self.perform_request( # type: ignore[return-value] - "PUT", - __path, - params=__query, - headers=__headers, - body=__body, - endpoint_id="indices.put_data_lifecycle", - path_parts=__path_parts, - ) - - @_rewrite_parameters( - body_name="mappings", - ) - async def put_data_stream_mappings( - self, - *, - name: t.Union[str, t.Sequence[str]], - mappings: t.Optional[t.Mapping[str, t.Any]] = None, - body: t.Optional[t.Mapping[str, t.Any]] = None, - dry_run: t.Optional[bool] = None, - 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]: - """ - .. raw:: html - -

          Update data stream mappings.

          -

          This API can be used to override mappings on specific data streams. These overrides will take precedence over what - is specified in the template that the data stream matches. The mapping change is only applied to new write indices - that are created during rollover after this API is called. No indices are changed by this API.

          - - - ``_ - - :param name: A comma-separated list of data streams or data stream patterns. - :param mappings: - :param dry_run: If `true`, the request does not actually change the mappings - on any data streams. Instead, it simulates changing the settings and reports - back to the user what would have happened had these settings actually been - applied. - :param master_timeout: The 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: The 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'") - if mappings is None and body is None: - raise ValueError( - "Empty value passed for parameters 'mappings' and 'body', one of them should be set." - ) - elif mappings is not None and body is not None: - raise ValueError("Cannot set both 'mappings' and 'body'") - __path_parts: t.Dict[str, str] = {"name": _quote(name)} - __path = f'/_data_stream/{__path_parts["name"]}/_mappings' - __query: t.Dict[str, t.Any] = {} - if dry_run is not None: - __query["dry_run"] = dry_run - if error_trace is not None: - __query["error_trace"] = error_trace - if filter_path is not None: - __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 = mappings if mappings is not None else body __headers = {"accept": "application/json", "content-type": "application/json"} return await self.perform_request( # type: ignore[return-value] "PUT", @@ -3777,7 +3641,7 @@ async def put_data_stream_mappings( params=__query, headers=__headers, body=__body, - endpoint_id="indices.put_data_stream_mappings", + endpoint_id="indices.put_data_lifecycle", path_parts=__path_parts, ) @@ -3808,11 +3672,11 @@ async def put_data_stream_options( """ .. raw:: html -

          Update data stream options. - Update the data stream options of the specified data streams.

          +

          Update data stream options.

          +

          Update the data stream options of the specified data streams.

          - ``_ + ``_ :param name: Comma-separated list of data streams used to limit the request. Supports wildcards (`*`). To target all data streams use `*` or `_all`. @@ -3849,11 +3713,7 @@ async def put_data_stream_options( if not __body: if failure_store is not None: __body["failure_store"] = failure_store - 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] "PUT", __path, @@ -3983,8 +3843,8 @@ async def put_index_template( """ .. raw:: html -

          Create or update an index template. - Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

          +

          Create or update an index template.

          +

          Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

          Elasticsearch applies templates to new indices based on an wildcard pattern that matches the index name. Index templates are applied during data stream or index creation. For data streams, these settings and mappings are applied when the stream's backing indices are created. @@ -4015,7 +3875,7 @@ async def put_index_template( via `actions.auto_create_index`. If set to `false`, then indices or data streams matching the template must always be explicitly created, and may never be automatically created. - :param cause: User defined reason for creating/updating the index template + :param cause: User defined reason for creating or updating the index template :param composed_of: An ordered list of component template names. Component templates are merged in the order specified, meaning that the last component template specified has the highest precedence. @@ -4167,8 +4027,8 @@ async def put_mapping( """ .. raw:: html -

          Update field mappings. - Add new fields to an existing data stream or index. +

          Update field mappings.

          +

          Add new fields to an existing data stream or index. You can use the update mapping API to:

          • Add a new field to an existing index
          • @@ -4179,13 +4039,13 @@ async def put_mapping(
          • Change a field's mapping using reindexing
          • Rename a field using a field alias
          -

          Learn how to use the update mapping API with practical examples in the Update mapping API examples guide.

          +

          Learn how to use the update mapping API with practical examples in the Update mapping API examples guide.

          ``_ :param index: A comma-separated list of index names the mapping should be added - to (supports wildcards); use `_all` or omit to add the mapping on all indices. + to (supports wildcards). Use `_all` or omit to add the mapping on all indices. :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. @@ -4312,8 +4172,8 @@ async def put_settings( """ .. raw:: html -

          Update index settings. - Changes dynamic index settings in real time. +

          Update index settings.

          +

          Changes dynamic index settings in real time. For data streams, index setting changes are applied to all backing indices by default.

          To revert a setting to the default value, use a null value. The list of per-index settings that can be updated dynamically on live indices can be found in index settings documentation. @@ -4466,8 +4326,8 @@ async def put_template( """ .. raw:: html -

          Create or update a legacy index template. - Index templates define settings, mappings, and aliases that can be applied automatically to new indices. +

          Create or update a legacy index template.

          +

          Index templates define settings, mappings, and aliases that can be applied automatically to new indices. Elasticsearch applies templates to new indices based on an index pattern that matches the index name.

          IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

          Composable templates always take precedence over legacy templates. @@ -4487,7 +4347,7 @@ async def put_template( :param name: The name of the template :param aliases: Aliases for the index. - :param cause: User defined reason for creating/updating the index template + :param cause: User defined reason for creating or updating the index template :param create: If true, this request cannot replace or update existing index templates. :param index_patterns: Array of wildcard expressions used to match the names @@ -4574,8 +4434,8 @@ async def recovery( """ .. raw:: html -

          Get index recovery information. - Get information about ongoing and completed shard recoveries for one or more indices. +

          Get index recovery information.

          +

          Get information about ongoing and completed shard recoveries for one or more indices. For data streams, the API returns information for the stream's backing indices.

          All recoveries, whether ongoing or complete, are kept in the cluster state and may be reported on at any time.

          Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or creating a replica shard from a primary shard. @@ -4672,11 +4532,12 @@ async def refresh( """ .. raw:: html -

          Refresh an index. - A refresh makes recent operations performed on one or more indices available for search. +

          Refresh an index.

          +

          A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.

          By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds. You can change this default interval with the index.refresh_interval setting.

          +

          In Elastic Cloud Serverless, the default refresh interval is 5 seconds across all indices.

          Refresh requests are synchronous and do not return a response until the refresh operation completes.

          Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.

          @@ -4755,8 +4616,8 @@ async def reload_search_analyzers( """ .. raw:: html -

          Reload search analyzers. - Reload an index's search analyzers and their resources. +

          Reload search analyzers.

          +

          Reload an index's search analyzers and their resources. For data streams, the API reloads search analyzers and resources for the stream's backing indices.

          IMPORTANT: After reloading the search analyzers you should clear the request cache to make sure it doesn't contain responses derived from the previous versions of the analyzer.

          You can use the reload search analyzers API to pick up changes to synonym files used in the synonym_graph or synonym token filter of a search analyzer. @@ -5070,8 +4931,8 @@ async def resolve_index( """ .. raw:: html -

          Resolve indices. - Resolve the names and/or index patterns for indices, aliases, and data streams. +

          Resolve indices.

          +

          Resolve the names and/or index patterns for indices, aliases, and data streams. Multiple patterns and remote clusters are supported.

          @@ -5149,8 +5010,8 @@ async def rollover( """ .. raw:: html -

          Roll over to a new index. - TIP: It is recommended to use the index lifecycle rollover action to automate rollovers.

          +

          Roll over to a new index.

          +

          TIP: It is recommended to use the index lifecycle rollover action to automate rollovers.

          The rollover API creates a new index for a data stream or index alias. The API behavior depends on the rollover target.

          Roll over a data stream

          @@ -5286,8 +5147,8 @@ async def segments( """ .. raw:: html -

          Get index segments. - Get low-level information about the Lucene segments in index shards. +

          Get index segments.

          +

          Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the stream's backing indices.

          @@ -5367,8 +5228,8 @@ async def shard_stores( """ .. raw:: html -

          Get index shard stores. - Get store information about replica shards in one or more indices. +

          Get index shard stores.

          +

          Get store information about replica shards in one or more indices. For data streams, the API retrieves store information for the stream's backing indices.

          The index shard stores API returns the following information:

            @@ -5451,8 +5312,8 @@ async def shrink( """ .. raw:: html -

            Shrink an index. - Shrink an index into a new index with fewer primary shards.

            +

            Shrink an index.

            +

            Shrink an index into a new index with fewer primary shards.

            Before you can shrink an index:

            • The index must be read-only.
            • @@ -5527,11 +5388,7 @@ async def shrink( __body["aliases"] = aliases if settings is not None: __body["settings"] = settings - 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] "PUT", __path, @@ -5542,7 +5399,9 @@ async def shrink( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_name="index_template", + ) async def simulate_index_template( self, *, @@ -5553,14 +5412,16 @@ async def simulate_index_template( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, include_defaults: t.Optional[bool] = None, + index_template: t.Optional[t.Mapping[str, t.Any]] = None, + body: t.Optional[t.Mapping[str, t.Any]] = None, master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html -

              Simulate an index. - Get the index configuration that would be applied to the specified index from an existing index template.

              +

              Simulate an index.

              +

              Get the index configuration that would be applied to the specified index from an existing index template.

              ``_ @@ -5572,12 +5433,15 @@ async def simulate_index_template( only be dry-run added if new or can also replace an existing one :param include_defaults: If true, returns all relevant default configurations for the index template. + :param index_template: :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'") + if index_template is not None and body is not None: + raise ValueError("Cannot set both 'index_template' and 'body'") __path_parts: t.Dict[str, str] = {"name": _quote(name)} __path = f'/_index_template/_simulate_index/{__path_parts["name"]}' __query: t.Dict[str, t.Any] = {} @@ -5597,12 +5461,18 @@ async def simulate_index_template( __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + __body = index_template if index_template is not None else body + if not __body: + __body = None __headers = {"accept": "application/json"} + if __body is not None: + __headers["content-type"] = "application/json" return await self.perform_request( # type: ignore[return-value] "POST", __path, params=__query, headers=__headers, + body=__body, endpoint_id="indices.simulate_index_template", path_parts=__path_parts, ) @@ -5649,8 +5519,8 @@ async def simulate_template( """ .. raw:: html -

              Simulate an index template. - Get the index configuration that would be applied by a particular index template.

              +

              Simulate an index template.

              +

              Get the index configuration that would be applied by a particular index template.

              ``_ @@ -5788,8 +5658,8 @@ async def split( """ .. raw:: html -

              Split an index. - Split an index into a new index with more primary shards.

              +

              Split an index.

              +

              Split an index into a new index with more primary shards.

              • Before you can split an index:

                @@ -5870,11 +5740,7 @@ async def split( __body["aliases"] = aliases if settings is not None: __body["settings"] = settings - 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] "PUT", __path, @@ -5917,8 +5783,8 @@ async def stats( """ .. raw:: html -

                Get index statistics. - For data streams, the API retrieves statistics for the stream's backing indices.

                +

                Get index statistics.

                +

                For data streams, the API retrieves statistics for the stream's backing indices.

                By default, the returned statistics are index-level with primaries and total aggregations. primaries are the values for only the primary shards. total are the accumulated values for both primary and replica shards.

                @@ -5931,7 +5797,7 @@ async def stats( :param index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices - :param metric: Limit the information returned the specific metrics. + :param metric: Limit the information returned the specific metrics :param completion_fields: Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics. :param expand_wildcards: Type of index that wildcard patterns can match. If the @@ -5951,8 +5817,8 @@ async def stats( are requested). :param include_unloaded_segments: If true, the response includes information from segments that are not loaded into memory. - :param level: Indicates whether statistics are aggregated at the cluster, index, - or shard level. + :param level: Indicates whether statistics are aggregated at the cluster, indices, + or shards level. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH and metric not in SKIP_IN_PATH: @@ -6022,8 +5888,8 @@ async def update_aliases( """ .. raw:: html -

                Create or update an alias. - Adds a data stream or index to an alias.

                +

                Create or update an alias.

                +

                Adds a data stream or index to an alias.

                ``_ @@ -6101,8 +5967,8 @@ async def validate_query( """ .. raw:: html -

                Validate a query. - Validates a query without running it.

                +

                Validate a query.

                +

                Validates a query without running it.

                ``_ diff --git a/elasticsearch/_async/client/inference.py b/elasticsearch/_async/client/inference.py index 58b51a72e..d5d7d420e 100644 --- a/elasticsearch/_async/client/inference.py +++ b/elasticsearch/_async/client/inference.py @@ -44,7 +44,7 @@ async def completion( """ .. raw:: html -

                Perform completion inference on the service

                +

                Perform completion inference on the service.

                ``_ @@ -78,11 +78,7 @@ async def completion( __body["input"] = input if task_settings is not None: __body["task_settings"] = task_settings - 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, @@ -120,7 +116,7 @@ async def delete( """ .. raw:: html -

                Delete an inference endpoint

                +

                Delete an inference endpoint.

                ``_ @@ -194,7 +190,7 @@ async def get( """ .. raw:: html -

                Get an inference endpoint

                +

                Get an inference endpoint.

                ``_ @@ -338,11 +334,7 @@ async def inference( __body["query"] = query if task_settings is not None: __body["task_settings"] = task_settings - 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, @@ -391,21 +383,23 @@ async def put(
                • AlibabaCloud AI Search (completion, rerank, sparse_embedding, text_embedding)
                • Amazon Bedrock (completion, text_embedding)
                • +
                • Amazon SageMaker (chat_completion, completion, rerank, sparse_embedding, text_embedding)
                • Anthropic (completion)
                • -
                • Azure AI Studio (completion, 'rerank', text_embedding)
                • +
                • Azure AI Studio (completion, text_embedding)
                • Azure OpenAI (completion, text_embedding)
                • Cohere (completion, rerank, text_embedding)
                • -
                • DeepSeek (completion, chat_completion)
                • +
                • DeepSeek (chat_completion, completion)
                • Elasticsearch (rerank, sparse_embedding, text_embedding - this service is for built-in models and models uploaded through Eland)
                • ELSER (sparse_embedding)
                • Google AI Studio (completion, text_embedding)
                • -
                • Google Vertex AI (rerank, text_embedding)
                • +
                • Google Vertex AI (chat_completion, completion, rerank, text_embedding)
                • Hugging Face (chat_completion, completion, rerank, text_embedding)
                • +
                • JinaAI (rerank, text_embedding)
                • +
                • Llama (chat_completion, completion, text_embedding)
                • Mistral (chat_completion, completion, text_embedding)
                • OpenAI (chat_completion, completion, text_embedding)
                • -
                • VoyageAI (text_embedding, rerank)
                • +
                • VoyageAI (rerank, text_embedding)
                • Watsonx inference integration (text_embedding)
                • -
                • JinaAI (text_embedding, rerank)
                @@ -544,11 +538,7 @@ async def put_alibabacloud( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -644,11 +634,7 @@ async def put_amazonbedrock( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -659,6 +645,108 @@ async def put_amazonbedrock( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=( + "service", + "service_settings", + "chunking_settings", + "task_settings", + ), + ) + async def put_amazonsagemaker( + self, + *, + task_type: t.Union[ + str, + t.Literal[ + "chat_completion", + "completion", + "rerank", + "sparse_embedding", + "text_embedding", + ], + ], + amazonsagemaker_inference_id: str, + service: t.Optional[t.Union[str, t.Literal["amazon_sagemaker"]]] = None, + service_settings: t.Optional[t.Mapping[str, t.Any]] = None, + chunking_settings: 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, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + task_settings: t.Optional[t.Mapping[str, t.Any]] = 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]: + """ + .. raw:: html + +

                Create an Amazon SageMaker inference endpoint.

                +

                Create an inference endpoint to perform an inference task with the amazon_sagemaker service.

                + + + ``_ + + :param task_type: The type of the inference task that the model will perform. + :param amazonsagemaker_inference_id: The unique identifier of the inference endpoint. + :param service: The type of service supported for the specified task type. In + this case, `amazon_sagemaker`. + :param service_settings: Settings used to install the inference model. These + settings are specific to the `amazon_sagemaker` service and `service_settings.api` + you specified. + :param chunking_settings: The chunking configuration object. + :param task_settings: Settings to configure the inference task. These settings + are specific to the task type and `service_settings.api` you specified. + :param timeout: Specifies the amount of time to wait for the inference endpoint + to be created. + """ + if task_type in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'task_type'") + if amazonsagemaker_inference_id in SKIP_IN_PATH: + raise ValueError( + "Empty value passed for parameter 'amazonsagemaker_inference_id'" + ) + if service is None and body is None: + raise ValueError("Empty value passed for parameter 'service'") + if service_settings is None and body is None: + raise ValueError("Empty value passed for parameter 'service_settings'") + __path_parts: t.Dict[str, str] = { + "task_type": _quote(task_type), + "amazonsagemaker_inference_id": _quote(amazonsagemaker_inference_id), + } + __path = f'/_inference/{__path_parts["task_type"]}/{__path_parts["amazonsagemaker_inference_id"]}' + __query: t.Dict[str, t.Any] = {} + __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 filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout + if not __body: + if service is not None: + __body["service"] = service + if service_settings is not None: + __body["service_settings"] = service_settings + if chunking_settings is not None: + __body["chunking_settings"] = chunking_settings + if task_settings is not None: + __body["task_settings"] = task_settings + __headers = {"accept": "application/json", "content-type": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "PUT", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="inference.put_amazonsagemaker", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=( "service", @@ -741,11 +829,7 @@ async def put_anthropic( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -767,7 +851,7 @@ async def put_anthropic( async def put_azureaistudio( self, *, - task_type: t.Union[str, t.Literal["completion", "rerank", "text_embedding"]], + task_type: t.Union[str, t.Literal["completion", "text_embedding"]], azureaistudio_inference_id: str, service: t.Optional[t.Union[str, t.Literal["azureaistudio"]]] = None, service_settings: t.Optional[t.Mapping[str, t.Any]] = None, @@ -837,11 +921,7 @@ async def put_azureaistudio( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -941,11 +1021,7 @@ async def put_azureopenai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -1035,11 +1111,7 @@ async def put_cohere( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -1166,11 +1238,7 @@ async def put_custom( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -1250,11 +1318,7 @@ async def put_deepseek( __body["service_settings"] = service_settings if chunking_settings is not None: __body["chunking_settings"] = chunking_settings - 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] "PUT", __path, @@ -1362,11 +1426,7 @@ async def put_elasticsearch( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -1460,11 +1520,7 @@ async def put_elser( __body["service_settings"] = service_settings if chunking_settings is not None: __body["chunking_settings"] = chunking_settings - 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] "PUT", __path, @@ -1546,11 +1602,7 @@ async def put_googleaistudio( __body["service_settings"] = service_settings if chunking_settings is not None: __body["chunking_settings"] = chunking_settings - 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] "PUT", __path, @@ -1644,11 +1696,7 @@ async def put_googlevertexai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -1776,11 +1824,7 @@ async def put_hugging_face( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -1872,11 +1916,7 @@ async def put_jinaai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -1958,11 +1998,7 @@ async def put_mistral( __body["service_settings"] = service_settings if chunking_settings is not None: __body["chunking_settings"] = chunking_settings - 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] "PUT", __path, @@ -2056,11 +2092,7 @@ async def put_openai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -2151,11 +2183,7 @@ async def put_voyageai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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] "PUT", __path, @@ -2235,11 +2263,7 @@ async def put_watsonx( __body["service"] = service if service_settings is not None: __body["service_settings"] = service_settings - 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] "PUT", __path, @@ -2270,7 +2294,7 @@ async def rerank( """ .. raw:: html -

                Perform reranking inference on the service

                +

                Perform reranking inference on the service.

                ``_ @@ -2312,11 +2336,7 @@ async def rerank( __body["query"] = query if task_settings is not None: __body["task_settings"] = task_settings - 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, @@ -2346,7 +2366,7 @@ async def sparse_embedding( """ .. raw:: html -

                Perform sparse embedding inference on the service

                +

                Perform sparse embedding inference on the service.

                ``_ @@ -2380,11 +2400,7 @@ async def sparse_embedding( __body["input"] = input if task_settings is not None: __body["task_settings"] = task_settings - 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, @@ -2396,7 +2412,7 @@ async def sparse_embedding( ) @_rewrite_parameters( - body_fields=("input", "task_settings"), + body_fields=("input", "input_type", "task_settings"), ) async def text_embedding( self, @@ -2406,6 +2422,7 @@ async def text_embedding( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + input_type: t.Optional[str] = None, pretty: t.Optional[bool] = None, task_settings: t.Optional[t.Any] = None, timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, @@ -2414,13 +2431,20 @@ async def text_embedding( """ .. raw:: html -

                Perform text embedding inference on the service

                +

                Perform text embedding inference on the service.

                ``_ :param inference_id: The inference Id :param input: Inference input. Either a string or an array of strings. + :param input_type: The input data type for the text embedding model. Possible + values include: * `SEARCH` * `INGEST` * `CLASSIFICATION` * `CLUSTERING` Not + all services support all values. Unsupported values will trigger a validation + exception. Accepted values depend on the configured inference service, refer + to the relevant service-specific documentation for more info. > info > The + `input_type` parameter specified on the root level of the request body will + take precedence over the `input_type` parameter specified in `task_settings`. :param task_settings: Optional task settings :param timeout: Specifies the amount of time to wait for the inference request to complete. @@ -2446,13 +2470,11 @@ async def text_embedding( if not __body: if input is not None: __body["input"] = input + if input_type is not None: + __body["input_type"] = input_type if task_settings is not None: __body["task_settings"] = task_settings - 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, diff --git a/elasticsearch/_async/client/ingest.py b/elasticsearch/_async/client/ingest.py index 3cd0260d5..d68eec651 100644 --- a/elasticsearch/_async/client/ingest.py +++ b/elasticsearch/_async/client/ingest.py @@ -151,8 +151,8 @@ async def delete_pipeline( """ .. raw:: html -

                Delete pipelines. - Delete one or more ingest pipelines.

                +

                Delete pipelines.

                +

                Delete one or more ingest pipelines.

                ``_ @@ -204,8 +204,8 @@ async def geo_ip_stats( """ .. raw:: html -

                Get GeoIP statistics. - Get download statistics for GeoIP2 databases that are used with the GeoIP processor.

                +

                Get GeoIP statistics.

                +

                Get download statistics for GeoIP2 databases that are used with the GeoIP processor.

                ``_ @@ -355,7 +355,7 @@ async def get_pipeline( :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 summary: Return pipelines without their definitions (default: false) + :param summary: Return pipelines without their definitions """ __path_parts: t.Dict[str, str] if id not in SKIP_IN_PATH: @@ -399,8 +399,8 @@ async def processor_grok( """ .. raw:: html -

                Run a grok processor. - Extract structured fields out of a single text field within a document. +

                Run a grok processor.

                +

                Extract structured fields out of a single text field within a document. You must choose which field to extract matched fields from, as well as the grok pattern you expect will match. A grok pattern is like a regular expression that supports aliased expressions that can be reused.

                @@ -609,8 +609,8 @@ async def put_pipeline( """ .. raw:: html -

                Create or update a pipeline. - Changes made using this API take effect immediately.

                +

                Create or update a pipeline.

                +

                Changes made using this API take effect immediately.

                ``_ diff --git a/elasticsearch/_async/client/license.py b/elasticsearch/_async/client/license.py index ba389d0d5..456efad5d 100644 --- a/elasticsearch/_async/client/license.py +++ b/elasticsearch/_async/client/license.py @@ -310,8 +310,7 @@ async def post_start_basic( ``_ - :param acknowledge: whether the user has acknowledged acknowledge messages (default: - false) + :param acknowledge: Whether the user has acknowledged acknowledge messages :param master_timeout: Period to wait for a connection to the master node. :param timeout: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. @@ -358,8 +357,8 @@ async def post_start_trial( """ .. raw:: html -

                Start a trial. - Start a 30-day trial, which gives access to all subscription features.

                +

                Start a trial.

                +

                Start a 30-day trial, which gives access to all subscription features.

                NOTE: You are allowed to start a trial only if your cluster has not already activated a trial for the current major product version. For example, if you have already activated a trial for v8.0, you cannot start a new trial until v9.0. You can, however, request an extended trial at https://www.elastic.co/trialextension.

                To check the status of your trial, use the get trial status API.

                @@ -367,10 +366,9 @@ async def post_start_trial( ``_ - :param acknowledge: whether the user has acknowledged acknowledge messages (default: - false) + :param acknowledge: Whether the user has acknowledged acknowledge messages :param master_timeout: Period to wait for a connection to the master node. - :param type: The type of trial license to generate (default: "trial") + :param type: The type of trial license to generate """ __path_parts: t.Dict[str, str] = {} __path = "/_license/start_trial" diff --git a/elasticsearch/_async/client/logstash.py b/elasticsearch/_async/client/logstash.py index c63983710..bc6639925 100644 --- a/elasticsearch/_async/client/logstash.py +++ b/elasticsearch/_async/client/logstash.py @@ -38,8 +38,8 @@ async def delete_pipeline( """ .. raw:: html -

                Delete a Logstash pipeline. - Delete a pipeline that is used for Logstash Central Management. +

                Delete a Logstash pipeline.

                +

                Delete a pipeline that is used for Logstash Central Management. If the request succeeds, you receive an empty response with an appropriate status code.

                @@ -83,8 +83,8 @@ async def get_pipeline( """ .. raw:: html -

                Get Logstash pipelines. - Get pipelines that are used for Logstash Central Management.

                +

                Get Logstash pipelines.

                +

                Get pipelines that are used for Logstash Central Management.

                ``_ @@ -141,7 +141,9 @@ async def put_pipeline( ``_ - :param id: An identifier for the pipeline. + :param id: An identifier for the pipeline. Pipeline IDs must begin with a letter + or underscore and contain only letters, underscores, dashes, hyphens and + numbers. :param pipeline: """ if id in SKIP_IN_PATH: diff --git a/elasticsearch/_async/client/migration.py b/elasticsearch/_async/client/migration.py index 4ff5a18fc..7fd2bee1f 100644 --- a/elasticsearch/_async/client/migration.py +++ b/elasticsearch/_async/client/migration.py @@ -38,8 +38,8 @@ async def deprecations( """ .. raw:: html -

                Get deprecation information. - Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.

                +

                Get deprecation information.

                +

                Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.

                TIP: This APIs is designed for indirect use by the Upgrade Assistant. You are strongly recommended to use the Upgrade Assistant.

                @@ -87,8 +87,8 @@ async def get_feature_upgrade_status( """ .. raw:: html -

                Get feature migration information. - Version upgrades sometimes require changes to how features store configuration information and data in system indices. +

                Get feature migration information.

                +

                Version upgrades sometimes require changes to how features store configuration information and data in system indices. Check which features need to be migrated and the status of any migrations that are in progress.

                TIP: This API is designed for indirect use by the Upgrade Assistant. You are strongly recommended to use the Upgrade Assistant.

                @@ -129,8 +129,8 @@ async def post_feature_upgrade( """ .. raw:: html -

                Start the feature migration. - Version upgrades sometimes require changes to how features store configuration information and data in system indices. +

                Start the feature migration.

                +

                Version upgrades sometimes require changes to how features store configuration information and data in system indices. This API starts the automatic migration process.

                Some functionality might be temporarily unavailable during the migration process.

                TIP: The API is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.

                diff --git a/elasticsearch/_async/client/ml.py b/elasticsearch/_async/client/ml.py index fb5af673f..a14a17b63 100644 --- a/elasticsearch/_async/client/ml.py +++ b/elasticsearch/_async/client/ml.py @@ -20,7 +20,14 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + Visibility, + _availability_warning, + _quote, + _rewrite_parameters, +) class MlClient(NamespacedClient): @@ -1101,8 +1108,8 @@ async def flush_job( """ .. raw:: html -

                Force buffered data to be processed. - The flush jobs API is only applicable when sending data for analysis using +

                Force buffered data to be processed.

                +

                The flush jobs API is only applicable when sending data for analysis using the post data API. Depending on the content of the buffer, then it might additionally calculate new results. Both flush and close operations are similar, however the flush is more efficient if you are expecting to send @@ -1269,8 +1276,8 @@ async def get_buckets( """ .. raw:: html -

                Get anomaly detection job results for buckets. - The API presents a chronological view of the records, grouped by bucket.

                +

                Get anomaly detection job results for buckets.

                +

                The API presents a chronological view of the records, grouped by bucket.

                ``_ @@ -1598,8 +1605,8 @@ async def get_data_frame_analytics( """ .. raw:: html -

                Get data frame analytics job configuration info. - You can get information for multiple data frame analytics jobs in a single +

                Get data frame analytics job configuration info.

                +

                You can get information for multiple data frame analytics jobs in a single API request by using a comma-separated list of data frame analytics jobs or a wildcard expression.

                @@ -1744,8 +1751,8 @@ async def get_datafeed_stats( """ .. raw:: html -

                Get datafeed stats. - You can get statistics for multiple datafeeds in a single API request by +

                Get datafeed stats.

                +

                You can get statistics for multiple datafeeds in a single API request by using a comma-separated list of datafeeds or a wildcard expression. You can get statistics for all datafeeds by using _all, by specifying * as the <feed_id>, or by omitting the <feed_id>. If the datafeed is stopped, the @@ -1809,8 +1816,8 @@ async def get_datafeeds( """ .. raw:: html -

                Get datafeeds configuration info. - You can get information for multiple datafeeds in a single API request by +

                Get datafeeds configuration info.

                +

                You can get information for multiple datafeeds in a single API request by using a comma-separated list of datafeeds or a wildcard expression. You can get information for all datafeeds by using _all, by specifying * as the <feed_id>, or by omitting the <feed_id>. @@ -1880,8 +1887,8 @@ async def get_filters( """ .. raw:: html -

                Get filters. - You can get a single filter or all filters.

                +

                Get filters.

                +

                You can get a single filter or all filters.

                ``_ @@ -1946,8 +1953,8 @@ async def get_influencers( """ .. raw:: html -

                Get anomaly detection job results for influencers. - Influencers are the entities that have contributed to, or are to blame for, +

                Get anomaly detection job results for influencers.

                +

                Influencers are the entities that have contributed to, or are to blame for, the anomalies. Influencer results are available only if an influencer_field_name is specified in the job configuration.

                @@ -2093,8 +2100,8 @@ async def get_jobs( """ .. raw:: html -

                Get anomaly detection jobs configuration info. - You can get information for multiple anomaly detection jobs in a single API +

                Get anomaly detection jobs configuration info.

                +

                You can get information for multiple anomaly detection jobs in a single API request by using a group name, a comma-separated list of jobs, or a wildcard expression. You can get information for all anomaly detection jobs by using _all, by specifying * as the <job_id>, or by omitting the <job_id>.

                @@ -2161,8 +2168,8 @@ async def get_memory_stats( """ .. raw:: html -

                Get machine learning memory usage info. - Get information about how machine learning jobs and trained models are using memory, +

                Get machine learning memory usage info.

                +

                Get information about how machine learning jobs and trained models are using memory, on each node, both within the JVM heap, and natively, outside of the JVM.

                @@ -2515,8 +2522,8 @@ async def get_records( """ .. raw:: html -

                Get anomaly records for an anomaly detection job. - Records contain the detailed analytical results. They describe the anomalous +

                Get anomaly records for an anomaly detection job.

                +

                Records contain the detailed analytical results. They describe the anomalous activity that has been identified in the input data based on the detector configuration. There can be many anomaly records depending on the characteristics and size @@ -2708,8 +2715,8 @@ async def get_trained_models_stats( """ .. raw:: html -

                Get trained models usage info. - You can get usage information for multiple trained +

                Get trained models usage info.

                +

                You can get usage information for multiple trained models in a single API request by using a comma-separated list of model IDs or a wildcard expression.

                @@ -2836,8 +2843,8 @@ async def info( """ .. raw:: html -

                Get machine learning information. - Get defaults and limits used by machine learning. +

                Get machine learning information.

                +

                Get defaults and limits used by machine learning. This endpoint is designed to be used by a user interface that needs to fully understand machine learning configurations where some options are not specified, meaning that the defaults should be used. This endpoint may be @@ -3045,10 +3052,7 @@ async def post_data( if reset_start is not None: __query["reset_start"] = reset_start __body = data if data is not None else body - __headers = { - "accept": "application/json", - "content-type": "application/x-ndjson", - } + __headers = {"accept": "application/json", "content-type": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", __path, @@ -3076,8 +3080,8 @@ async def preview_data_frame_analytics( """ .. raw:: html -

                Preview features used by data frame analytics. - Preview the extracted features used by a data frame analytics config.

                +

                Preview features used by data frame analytics.

                +

                Preview the extracted features used by a data frame analytics config.

                ``_ @@ -3142,8 +3146,8 @@ async def preview_datafeed( """ .. raw:: html -

                Preview a datafeed. - This API returns the first "page" of search results from a datafeed. +

                Preview a datafeed.

                +

                This API returns the first "page" of search results from a datafeed. You can preview an existing datafeed or provide configuration details for a datafeed and anomaly detection job in the API. The preview shows the structure of the data that will be passed to the anomaly detection engine. @@ -3364,8 +3368,8 @@ async def put_data_frame_analytics( """ .. raw:: html -

                Create a data frame analytics job. - This API creates a data frame analytics job that performs an analysis on the +

                Create a data frame analytics job.

                +

                This API creates a data frame analytics job that performs an analysis on the source indices and stores the outcome in a destination index. By default, the query used in the source configuration is {"match_all": {}}.

                If the destination index does not exist, it is created automatically when you start the job.

                @@ -3545,8 +3549,8 @@ async def put_datafeed( """ .. raw:: html -

                Create a datafeed. - Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job. +

                Create a datafeed.

                +

                Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job. You can associate only one datafeed with each anomaly detection job. The datafeed contains a query that runs at a defined interval (frequency). If you are concerned about delayed data, you can add a delay (query_delay') at each interval. By default, the datafeed uses the following query: {"match_all": {"boost": 1}}`.

                @@ -3714,8 +3718,8 @@ async def put_filter( """ .. raw:: html -

                Create a filter. - A filter contains a list of strings. It can be used by one or more anomaly detection jobs. +

                Create a filter.

                +

                A filter contains a list of strings. It can be used by one or more anomaly detection jobs. Specifically, filters are referenced in the custom_rules property of detector configuration objects.

                @@ -4019,8 +4023,8 @@ async def put_trained_model( """ .. raw:: html -

                Create a trained model. - Enable you to supply a trained model that is not created by data frame analytics.

                +

                Create a trained model.

                +

                Enable you to supply a trained model that is not created by data frame analytics.

                ``_ @@ -4125,8 +4129,8 @@ async def put_trained_model_alias( """ .. raw:: html -

                Create or update a trained model alias. - A trained model alias is a logical name used to reference a single trained +

                Create or update a trained model alias.

                +

                A trained model alias is a logical name used to reference a single trained model. You can use aliases instead of trained model identifiers to make it easier to reference your models. For example, you can use aliases in inference @@ -4282,8 +4286,8 @@ async def put_trained_model_vocabulary( """ .. raw:: html -

                Create a trained model vocabulary. - This API is supported only for natural language processing (NLP) models. +

                Create a trained model vocabulary.

                +

                This API is supported only for natural language processing (NLP) models. The vocabulary is stored in the index as described in inference_config.*.vocabulary of the trained model definition.

                @@ -4343,8 +4347,8 @@ async def reset_job( """ .. raw:: html -

                Reset an anomaly detection job. - All model state and results are deleted. The job is ready to start over as if +

                Reset an anomaly detection job.

                +

                All model state and results are deleted. The job is ready to start over as if it had just been created. It is not currently possible to reset multiple jobs using wildcards or a comma separated list.

                @@ -4404,8 +4408,8 @@ async def revert_model_snapshot( """ .. raw:: html -

                Revert to a snapshot. - The machine learning features react quickly to anomalous input, learning new +

                Revert to a snapshot.

                +

                The machine learning features react quickly to anomalous input, learning new behaviors in data. Highly anomalous input increases the variance in the models whilst the system learns whether this is a new step-change in behavior or a one-off event. In the case where this anomalous input is known to be a @@ -4474,8 +4478,8 @@ async def set_upgrade_mode( """ .. raw:: html -

                Set upgrade_mode for ML indices. - Sets a cluster wide upgrade_mode setting that prepares machine learning +

                Set upgrade_mode for ML indices.

                +

                Sets a cluster wide upgrade_mode setting that prepares machine learning indices for an upgrade. When upgrading your cluster, in some circumstances you must restart your nodes and reindex your machine learning indices. In those circumstances, @@ -4521,7 +4525,9 @@ async def set_upgrade_mode( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_fields=("timeout",), + ) async def start_data_frame_analytics( self, *, @@ -4531,12 +4537,13 @@ async def start_data_frame_analytics( human: t.Optional[bool] = 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]: """ .. raw:: html -

                Start a data frame analytics job. - A data frame analytics job can be started and stopped multiple times +

                Start a data frame analytics job.

                +

                A data frame analytics job can be started and stopped multiple times throughout its lifecycle. If the destination index does not exist, it is created automatically the first time you start the data frame analytics job. The @@ -4562,6 +4569,7 @@ async def start_data_frame_analytics( __path_parts: t.Dict[str, str] = {"id": _quote(id)} __path = f'/_ml/data_frame/analytics/{__path_parts["id"]}/_start' __query: t.Dict[str, t.Any] = {} + __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 filter_path is not None: @@ -4570,14 +4578,20 @@ async def start_data_frame_analytics( __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout + if not __body: + 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" return await self.perform_request( # type: ignore[return-value] "POST", __path, params=__query, headers=__headers, + body=__body, endpoint_id="ml.start_data_frame_analytics", path_parts=__path_parts, ) @@ -4685,8 +4699,8 @@ async def start_trained_model_deployment( """ .. raw:: html -

                Start a trained model deployment. - It allocates the model to every machine learning node.

                +

                Start a trained model deployment.

                +

                It allocates the model to every machine learning node.

                ``_ @@ -4707,7 +4721,7 @@ async def start_trained_model_deployment( is greater than the number of hardware threads it will automatically be changed to a value less than the number of hardware threads. If adaptive_allocations is enabled, do not set this value, because it’s automatically set. - :param priority: The deployment priority. + :param priority: The deployment priority :param queue_capacity: Specifies the number of inference requests that are allowed in the queue. After the number of requests exceeds this value, new requests are rejected with a 429 error. @@ -4769,7 +4783,9 @@ async def start_trained_model_deployment( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_fields=("allow_no_match", "force", "timeout"), + ) async def stop_data_frame_analytics( self, *, @@ -4781,12 +4797,13 @@ async def stop_data_frame_analytics( human: t.Optional[bool] = 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]: """ .. raw:: html -

                Stop data frame analytics jobs. - A data frame analytics job can be started and stopped multiple times +

                Stop data frame analytics jobs.

                +

                A data frame analytics job can be started and stopped multiple times throughout its lifecycle.

                @@ -4812,26 +4829,33 @@ async def stop_data_frame_analytics( __path_parts: t.Dict[str, str] = {"id": _quote(id)} __path = f'/_ml/data_frame/analytics/{__path_parts["id"]}/_stop' __query: t.Dict[str, t.Any] = {} - if allow_no_match is not None: - __query["allow_no_match"] = allow_no_match + __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 filter_path is not None: __query["filter_path"] = filter_path - if force is not None: - __query["force"] = force if human is not None: __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout + if not __body: + if allow_no_match is not None: + __body["allow_no_match"] = allow_no_match + if force is not None: + __body["force"] = force + 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" return await self.perform_request( # type: ignore[return-value] "POST", __path, params=__query, headers=__headers, + body=__body, endpoint_id="ml.stop_data_frame_analytics", path_parts=__path_parts, ) @@ -4855,8 +4879,8 @@ async def stop_datafeed( """ .. raw:: html -

                Stop datafeeds. - A datafeed that is stopped ceases to retrieve data from Elasticsearch. A datafeed can be started and stopped +

                Stop datafeeds.

                +

                A datafeed that is stopped ceases to retrieve data from Elasticsearch. A datafeed can be started and stopped multiple times throughout its lifecycle.

                @@ -4907,7 +4931,9 @@ async def stop_datafeed( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_fields=("allow_no_match", "force", "id"), + ) async def stop_trained_model_deployment( self, *, @@ -4917,7 +4943,9 @@ async def stop_trained_model_deployment( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, force: t.Optional[bool] = None, human: t.Optional[bool] = None, + id: t.Optional[str] = None, pretty: t.Optional[bool] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html @@ -4937,30 +4965,40 @@ async def stop_trained_model_deployment( no matches or only partial matches. :param force: Forcefully stops the deployment, even if it is used by ingest pipelines. You can't use these pipelines until you restart the model deployment. + :param id: If provided, must be the same identifier as in the path. """ if model_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'model_id'") __path_parts: t.Dict[str, str] = {"model_id": _quote(model_id)} __path = f'/_ml/trained_models/{__path_parts["model_id"]}/deployment/_stop' __query: t.Dict[str, t.Any] = {} - if allow_no_match is not None: - __query["allow_no_match"] = allow_no_match + __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 filter_path is not None: __query["filter_path"] = filter_path - if force is not None: - __query["force"] = force if human is not None: __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if not __body: + if allow_no_match is not None: + __body["allow_no_match"] = allow_no_match + if force is not None: + __body["force"] = force + if id is not None: + __body["id"] = id + if not __body: + __body = None # type: ignore[assignment] __headers = {"accept": "application/json"} + if __body is not None: + __headers["content-type"] = "application/json" return await self.perform_request( # type: ignore[return-value] "POST", __path, params=__query, headers=__headers, + body=__body, endpoint_id="ml.stop_trained_model_deployment", path_parts=__path_parts, ) @@ -5101,8 +5139,8 @@ async def update_datafeed( """ .. raw:: html -

                Update a datafeed. - You must stop and start the datafeed for the changes to be applied. +

                Update a datafeed.

                +

                You must stop and start the datafeed for the changes to be applied. When Elasticsearch security features are enabled, your datafeed remembers which roles the user who updated it had at the time of the update and runs the query using those same roles. If you provide secondary authorization headers, those credentials are used instead.

                @@ -5265,8 +5303,8 @@ async def update_filter( """ .. raw:: html -

                Update a filter. - Updates the description of a filter, adds items, or removes items from the list.

                +

                Update a filter.

                +

                Updates the description of a filter, adds items, or removes items from the list.

                ``_ @@ -5359,8 +5397,8 @@ async def update_job( """ .. raw:: html -

                Update an anomaly detection job. - Updates certain properties of an anomaly detection job.

                +

                Update an anomaly detection job.

                +

                Updates certain properties of an anomaly detection job.

                ``_ @@ -5491,8 +5529,8 @@ async def update_model_snapshot( """ .. raw:: html -

                Update a snapshot. - Updates certain properties of a snapshot.

                +

                Update a snapshot.

                +

                Updates certain properties of a snapshot.

                ``_ @@ -5625,8 +5663,8 @@ async def upgrade_job_snapshot( """ .. raw:: html -

                Upgrade a snapshot. - Upgrade an anomaly detection model snapshot to the latest major version. +

                Upgrade a snapshot.

                +

                Upgrade an anomaly detection model snapshot to the latest major version. Over time, older snapshot formats are deprecated and removed. Anomaly detection jobs support only snapshots that are from the current or previous major version. @@ -5692,6 +5730,7 @@ async def upgrade_job_snapshot( "results_index_name", ), ) + @_availability_warning(Stability.STABLE, Visibility.PRIVATE) async def validate( self, *, @@ -5716,7 +5755,7 @@ async def validate(

                Validate an anomaly detection job.

                - ``_ + ``_ :param analysis_config: :param analysis_limits: @@ -5773,6 +5812,7 @@ async def validate( @_rewrite_parameters( body_name="detector", ) + @_availability_warning(Stability.STABLE, Visibility.PRIVATE) async def validate_detector( self, *, diff --git a/elasticsearch/_async/client/monitoring.py b/elasticsearch/_async/client/monitoring.py index afc6406da..54e6dd343 100644 --- a/elasticsearch/_async/client/monitoring.py +++ b/elasticsearch/_async/client/monitoring.py @@ -20,7 +20,7 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import _rewrite_parameters +from .utils import Stability, Visibility, _availability_warning, _rewrite_parameters class MonitoringClient(NamespacedClient): @@ -28,6 +28,7 @@ class MonitoringClient(NamespacedClient): @_rewrite_parameters( body_name="operations", ) + @_availability_warning(Stability.STABLE, Visibility.PRIVATE) async def bulk( self, *, @@ -44,8 +45,8 @@ async def bulk( """ .. raw:: html -

                Send monitoring data. - This API is used by the monitoring features to send monitoring data.

                +

                Send monitoring data.

                +

                This API is used by the monitoring features to send monitoring data.

                ``_ diff --git a/elasticsearch/_async/client/nodes.py b/elasticsearch/_async/client/nodes.py index 1b007e7cb..ad225647d 100644 --- a/elasticsearch/_async/client/nodes.py +++ b/elasticsearch/_async/client/nodes.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class NodesClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def clear_repositories_metering_archive( self, *, @@ -46,8 +46,8 @@ async def clear_repositories_metering_archive( """ .. raw:: html -

                Clear the archived repositories metering. - Clear the archived repositories metering information in the cluster.

                +

                Clear the archived repositories metering.

                +

                Clear the archived repositories metering information in the cluster.

                ``_ @@ -86,7 +86,7 @@ async def clear_repositories_metering_archive( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def get_repositories_metering_info( self, *, @@ -99,8 +99,8 @@ async def get_repositories_metering_info( """ .. raw:: html -

                Get cluster repositories metering. - Get repositories metering information for a cluster. +

                Get cluster repositories metering.

                +

                Get repositories metering information for a cluster. This API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time. Additionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.

                @@ -157,8 +157,8 @@ async def hot_threads( """ .. raw:: html -

                Get the hot threads for nodes. - Get a breakdown of the hot threads on each selected node in the cluster. +

                Get the hot threads for nodes.

                +

                Get a breakdown of the hot threads on each selected node in the cluster. The output is plain text with a breakdown of the top hot threads for each node.

                @@ -169,7 +169,7 @@ async def hot_threads( select, or to get a task from an empty queue) are filtered out. :param interval: The interval to do the second sampling of threads. :param snapshots: Number of samples of thread stacktrace. - :param sort: The sort order for 'cpu' type (default: total) + :param sort: The sort order for 'cpu' type :param threads: Specifies the number of hot threads to provide information for. :param timeout: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. @@ -378,8 +378,8 @@ async def stats( """ .. raw:: html -

                Get node statistics. - Get statistics for nodes in a cluster. +

                Get node statistics.

                +

                Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.

                @@ -387,7 +387,7 @@ async def stats( :param node_id: Comma-separated list of node IDs or names used to limit returned information. - :param metric: Limit the information returned to the specified metrics + :param metric: :param index_metric: Limit the information returned for indices metric to the specific index metrics. It can be used only if indices (or all) metric is specified. @@ -404,8 +404,8 @@ async def stats( are requested). :param include_unloaded_segments: If `true`, the response includes information from segments that are not loaded into memory. - :param level: Indicates whether statistics are aggregated at the cluster, index, - or shard level. + :param level: Indicates whether statistics are aggregated at the node, indices, + or shards level. :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 types: A comma-separated list of document types for the indexing index @@ -501,8 +501,8 @@ async def usage( ``_ :param node_id: A comma-separated list of node IDs or names to limit the returned - information; use `_local` to return information from the node you're connecting - to, leave empty to get information from all nodes + information. Use `_local` to return information from the node you're connecting + to, leave empty to get information from all nodes. :param metric: Limits the information returned to the specific metrics. A comma-separated list of the following options: `_all`, `rest_actions`. :param timeout: Period to wait for a response. If no response is received before diff --git a/elasticsearch/_async/client/query_rules.py b/elasticsearch/_async/client/query_rules.py index 4e056f817..ec9d478f4 100644 --- a/elasticsearch/_async/client/query_rules.py +++ b/elasticsearch/_async/client/query_rules.py @@ -39,8 +39,8 @@ async def delete_rule( """ .. raw:: html -

                Delete a query rule. - Delete a query rule within a query ruleset. +

                Delete a query rule.

                +

                Delete a query rule within a query ruleset. This is a destructive action that is only recoverable by re-adding the same rule with the create or update query rule API.

                @@ -92,8 +92,8 @@ async def delete_ruleset( """ .. raw:: html -

                Delete a query ruleset. - Remove a query ruleset and its associated data. +

                Delete a query ruleset.

                +

                Remove a query ruleset and its associated data. This is a destructive action that is not recoverable.

                @@ -138,8 +138,8 @@ async def get_rule( """ .. raw:: html -

                Get a query rule. - Get details about a query rule within a query ruleset.

                +

                Get a query rule.

                +

                Get details about a query rule within a query ruleset.

                ``_ @@ -190,8 +190,8 @@ async def get_ruleset( """ .. raw:: html -

                Get a query ruleset. - Get details about a query ruleset.

                +

                Get a query ruleset.

                +

                Get details about a query ruleset.

                ``_ @@ -237,8 +237,8 @@ async def list_rulesets( """ .. raw:: html -

                Get all query rulesets. - Get summarized information about the query rulesets.

                +

                Get all query rulesets.

                +

                Get summarized information about the query rulesets.

                ``_ @@ -294,8 +294,8 @@ async def put_rule( """ .. raw:: html -

                Create or update a query rule. - Create or update a query rule within a query ruleset.

                +

                Create or update a query rule.

                +

                Create or update a query rule within a query ruleset.

                IMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. @@ -380,8 +380,8 @@ async def put_ruleset( """ .. raw:: html -

                Create or update a query ruleset. - There is a limit of 100 rules per ruleset. +

                Create or update a query ruleset.

                +

                There is a limit of 100 rules per ruleset. This limit can be increased by using the xpack.applications.rules.max_rules_per_ruleset cluster setting.

                IMPORTANT: Due to limitations within pinned queries, you can only select documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. @@ -442,8 +442,8 @@ async def test( """ .. raw:: html -

                Test a query ruleset. - Evaluate match criteria against a query ruleset to identify the rules that would match that criteria.

                +

                Test a query ruleset.

                +

                Evaluate match criteria against a query ruleset to identify the rules that would match that criteria.

                ``_ diff --git a/elasticsearch/_async/client/rollup.py b/elasticsearch/_async/client/rollup.py index ea1ace0dc..75d9f70b2 100644 --- a/elasticsearch/_async/client/rollup.py +++ b/elasticsearch/_async/client/rollup.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class RollupClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def delete_job( self, *, @@ -95,7 +95,7 @@ async def delete_job( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def get_jobs( self, *, @@ -108,8 +108,8 @@ async def get_jobs( """ .. raw:: html -

                Get rollup job information. - Get the configuration, stats, and status of rollup jobs.

                +

                Get rollup job information.

                +

                Get the configuration, stats, and status of rollup jobs.

                NOTE: This API returns only active (both STARTED and STOPPED) jobs. If a job was created, ran for a while, then was deleted, the API does not return any details about it. For details about a historical rollup job, the rollup capabilities API may be more useful.

                @@ -147,7 +147,7 @@ async def get_jobs( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def get_rollup_caps( self, *, @@ -160,8 +160,8 @@ async def get_rollup_caps( """ .. raw:: html -

                Get the rollup job capabilities. - Get the capabilities of any rollup jobs that have been configured for a specific index or index pattern.

                +

                Get the rollup job capabilities.

                +

                Get the capabilities of any rollup jobs that have been configured for a specific index or index pattern.

                This API is useful because a rollup job is often configured to rollup only a subset of fields from the source index. Furthermore, only certain aggregations can be configured for various fields, leading to a limited subset of functionality depending on that configuration. This API enables you to inspect an index and determine:

                @@ -203,7 +203,7 @@ async def get_rollup_caps( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def get_rollup_index_caps( self, *, @@ -216,8 +216,8 @@ async def get_rollup_index_caps( """ .. raw:: html -

                Get the rollup index capabilities. - Get the rollup capabilities of all jobs inside of a rollup index. +

                Get the rollup index capabilities.

                +

                Get the rollup capabilities of all jobs inside of a rollup index. A single rollup index may store the data for multiple rollup jobs and may have a variety of capabilities depending on those jobs. This API enables you to determine:

                • What jobs are stored in an index (or indices specified via a pattern)?
                • @@ -266,7 +266,7 @@ async def get_rollup_index_caps( ), ignore_deprecated_options={"headers"}, ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def put_job( self, *, @@ -392,7 +392,7 @@ async def put_job( @_rewrite_parameters( body_fields=("aggregations", "aggs", "query", "size"), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def rollup_search( self, *, @@ -412,8 +412,8 @@ async def rollup_search( """ .. raw:: html -

                  Search rolled-up data. - The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data. +

                  Search rolled-up data.

                  +

                  The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data. It rewrites standard Query DSL into a format that matches the rollup documents then takes the response and rewrites it back to what a client would expect given the original query.

                  The request body supports a subset of features from the regular search API. The following functionality is not available:

                  @@ -482,7 +482,7 @@ async def rollup_search( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def start_job( self, *, @@ -495,8 +495,8 @@ async def start_job( """ .. raw:: html -

                  Start rollup jobs. - If you try to start a job that does not exist, an exception occurs. +

                  Start rollup jobs.

                  +

                  If you try to start a job that does not exist, an exception occurs. If you try to start a job that is already started, nothing happens.

                  @@ -528,7 +528,7 @@ async def start_job( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def stop_job( self, *, @@ -543,8 +543,8 @@ async def stop_job( """ .. raw:: html -

                  Stop rollup jobs. - If you try to stop a job that does not exist, an exception occurs. +

                  Stop rollup jobs.

                  +

                  If you try to stop a job that does not exist, an exception occurs. If you try to stop a job that is already stopped, nothing happens.

                  Since only a stopped job can be deleted, it can be useful to block the API until the indexer has fully stopped. This is accomplished with the wait_for_completion query parameter, and optionally a timeout. For example:

                  diff --git a/elasticsearch/_async/client/search_application.py b/elasticsearch/_async/client/search_application.py index 30352bd67..30e57740c 100644 --- a/elasticsearch/_async/client/search_application.py +++ b/elasticsearch/_async/client/search_application.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class SearchApplicationClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def delete( self, *, @@ -77,7 +77,7 @@ async def delete( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def delete_behavioral_analytics( self, *, @@ -90,8 +90,8 @@ async def delete_behavioral_analytics( """ .. raw:: html -

                  Delete a behavioral analytics collection. - The associated data stream is also deleted.

                  +

                  Delete a behavioral analytics collection.

                  +

                  The associated data stream is also deleted.

                  ``_ @@ -122,7 +122,7 @@ async def delete_behavioral_analytics( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def get( self, *, @@ -166,7 +166,7 @@ async def get( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def get_behavioral_analytics( self, *, @@ -215,7 +215,7 @@ async def get_behavioral_analytics( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def list( self, *, @@ -230,8 +230,8 @@ async def list( """ .. raw:: html -

                  Get search applications. - Get information about search applications.

                  +

                  Get search applications.

                  +

                  Get information about search applications.

                  ``_ @@ -270,7 +270,7 @@ async def list( @_rewrite_parameters( body_name="payload", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def post_behavioral_analytics_event( self, *, @@ -338,7 +338,7 @@ async def post_behavioral_analytics_event( @_rewrite_parameters( body_name="search_application", ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def put( self, *, @@ -398,7 +398,7 @@ async def put( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def put_behavioral_analytics( self, *, @@ -445,7 +445,7 @@ async def put_behavioral_analytics( body_fields=("params",), ignore_deprecated_options={"params"}, ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def render_query( self, *, @@ -460,8 +460,8 @@ async def render_query( """ .. raw:: html -

                  Render a search application query. - Generate an Elasticsearch query using the specified query parameters and the search template associated with the search application or a default template if none is specified. +

                  Render a search application query.

                  +

                  Generate an Elasticsearch query using the specified query parameters and the search template associated with the search application or a default template if none is specified. If a parameter used in the search template is not specified in params, the parameter's default value will be used. The API returns the specific Elasticsearch query that would be generated and run by calling the search application search API.

                  You must have read privileges on the backing alias of the search application.

                  @@ -510,7 +510,7 @@ async def render_query( body_fields=("params",), ignore_deprecated_options={"params"}, ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) async def search( self, *, @@ -526,8 +526,8 @@ async def search( """ .. raw:: html -

                  Run a search application search. - Generate and run an Elasticsearch query that uses the specified query parameteter and the search template associated with the search application or default template. +

                  Run a search application search.

                  +

                  Generate and run an Elasticsearch query that uses the specified query parameteter and the search template associated with the search application or default template. Unspecified template parameters are assigned their default values if applicable.

                  diff --git a/elasticsearch/_async/client/searchable_snapshots.py b/elasticsearch/_async/client/searchable_snapshots.py index 9b6902fac..539932dd3 100644 --- a/elasticsearch/_async/client/searchable_snapshots.py +++ b/elasticsearch/_async/client/searchable_snapshots.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class SearchableSnapshotsClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def cache_stats( self, *, @@ -46,8 +46,8 @@ async def cache_stats( """ .. raw:: html -

                  Get cache statistics. - Get statistics about the shared cache for partially mounted indices.

                  +

                  Get cache statistics.

                  +

                  Get statistics about the shared cache for partially mounted indices.

                  ``_ @@ -84,7 +84,7 @@ async def cache_stats( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def clear_cache( self, *, @@ -107,8 +107,8 @@ async def clear_cache( """ .. raw:: html -

                  Clear the cache. - Clear indices and data streams from the shared cache for partially mounted indices.

                  +

                  Clear the cache.

                  +

                  Clear indices and data streams from the shared cache for partially mounted indices.

                  ``_ @@ -119,7 +119,7 @@ async def clear_cache( into no concrete indices. (This includes `_all` string or when no indices have been specified) :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. + that are open, closed or both :param ignore_unavailable: Whether specified concrete indices should be ignored when unavailable (missing or closed) """ @@ -184,8 +184,8 @@ async def mount( """ .. raw:: html -

                  Mount a snapshot. - Mount a snapshot as a searchable snapshot index. +

                  Mount a snapshot.

                  +

                  Mount a snapshot as a searchable snapshot index. Do not use this API for snapshots managed by index lifecycle management (ILM). Manually mounting ILM-managed snapshots can interfere with ILM processes.

                  diff --git a/elasticsearch/_async/client/security.py b/elasticsearch/_async/client/security.py index 516906ce8..793915030 100644 --- a/elasticsearch/_async/client/security.py +++ b/elasticsearch/_async/client/security.py @@ -288,8 +288,8 @@ async def bulk_update_api_keys( """ .. raw:: html -

                  Bulk update API keys. - Update the attributes for multiple API keys.

                  +

                  Bulk update API keys.

                  +

                  Update the attributes for multiple API keys.

                  IMPORTANT: It is not possible to use an API key as the authentication credential for this API. To update API keys, the owner user's credentials are required.

                  This API is similar to the update API key API but enables you to apply the same update to multiple API keys in one API call. This operation can greatly improve performance over making individual updates.

                  It is not possible to update expired or invalidated API keys.

                  @@ -892,8 +892,8 @@ async def create_service_token( Token names must be unique in the context of the associated service account. They must also be globally unique with their fully qualified names, which are comprised of the service account principal and token name, such as `//`. - :param refresh: If `true` then refresh the affected shards to make this operation - visible to search, if `wait_for` (the default) then wait for a refresh to + :param refresh: If `true` (the default) then refresh 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` then do nothing with refreshes. """ if namespace in SKIP_IN_PATH: @@ -1208,8 +1208,8 @@ async def delete_service_token( :param namespace: The namespace, which is a top-level grouping of service accounts. :param service: The service name. :param name: The name of the service account token. - :param refresh: If `true` then refresh the affected shards to make this operation - visible to search, if `wait_for` (the default) then wait for a refresh to + :param refresh: If `true` (the default) then refresh 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` then do nothing with refreshes. """ if namespace in SKIP_IN_PATH: @@ -3711,7 +3711,8 @@ async def query_role( :param size: The number of hits to return. It 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` parameter. - :param sort: The sort definition. You can sort on `username`, `roles`, or `enabled`. + :param sort: The sort definition. You can sort on `name`, `description`, `metadata`, + `applications.application`, `applications.privileges`, and `applications.resources`. In addition, sort can also be applied to the `_doc` field to sort by index order. """ diff --git a/elasticsearch/_async/client/shutdown.py b/elasticsearch/_async/client/shutdown.py index 5dbc33e92..697a95d49 100644 --- a/elasticsearch/_async/client/shutdown.py +++ b/elasticsearch/_async/client/shutdown.py @@ -20,7 +20,11 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + _quote, + _rewrite_parameters, +) class ShutdownClient(NamespacedClient): @@ -33,19 +37,15 @@ async def delete_node( 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["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = 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["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = None, + timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html -

                  Cancel node shutdown preparations. - Remove a node from the shutdown list so it can resume normal operations. +

                  Cancel node shutdown preparations.

                  +

                  Remove a node from the shutdown list so it can resume normal operations. You must explicitly clear the shutdown request when a node rejoins the cluster or when a node has permanently left the cluster. Shutdown requests are never removed automatically by Elasticsearch.

                  NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. @@ -97,9 +97,7 @@ async def get_node( 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["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -114,7 +112,8 @@ async def get_node( ``_ - :param node_id: Which node for which to retrieve the shutdown status + :param node_id: Comma-separated list of nodes for which to retrieve the shutdown + status :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. @@ -162,14 +161,10 @@ async def put_node( 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["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, target_node_name: t.Optional[str] = None, - timeout: 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, body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ diff --git a/elasticsearch/_async/client/simulate.py b/elasticsearch/_async/client/simulate.py index bb636ddb6..fda8ca507 100644 --- a/elasticsearch/_async/client/simulate.py +++ b/elasticsearch/_async/client/simulate.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -40,7 +40,7 @@ class SimulateClient(NamespacedClient): "pipeline_substitutions", ), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def ingest( self, *, @@ -66,8 +66,8 @@ async def ingest( """ .. raw:: html -

                  Simulate data ingestion. - Run ingest pipelines against a set of provided documents, optionally with substitute pipeline definitions, to simulate ingesting data into an index.

                  +

                  Simulate data ingestion.

                  +

                  Run ingest pipelines against a set of provided documents, optionally with substitute pipeline definitions, to simulate ingesting data into an index.

                  This API is meant to be used for troubleshooting or pipeline development, as it does not actually index any data into Elasticsearch.

                  The API runs the default and final pipeline for that index against a set of documents provided in the body of the request. If a pipeline contains a reroute processor, it follows that reroute processor to the new index, running that index's pipelines as well the same way that a non-simulated ingest would. diff --git a/elasticsearch/_async/client/slm.py b/elasticsearch/_async/client/slm.py index 3eaafd865..a157eb73e 100644 --- a/elasticsearch/_async/client/slm.py +++ b/elasticsearch/_async/client/slm.py @@ -40,8 +40,8 @@ async def delete_lifecycle( """ .. raw:: html -

                  Delete a policy. - Delete a snapshot lifecycle policy definition. +

                  Delete a policy.

                  +

                  Delete a snapshot lifecycle policy definition. This operation prevents any future snapshots from being taken but does not cancel in-progress snapshots or remove previously-taken snapshots.

                  @@ -96,8 +96,8 @@ async def execute_lifecycle( """ .. raw:: html -

                  Run a policy. - Immediately create a snapshot according to the snapshot lifecycle policy without waiting for the scheduled time. +

                  Run a policy.

                  +

                  Immediately create a snapshot according to the snapshot lifecycle policy without waiting for the scheduled time. The snapshot policy is normally applied according to its schedule, but you might want to manually run a policy before performing an upgrade or other maintenance.

                  @@ -151,8 +151,8 @@ async def execute_retention( """ .. raw:: html -

                  Run a retention policy. - Manually apply the retention policy to force immediate removal of snapshots that are expired according to the snapshot lifecycle policy retention rules. +

                  Run a retention policy.

                  +

                  Manually apply the retention policy to force immediate removal of snapshots that are expired according to the snapshot lifecycle policy retention rules. The retention policy is normally applied according to its schedule.

                  @@ -204,13 +204,13 @@ async def get_lifecycle( """ .. raw:: html -

                  Get policy information. - Get snapshot lifecycle policy definitions and information about the latest snapshot attempts.

                  +

                  Get policy information.

                  +

                  Get snapshot lifecycle policy definitions and information about the latest snapshot attempts.

                  ``_ - :param policy_id: Comma-separated list of snapshot lifecycle policies to retrieve + :param policy_id: A comma-separated list of snapshot lifecycle policy identifiers. :param master_timeout: The 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. @@ -261,8 +261,8 @@ async def get_stats( """ .. raw:: html -

                  Get snapshot lifecycle management statistics. - Get global and policy-level statistics about actions taken by snapshot lifecycle management.

                  +

                  Get snapshot lifecycle management statistics.

                  +

                  Get global and policy-level statistics about actions taken by snapshot lifecycle management.

                  ``_ @@ -373,8 +373,8 @@ async def put_lifecycle( """ .. raw:: html -

                  Create or update a policy. - Create or update a snapshot lifecycle policy. +

                  Create or update a policy.

                  +

                  Create or update a snapshot lifecycle policy. If the policy already exists, this request increments the policy version. Only the latest version of a policy is stored.

                  @@ -431,11 +431,7 @@ async def put_lifecycle( __body["retention"] = retention if schedule is not None: __body["schedule"] = schedule - 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] "PUT", __path, @@ -460,8 +456,8 @@ async def start( """ .. raw:: html -

                  Start snapshot lifecycle management. - Snapshot lifecycle management (SLM) starts automatically when a cluster is formed. +

                  Start snapshot lifecycle management.

                  +

                  Snapshot lifecycle management (SLM) starts automatically when a cluster is formed. Manually starting SLM is necessary only if it has been stopped using the stop SLM API.

                  @@ -514,8 +510,8 @@ async def stop( """ .. raw:: html -

                  Stop snapshot lifecycle management. - Stop all snapshot lifecycle management (SLM) operations and the SLM plugin. +

                  Stop snapshot lifecycle management.

                  +

                  Stop all snapshot lifecycle management (SLM) operations and the SLM plugin. This API is useful when you are performing maintenance on a cluster and need to prevent SLM from performing any actions on your data streams or indices. Stopping SLM does not stop any snapshots that are in progress. You can manually trigger snapshots with the run snapshot lifecycle policy API even if SLM is stopped.

                  diff --git a/elasticsearch/_async/client/snapshot.py b/elasticsearch/_async/client/snapshot.py index c4ece9be9..0edd2620b 100644 --- a/elasticsearch/_async/client/snapshot.py +++ b/elasticsearch/_async/client/snapshot.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -46,8 +46,8 @@ async def cleanup_repository( """ .. raw:: html -

                  Clean up the snapshot repository. - Trigger the review of the contents of a snapshot repository and delete any stale data not referenced by existing snapshots.

                  +

                  Clean up the snapshot repository.

                  +

                  Trigger the review of the contents of a snapshot repository and delete any stale data not referenced by existing snapshots.

                  ``_ @@ -110,8 +110,8 @@ async def clone( """ .. raw:: html -

                  Clone a snapshot. - Clone part of all of a snapshot into another snapshot in the same repository.

                  +

                  Clone a snapshot.

                  +

                  Clone part of all of a snapshot into another snapshot in the same repository.

                  ``_ @@ -207,8 +207,8 @@ async def create( """ .. raw:: html -

                  Create a snapshot. - Take a snapshot of a cluster or of data streams and indices.

                  +

                  Create a snapshot.

                  +

                  Take a snapshot of a cluster or of data streams and indices.

                  ``_ @@ -330,8 +330,8 @@ async def create_repository( """ .. raw:: html -

                  Create or update a snapshot repository. - IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters. +

                  Create or update a snapshot repository.

                  +

                  IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters. To register a snapshot repository, the cluster's global metadata must be writeable. Ensure there are no cluster blocks (for example, cluster.blocks.read_only and clsuter.blocks.read_only_allow_delete settings) that prevent write access.

                  Several options for this API can be specified using a query parameter or a request body parameter. @@ -470,8 +470,8 @@ async def delete_repository( """ .. raw:: html -

                  Delete snapshot repositories. - When a repository is unregistered, Elasticsearch removes only the reference to the location where the repository is storing the snapshots. +

                  Delete snapshot repositories.

                  +

                  When a repository is unregistered, Elasticsearch removes only the reference to the location where the repository is storing the snapshots. The snapshots themselves are left untouched and in place.

                  @@ -950,7 +950,7 @@ async def repository_analyze( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def repository_verify_integrity( self, *, @@ -971,8 +971,8 @@ async def repository_verify_integrity( """ .. raw:: html -

                  Verify the repository integrity. - Verify the integrity of the contents of a snapshot repository.

                  +

                  Verify the repository integrity.

                  +

                  Verify the integrity of the contents of a snapshot repository.

                  This API enables you to perform a comprehensive check of the contents of a repository, looking for any anomalies in its data or metadata which might prevent you from restoring snapshots from the repository or which might cause future snapshot create or delete operations to fail.

                  If you suspect the integrity of the contents of one of your snapshot repositories, cease all write activity to this repository immediately, set its read_only option to true, and use this API to verify its integrity. Until you do so:

                  @@ -1110,8 +1110,8 @@ async def restore( """ .. raw:: html -

                  Restore a snapshot. - Restore a snapshot of a cluster or data streams and indices.

                  +

                  Restore a snapshot.

                  +

                  Restore a snapshot of a cluster or data streams and indices.

                  You can restore a snapshot only to a running cluster with an elected master node. The snapshot repository must be registered and available to the cluster. The snapshot and cluster versions must be compatible.

                  @@ -1259,18 +1259,13 @@ async def status( """ .. raw:: html -

                  Get the snapshot status. - Get a detailed description of the current state for each shard participating in the snapshot.

                  +

                  Get the snapshot status.

                  +

                  Get a detailed description of the current state for each shard participating in the snapshot.

                  Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. If this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.

                  If you omit the <snapshot> request path parameter, the request retrieves information only for currently running snapshots. This usage is preferred. If needed, you can specify <repository> and <snapshot> to retrieve information for specific snapshots, even if they're not currently running.

                  -

                  Note that the stats will not be available for any shard snapshots in an ongoing snapshot completed by a node that (even momentarily) left the cluster. - Loading the stats from the repository is an expensive operation (see the WARNING below). - Therefore the stats values for such shards will be -1 even though the "stage" value will be "DONE", in order to minimize latency. - A "description" field will be present for a shard snapshot completed by a departed node explaining why the shard snapshot's stats results are invalid. - Consequently, the total stats for the index will be less than expected due to the missing values from these shards.

                  WARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive. The API requires a read from the repository for each shard in each snapshot. For example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).

                  @@ -1342,8 +1337,8 @@ async def verify_repository( """ .. raw:: html -

                  Verify a snapshot repository. - Check for common misconfigurations in a snapshot repository.

                  +

                  Verify a snapshot repository.

                  +

                  Check for common misconfigurations in a snapshot repository.

                  ``_ diff --git a/elasticsearch/_async/client/sql.py b/elasticsearch/_async/client/sql.py index 3eb37a6cc..133844023 100644 --- a/elasticsearch/_async/client/sql.py +++ b/elasticsearch/_async/client/sql.py @@ -89,8 +89,8 @@ async def delete_async( """ .. raw:: html -

                  Delete an async SQL search. - Delete an async SQL search or a stored synchronous SQL search. +

                  Delete an async SQL search.

                  +

                  Delete an async SQL search or a stored synchronous SQL search. If the search is still running, the API cancels it.

                  If the Elasticsearch security features are enabled, only the following users can use this API to delete a search:

                    @@ -145,8 +145,8 @@ async def get_async( """ .. raw:: html -

                    Get async SQL search results. - Get the current status and available results for an async SQL search or stored synchronous SQL search.

                    +

                    Get async SQL search results.

                    +

                    Get the current status and available results for an async SQL search or stored synchronous SQL search.

                    If the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.

                    @@ -208,8 +208,8 @@ async def get_async_status( """ .. raw:: html -

                    Get the async SQL search status. - Get the current status of an async SQL search or a stored synchronous SQL search.

                    +

                    Get the async SQL search status.

                    +

                    Get the current status of an async SQL search or a stored synchronous SQL search.

                    ``_ @@ -283,7 +283,7 @@ async def query( keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, keep_on_completion: t.Optional[bool] = None, page_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, - params: t.Optional[t.Mapping[str, t.Any]] = None, + params: t.Optional[t.Sequence[t.Any]] = None, pretty: t.Optional[bool] = None, query: t.Optional[str] = None, request_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, @@ -297,8 +297,8 @@ async def query( """ .. raw:: html -

                    Get SQL search results. - Run an SQL request.

                    +

                    Get SQL search results.

                    +

                    Run an SQL request.

                    ``_ @@ -422,8 +422,8 @@ async def translate( """ .. raw:: html -

                    Translate SQL into Elasticsearch queries. - Translate an SQL search into a search API request containing Query DSL. +

                    Translate SQL into Elasticsearch queries.

                    +

                    Translate an SQL search into a search API request containing Query DSL. It accepts the same request body parameters as the SQL search API, excluding cursor.

                    diff --git a/elasticsearch/_async/client/streams.py b/elasticsearch/_async/client/streams.py new file mode 100644 index 000000000..76f813904 --- /dev/null +++ b/elasticsearch/_async/client/streams.py @@ -0,0 +1,186 @@ +# Licensed to Elasticsearch B.V. under one or more contributor +# license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright +# ownership. Elasticsearch B.V. licenses this file to you under +# the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +import typing as t + +from elastic_transport import ObjectApiResponse, TextApiResponse + +from ._base import NamespacedClient +from .utils import ( + Stability, + _availability_warning, + _rewrite_parameters, +) + + +class StreamsClient(NamespacedClient): + + @_rewrite_parameters() + @_availability_warning(Stability.EXPERIMENTAL) + async def logs_disable( + self, + *, + 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, + ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: + """ + .. raw:: html + +

                    Disable logs stream.

                    +

                    Turn off the logs stream feature for this cluster.

                    + + + ``_ + + :param master_timeout: The 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: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_streams/logs/_disable" + __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 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": "text/plain,application/json"} + return await self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + endpoint_id="streams.logs_disable", + path_parts=__path_parts, + ) + + @_rewrite_parameters() + @_availability_warning(Stability.EXPERIMENTAL) + async def logs_enable( + self, + *, + 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, + ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: + """ + .. raw:: html + +

                    Enable logs stream.

                    +

                    Turn on the logs stream feature for this cluster.

                    +

                    NOTE: To protect existing data, this feature can be turned on only if the + cluster does not have existing indices or data streams that match the pattern logs|logs.*. + If those indices or data streams exist, a 409 - Conflict response and error is returned.

                    + + + ``_ + + :param master_timeout: The 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: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_streams/logs/_enable" + __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 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": "text/plain,application/json"} + return await self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + endpoint_id="streams.logs_enable", + path_parts=__path_parts, + ) + + @_rewrite_parameters() + @_availability_warning(Stability.EXPERIMENTAL) + async def status( + self, + *, + 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["d", "h", "m", "micros", "ms", "nanos", "s"]] + ] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + .. raw:: html + +

                    Get the status of streams.

                    +

                    Get the current status for all types of streams.

                    + + + ``_ + + :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 = "/_streams/status" + __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 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"} + return await self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="streams.status", + path_parts=__path_parts, + ) diff --git a/elasticsearch/_async/client/synonyms.py b/elasticsearch/_async/client/synonyms.py index 2466dfb6c..34edb0c77 100644 --- a/elasticsearch/_async/client/synonyms.py +++ b/elasticsearch/_async/client/synonyms.py @@ -95,8 +95,8 @@ async def delete_synonym_rule( """ .. raw:: html -

                    Delete a synonym rule. - Delete a synonym rule from a synonym set.

                    +

                    Delete a synonym rule.

                    +

                    Delete a synonym rule from a synonym set.

                    ``_ @@ -204,8 +204,8 @@ async def get_synonym_rule( """ .. raw:: html -

                    Get a synonym rule. - Get a synonym rule from a synonym set.

                    +

                    Get a synonym rule.

                    +

                    Get a synonym rule from a synonym set.

                    ``_ @@ -257,8 +257,8 @@ async def get_synonyms_sets( """ .. raw:: html -

                    Get all synonym sets. - Get a summary of all defined synonym sets.

                    +

                    Get all synonym sets.

                    +

                    Get a summary of all defined synonym sets.

                    ``_ @@ -311,8 +311,8 @@ async def put_synonym( """ .. raw:: html -

                    Create or update a synonym set. - Synonyms sets are limited to a maximum of 10,000 synonym rules per set. +

                    Create or update a synonym set.

                    +

                    Synonyms sets are limited to a maximum of 10,000 synonym rules per set. If you need to manage more synonym rules, you can create multiple synonym sets.

                    When an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices. This is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.

                    @@ -378,8 +378,8 @@ async def put_synonym_rule( """ .. raw:: html -

                    Create or update a synonym rule. - Create or update a synonym rule in a synonym set.

                    +

                    Create or update a synonym rule.

                    +

                    Create or update a synonym rule in a synonym set.

                    If any of the synonym rules included is invalid, the API returns an error.

                    When you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.

                    diff --git a/elasticsearch/_async/client/tasks.py b/elasticsearch/_async/client/tasks.py index 96230cc4c..53e2faaaa 100644 --- a/elasticsearch/_async/client/tasks.py +++ b/elasticsearch/_async/client/tasks.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class TasksClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def cancel( self, *, @@ -106,7 +106,7 @@ async def cancel( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def get( self, *, @@ -121,8 +121,8 @@ async def get( """ .. raw:: html -

                    Get task information. - Get information about a task currently running in the cluster.

                    +

                    Get task information.

                    +

                    Get information about a task currently running in the cluster.

                    WARNING: The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible.

                    If the task identifier is not found, a 404 response code indicates that there are no resources that match the request.

                    @@ -164,7 +164,7 @@ async def get( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) async def list( self, *, @@ -185,8 +185,8 @@ async def list( """ .. raw:: html -

                    Get all tasks. - Get information about the tasks currently running on one or more nodes in the cluster.

                    +

                    Get all tasks.

                    +

                    Get information about the tasks currently running on one or more nodes in the cluster.

                    WARNING: The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible.

                    Identifying running tasks

                    diff --git a/elasticsearch/_async/client/text_structure.py b/elasticsearch/_async/client/text_structure.py index 6307f20bb..98d3cbf82 100644 --- a/elasticsearch/_async/client/text_structure.py +++ b/elasticsearch/_async/client/text_structure.py @@ -55,8 +55,8 @@ async def find_field_structure( """ .. raw:: html -

                    Find the structure of a text field. - Find the structure of a text field in an Elasticsearch index.

                    +

                    Find the structure of a text field.

                    +

                    Find the structure of a text field in an Elasticsearch index.

                    This API provides a starting point for extracting further information from log messages already ingested into Elasticsearch. For example, if you have ingested data into a very simple index that has just @timestamp and message fields, you can use this API to see what common structure exists in the message field.

                    The response from the API contains:

                    @@ -241,8 +241,8 @@ async def find_message_structure( """ .. raw:: html -

                    Find the structure of text messages. - Find the structure of a list of text messages. +

                    Find the structure of text messages.

                    +

                    Find the structure of a list of text messages. The messages must contain data that is suitable to be ingested into Elasticsearch.

                    This API provides a starting point for ingesting data into Elasticsearch in a format that is suitable for subsequent use with other Elastic Stack functionality. Use this API rather than the find text structure API if your input text has already been split up into separate messages by some other process.

                    @@ -402,7 +402,11 @@ async def find_structure( delimiter: t.Optional[str] = None, ecs_compatibility: t.Optional[str] = None, explain: t.Optional[bool] = None, - format: t.Optional[str] = None, + format: t.Optional[ + t.Union[ + str, t.Literal["delimited", "ndjson", "semi_structured_text", "xml"] + ] + ] = None, grok_pattern: t.Optional[str] = None, has_header_row: t.Optional[bool] = None, line_merge_size_limit: t.Optional[int] = None, @@ -416,8 +420,8 @@ async def find_structure( """ .. raw:: html -

                    Find the structure of a text file. - The text file must contain data that is suitable to be ingested into Elasticsearch.

                    +

                    Find the structure of a text file.

                    +

                    The text file must contain data that is suitable to be ingested into Elasticsearch.

                    This API provides a starting point for ingesting data into Elasticsearch in a format that is suitable for subsequent use with other Elastic Stack functionality. Unlike other Elasticsearch endpoints, the data that is posted to this endpoint does not need to be UTF-8 encoded and in JSON format. It must, however, be text; binary text formats are not currently supported. @@ -615,8 +619,8 @@ async def test_grok_pattern( """ .. raw:: html -

                    Test a Grok pattern. - Test a Grok pattern on one or more lines of text. +

                    Test a Grok pattern.

                    +

                    Test a Grok pattern on one or more lines of text. The API indicates whether the lines match the pattern together with the offsets and lengths of the matched substrings.

                    diff --git a/elasticsearch/_async/client/transform.py b/elasticsearch/_async/client/transform.py index 191c959d3..165ddf6d1 100644 --- a/elasticsearch/_async/client/transform.py +++ b/elasticsearch/_async/client/transform.py @@ -85,6 +85,45 @@ async def delete_transform( path_parts=__path_parts, ) + @_rewrite_parameters() + async def get_node_stats( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + .. raw:: html + +

                    Get node stats.

                    +

                    Get per-node information about transform usage.

                    + + + ``_ + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_transform/_node_stats" + __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 human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="transform.get_node_stats", + path_parts=__path_parts, + ) + @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) @@ -104,8 +143,8 @@ async def get_transform( """ .. raw:: html -

                    Get transforms. - Get configuration information for transforms.

                    +

                    Get transforms.

                    +

                    Get configuration information for transforms.

                    ``_ @@ -262,8 +301,8 @@ async def preview_transform( """ .. raw:: html -

                    Preview a transform. - Generates a preview of the results that you will get when you create a transform with the same configuration.

                    +

                    Preview a transform.

                    +

                    Generates a preview of the results that you will get when you create a transform with the same configuration.

                    It returns a maximum of 100 results. The calculations are based on all the current data in the source index. It also generates a list of mappings and settings for the destination index. These values are determined based on the field types of the source index and the transform aggregations.

                    @@ -386,8 +425,8 @@ async def put_transform( """ .. raw:: html -

                    Create a transform. - Creates a transform.

                    +

                    Create a transform.

                    +

                    Creates a transform.

                    A transform copies data from source indices, transforms it, and persists it into an entity-centric destination index. You can also think of the destination index as a two-dimensional tabular data structure (known as a data frame). The ID for each document in the data frame is generated from a hash of the entity, so there is a unique row per entity.

                    @@ -602,6 +641,66 @@ async def schedule_now_transform( path_parts=__path_parts, ) + @_rewrite_parameters() + async def set_upgrade_mode( + self, + *, + enabled: t.Optional[bool] = None, + error_trace: t.Optional[bool] = None, + 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]: + """ + .. raw:: html + +

                    Set upgrade_mode for transform indices.

                    +

                    Sets a cluster wide upgrade_mode setting that prepares transform + indices for an upgrade. + When upgrading your cluster, in some circumstances you must restart your + nodes and reindex your transform indices. In those circumstances, + there must be no transforms running. You can close the transforms, + do the upgrade, then open all the transforms again. Alternatively, + you can use this API to temporarily halt tasks associated with the transforms + and prevent new transforms from opening. You can also use this API + during upgrades that do not require you to reindex your transform + indices, though stopping transforms is not a requirement in that case. + You can see the current value for the upgrade_mode setting by using the get + transform info API.

                    + + + ``_ + + :param enabled: When `true`, it enables `upgrade_mode` which temporarily halts + all transform tasks and prohibits new transform tasks from starting. + :param timeout: The time to wait for the request to be completed. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_transform/set_upgrade_mode" + __query: t.Dict[str, t.Any] = {} + if enabled is not None: + __query["enabled"] = enabled + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __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] + "POST", + __path, + params=__query, + headers=__headers, + endpoint_id="transform.set_upgrade_mode", + path_parts=__path_parts, + ) + @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) @@ -689,8 +788,8 @@ async def stop_transform( """ .. raw:: html -

                    Stop transforms. - Stops one or more transforms.

                    +

                    Stop transforms.

                    +

                    Stops one or more transforms.

                    ``_ @@ -786,8 +885,8 @@ async def update_transform( """ .. raw:: html -

                    Update a transform. - Updates certain properties of a transform.

                    +

                    Update a transform.

                    +

                    Updates certain properties of a transform.

                    All updated properties except description do not take effect until after the transform starts the next checkpoint, thus there is data consistency in each checkpoint. To use this API, you must have read and view_index_metadata privileges for the source indices. You must also have index and read privileges for the destination index. When diff --git a/elasticsearch/_async/client/utils.py b/elasticsearch/_async/client/utils.py index 97918d9e4..3ccd0fc36 100644 --- a/elasticsearch/_async/client/utils.py +++ b/elasticsearch/_async/client/utils.py @@ -21,11 +21,12 @@ CLIENT_META_SERVICE, SKIP_IN_PATH, Stability, + Visibility, + _availability_warning, _base64_auth_header, _quote, _quote_query, _rewrite_parameters, - _stability_warning, client_node_configs, is_requests_http_auth, is_requests_node_class, @@ -40,9 +41,10 @@ "_TYPE_HOSTS", "SKIP_IN_PATH", "Stability", + "Visibility", "client_node_configs", "_rewrite_parameters", - "_stability_warning", + "_availability_warning", "is_requests_http_auth", "is_requests_node_class", ] diff --git a/elasticsearch/_async/client/watcher.py b/elasticsearch/_async/client/watcher.py index e0b7b39ec..147d235bd 100644 --- a/elasticsearch/_async/client/watcher.py +++ b/elasticsearch/_async/client/watcher.py @@ -39,8 +39,8 @@ async def ack_watch( """ .. raw:: html -

                    Acknowledge a watch. - Acknowledging a watch enables you to manually throttle the execution of the watch's actions.

                    +

                    Acknowledge a watch.

                    +

                    Acknowledging a watch enables you to manually throttle the execution of the watch's actions.

                    The acknowledgement state of an action is stored in the status.actions.<id>.ack.state structure.

                    IMPORTANT: If the specified watch is currently being executed, this API will return an error The reason for this behavior is to prevent overwriting the watch status from a watch execution.

                    @@ -101,8 +101,8 @@ async def activate_watch( """ .. raw:: html -

                    Activate a watch. - A watch can be either active or inactive.

                    +

                    Activate a watch.

                    +

                    A watch can be either active or inactive.

                    ``_ @@ -145,8 +145,8 @@ async def deactivate_watch( """ .. raw:: html -

                    Deactivate a watch. - A watch can be either active or inactive.

                    +

                    Deactivate a watch.

                    +

                    A watch can be either active or inactive.

                    ``_ @@ -189,8 +189,8 @@ async def delete_watch( """ .. raw:: html -

                    Delete a watch. - When the watch is removed, the document representing the watch in the .watches index is gone and it will never be run again.

                    +

                    Delete a watch.

                    +

                    When the watch is removed, the document representing the watch in the .watches index is gone and it will never be run again.

                    Deleting a watch does not delete any watch execution records related to this watch from the watch history.

                    IMPORTANT: Deleting a watch must be done by using only this API. Do not delete the watch directly from the .watches index using the Elasticsearch delete document API @@ -266,8 +266,8 @@ async def execute_watch( """ .. raw:: html -

                    Run a watch. - This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

                    +

                    Run a watch.

                    +

                    This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

                    For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can run the watch without running all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.

                    @@ -362,8 +362,8 @@ async def get_settings( """ .. raw:: html -

                    Get Watcher index settings. - Get settings for the Watcher internal index (.watches). +

                    Get Watcher index settings.

                    +

                    Get settings for the Watcher internal index (.watches). Only a subset of settings are shown, for example index.auto_expand_replicas and index.number_of_replicas.

                    @@ -476,8 +476,8 @@ async def put_watch( """ .. raw:: html -

                    Create or update a watch. - When a watch is registered, a new document that represents the watch is added to the .watches index and its trigger is immediately registered with the relevant trigger engine. +

                    Create or update a watch.

                    +

                    When a watch is registered, a new document that represents the watch is added to the .watches index and its trigger is immediately registered with the relevant trigger engine. Typically for the schedule trigger, the scheduler is the trigger engine.

                    IMPORTANT: You must use Kibana or this API to create a watch. Do not add a watch directly to the .watches index by using the Elasticsearch index API. @@ -494,9 +494,9 @@ async def put_watch( :param active: The initial state of the watch. The default value is `true`, which means the watch is active by default. :param condition: The condition that defines if the actions should be run. - :param if_primary_term: only update the watch if the last operation that has + :param if_primary_term: Only update the watch if the last operation that has changed the watch has the specified primary term - :param if_seq_no: only update the watch if the last operation that has changed + :param if_seq_no: Only update the watch if the last operation that has changed the watch has the specified sequence number :param input: The input that defines the input that loads the data for the watch. :param metadata: Metadata JSON that will be copied into the history entries. @@ -552,11 +552,7 @@ async def put_watch( __body["transform"] = transform if trigger is not None: __body["trigger"] = trigger - 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] "PUT", __path, @@ -595,8 +591,8 @@ async def query_watches( """ .. raw:: html -

                    Query watches. - Get all registered watches in a paginated manner and optionally filter watches by a query.

                    +

                    Query watches.

                    +

                    Get all registered watches in a paginated manner and optionally filter watches by a query.

                    Note that only the _id and metadata.* fields are queryable or sortable.

                    @@ -671,8 +667,8 @@ async def start( """ .. raw:: html -

                    Start the watch service. - Start the Watcher service if it is not already running.

                    +

                    Start the watch service.

                    +

                    Start the Watcher service if it is not already running.

                    ``_ @@ -736,8 +732,8 @@ async def stats( """ .. raw:: html -

                    Get Watcher statistics. - This API always returns basic metrics. +

                    Get Watcher statistics.

                    +

                    This API always returns basic metrics. You retrieve more metrics by using the metric parameter.

                    @@ -788,8 +784,8 @@ async def stop( """ .. raw:: html -

                    Stop the watch service. - Stop the Watcher service if it is running.

                    +

                    Stop the watch service.

                    +

                    Stop the Watcher service if it is running.

                    ``_ @@ -844,8 +840,8 @@ async def update_settings( """ .. raw:: html -

                    Update Watcher index settings. - Update settings for the Watcher internal index (.watches). +

                    Update Watcher index settings.

                    +

                    Update settings for the Watcher internal index (.watches). Only a subset of settings can be modified. This includes index.auto_expand_replicas, index.number_of_replicas, index.routing.allocation.exclude.*, index.routing.allocation.include.* and index.routing.allocation.require.*. diff --git a/elasticsearch/_async/client/xpack.py b/elasticsearch/_async/client/xpack.py index 710d36cb1..9365e1c21 100644 --- a/elasticsearch/_async/client/xpack.py +++ b/elasticsearch/_async/client/xpack.py @@ -45,8 +45,8 @@ async def info( """ .. raw:: html -

                    Get information. - The information provided by the API includes:

                    +

                    Get information.

                    +

                    The information provided by the API includes:

                    • Build information including the build number and timestamp.
                    • License information about the currently installed license.
                    • @@ -56,7 +56,8 @@ async def info( ``_ - :param accept_enterprise: If this param is used it must be set to true + :param accept_enterprise: If used, this otherwise ignored parameter must be set + to true :param categories: A comma-separated list of the information categories to include in the response. For example, `build,license,features`. """ @@ -98,8 +99,8 @@ async def usage( """ .. raw:: html -

                      Get usage information. - Get information about the features that are currently enabled and available under the current license. +

                      Get usage information.

                      +

                      Get information about the features that are currently enabled and available under the current license. The API also provides some usage statistics.

                      diff --git a/elasticsearch/_async/helpers.py b/elasticsearch/_async/helpers.py index e4d5e6bc5..c9243af63 100644 --- a/elasticsearch/_async/helpers.py +++ b/elasticsearch/_async/helpers.py @@ -33,12 +33,16 @@ Union, ) +from ..compat import safe_task from ..exceptions import ApiError, NotFoundError, TransportError from ..helpers.actions import ( _TYPE_BULK_ACTION, _TYPE_BULK_ACTION_BODY, _TYPE_BULK_ACTION_HEADER, _TYPE_BULK_ACTION_HEADER_AND_BODY, + _TYPE_BULK_ACTION_HEADER_WITH_META_AND_BODY, + _TYPE_BULK_ACTION_WITH_META, + BulkMeta, _ActionChunker, _process_bulk_chunk_error, _process_bulk_chunk_success, @@ -54,9 +58,10 @@ async def _chunk_actions( - actions: AsyncIterable[_TYPE_BULK_ACTION_HEADER_AND_BODY], + actions: AsyncIterable[_TYPE_BULK_ACTION_HEADER_WITH_META_AND_BODY], chunk_size: int, max_chunk_bytes: int, + flush_after_seconds: Optional[float], serializer: Serializer, ) -> AsyncIterable[ Tuple[ @@ -76,10 +81,42 @@ async def _chunk_actions( chunker = _ActionChunker( chunk_size=chunk_size, max_chunk_bytes=max_chunk_bytes, serializer=serializer ) - async for action, data in actions: - ret = chunker.feed(action, data) - if ret: - yield ret + + if not flush_after_seconds: + async for action, data in actions: + ret = chunker.feed(action, data) + if ret: + yield ret + else: + item_queue: asyncio.Queue[_TYPE_BULK_ACTION_HEADER_WITH_META_AND_BODY] = ( + asyncio.Queue() + ) + + async def get_items() -> None: + try: + async for item in actions: + await item_queue.put(item) + finally: + await item_queue.put((BulkMeta.done, None)) + + async with safe_task(get_items()): + timeout: Optional[float] = flush_after_seconds + while True: + try: + action, data = await asyncio.wait_for( + item_queue.get(), timeout=timeout + ) + timeout = flush_after_seconds + except asyncio.TimeoutError: + action, data = BulkMeta.flush, None + timeout = None + + if action is BulkMeta.done: + break + ret = chunker.feed(action, data) + if ret: + yield ret + ret = chunker.flush() if ret: yield ret @@ -159,9 +196,13 @@ async def azip( async def async_streaming_bulk( client: AsyncElasticsearch, - actions: Union[Iterable[_TYPE_BULK_ACTION], AsyncIterable[_TYPE_BULK_ACTION]], + actions: Union[ + Iterable[_TYPE_BULK_ACTION_WITH_META], + AsyncIterable[_TYPE_BULK_ACTION_WITH_META], + ], chunk_size: int = 500, max_chunk_bytes: int = 100 * 1024 * 1024, + flush_after_seconds: Optional[float] = None, raise_on_error: bool = True, expand_action_callback: Callable[ [_TYPE_BULK_ACTION], _TYPE_BULK_ACTION_HEADER_AND_BODY @@ -194,6 +235,9 @@ async def async_streaming_bulk( :arg actions: iterable or async iterable containing the actions to be executed :arg chunk_size: number of docs in one chunk sent to es (default: 500) :arg max_chunk_bytes: the maximum size of the request in bytes (default: 100MB) + :arg flush_after_seconds: time in seconds after which a chunk is written even + if hasn't reached `chunk_size` or `max_chunk_bytes`. Set to 0 to not use a + timeout-based flush. (default: 0) :arg raise_on_error: raise ``BulkIndexError`` containing errors (as `.errors`) from the execution of the last chunk when some occur. By default we raise. :arg raise_on_exception: if ``False`` then don't propagate exceptions from @@ -220,9 +264,14 @@ async def async_streaming_bulk( if isinstance(retry_on_status, int): retry_on_status = (retry_on_status,) - async def map_actions() -> AsyncIterable[_TYPE_BULK_ACTION_HEADER_AND_BODY]: + async def map_actions() -> ( + AsyncIterable[_TYPE_BULK_ACTION_HEADER_WITH_META_AND_BODY] + ): async for item in aiter(actions): - yield expand_action_callback(item) + if isinstance(item, BulkMeta): + yield item, None + else: + yield expand_action_callback(item) serializer = client.transport.serializers.get_serializer("application/json") @@ -234,7 +283,7 @@ async def map_actions() -> AsyncIterable[_TYPE_BULK_ACTION_HEADER_AND_BODY]: ] bulk_actions: List[bytes] async for bulk_data, bulk_actions in _chunk_actions( - map_actions(), chunk_size, max_chunk_bytes, serializer + map_actions(), chunk_size, max_chunk_bytes, flush_after_seconds, serializer ): for attempt in range(max_retries + 1): to_retry: List[bytes] = [] diff --git a/elasticsearch/_sync/client/__init__.py b/elasticsearch/_sync/client/__init__.py index 5f7a4313d..bdec16efd 100644 --- a/elasticsearch/_sync/client/__init__.py +++ b/elasticsearch/_sync/client/__init__.py @@ -74,6 +74,7 @@ from .snapshot import SnapshotClient from .sql import SqlClient from .ssl import SslClient +from .streams import StreamsClient from .synonyms import SynonymsClient from .tasks import TasksClient from .text_structure import TextStructureClient @@ -83,9 +84,9 @@ CLIENT_META_SERVICE, SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, client_node_configs, is_requests_http_auth, is_requests_node_class, @@ -378,6 +379,7 @@ def __init__( self.shutdown = ShutdownClient(self) self.sql = SqlClient(self) self.ssl = SslClient(self) + self.streams = StreamsClient(self) self.synonyms = SynonymsClient(self) self.text_structure = TextStructureClient(self) self.transform = TransformClient(self) @@ -500,6 +502,7 @@ def ping( """ __path = "/" __query: t.Dict[str, t.Any] = {} + __path_parts: t.Dict[str, str] = {} if error_trace is not None: __query["error_trace"] = error_trace if filter_path is not None: @@ -510,7 +513,14 @@ def ping( __query["pretty"] = pretty __headers = {"accept": "application/json"} try: - self.perform_request("HEAD", __path, params=__query, headers=__headers) + self.perform_request( + "HEAD", + __path, + params=__query, + headers=__headers, + endpoint_id="ping", + path_parts=__path_parts, + ) return True except (ApiError, TransportError): return False @@ -555,8 +565,8 @@ def bulk( """ .. raw:: html -

                      Bulk index or delete documents. - Perform multiple index, create, delete, and update actions in a single request. +

                      Bulk index or delete documents.

                      +

                      Perform multiple index, create, delete, and update actions in a single request. This reduces overhead and can greatly increase indexing speed.

                      If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

                        @@ -606,6 +616,7 @@ def bulk(
                      • JavaScript: Check out client.helpers.*
                      • .NET: Check out BulkAllObservable
                      • PHP: Check out bulk indexing.
                      • +
                      • Ruby: Check out Elasticsearch::Helpers::BulkHelper

                      Submitting bulk requests with cURL

                      If you're providing text file input to curl, you must use the --data-binary flag instead of plain -d. @@ -760,8 +771,8 @@ def clear_scroll( """ .. raw:: html -

                      Clear a scrolling search. - Clear the search context and results for a scrolling search.

                      +

                      Clear a scrolling search.

                      +

                      Clear the search context and results for a scrolling search.

                      ``_ @@ -814,8 +825,8 @@ def close_point_in_time( """ .. raw:: html -

                      Close a point in time. - A point in time must be opened explicitly before being used in search requests. +

                      Close a point in time.

                      +

                      A point in time must be opened explicitly before being used in search requests. The keep_alive parameter tells Elasticsearch how long it should persist. A point in time is automatically closed when the keep_alive period has elapsed. However, keeping points in time has a cost; close them as soon as they are no longer required for search requests.

                      @@ -842,11 +853,7 @@ def close_point_in_time( if not __body: if id is not None: __body["id"] = id - 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 self.perform_request( # type: ignore[return-value] "DELETE", __path, @@ -895,8 +902,8 @@ def count( """ .. raw:: html -

                      Count search results. - Get the number of documents matching a query.

                      +

                      Count search results.

                      +

                      Get the number of documents matching a query.

                      The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body. The query is optional. When no query is provided, the API uses match_all to count all the documents.

                      The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.

                      @@ -1324,7 +1331,7 @@ def delete( ) @_rewrite_parameters( - body_fields=("max_docs", "query", "slice"), + body_fields=("max_docs", "query", "slice", "sort"), parameter_aliases={"from": "from_"}, ) def delete_by_query( @@ -1368,7 +1375,12 @@ def delete_by_query( ] = None, slice: t.Optional[t.Mapping[str, t.Any]] = None, slices: t.Optional[t.Union[int, t.Union[str, t.Literal["auto"]]]] = None, - sort: t.Optional[t.Sequence[str]] = None, + sort: t.Optional[ + t.Union[ + t.Sequence[t.Union[str, t.Mapping[str, t.Any]]], + t.Union[str, t.Mapping[str, t.Any]], + ] + ] = None, stats: t.Optional[t.Sequence[str]] = None, terminate_after: t.Optional[int] = None, timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, @@ -1500,7 +1512,7 @@ def delete_by_query( :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 sort: A sort object that specifies the order of deleted documents. :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. @@ -1590,8 +1602,6 @@ def delete_by_query( __query["search_type"] = search_type if slices is not None: __query["slices"] = slices - if sort is not None: - __query["sort"] = sort if stats is not None: __query["stats"] = stats if terminate_after is not None: @@ -1611,6 +1621,8 @@ def delete_by_query( __body["query"] = query if slice is not None: __body["slice"] = slice + if sort is not None: + __body["sort"] = sort __headers = {"accept": "application/json", "content-type": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", @@ -1627,11 +1639,11 @@ def delete_by_query_rethrottle( self, *, task_id: str, + requests_per_second: float, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, - requests_per_second: t.Optional[float] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html @@ -1649,9 +1661,13 @@ def delete_by_query_rethrottle( """ if task_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'task_id'") + if requests_per_second is None: + raise ValueError("Empty value passed for parameter 'requests_per_second'") __path_parts: t.Dict[str, str] = {"task_id": _quote(task_id)} __path = f'/_delete_by_query/{__path_parts["task_id"]}/_rethrottle' __query: t.Dict[str, t.Any] = {} + if requests_per_second is not None: + __query["requests_per_second"] = requests_per_second if error_trace is not None: __query["error_trace"] = error_trace if filter_path is not None: @@ -1660,8 +1676,6 @@ def delete_by_query_rethrottle( __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if requests_per_second is not None: - __query["requests_per_second"] = requests_per_second __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", @@ -1687,8 +1701,8 @@ def delete_script( """ .. raw:: html -

                      Delete a script or search template. - Deletes a stored script or search template.

                      +

                      Delete a script or search template.

                      +

                      Deletes a stored script or search template.

                      ``_ @@ -1999,8 +2013,8 @@ def explain( """ .. raw:: html -

                      Explain a document match result. - Get information about why a specific document matches, or doesn't match, a query. +

                      Explain a document match result.

                      +

                      Get information about why a specific document matches, or doesn't match, a query. It computes a score explanation for a query and a specific document.

                      @@ -2232,7 +2246,6 @@ def field_caps( @_rewrite_parameters( parameter_aliases={ "_source": "source", - "_source_exclude_vectors": "source_exclude_vectors", "_source_excludes": "source_excludes", "_source_includes": "source_includes", }, @@ -2252,7 +2265,6 @@ def get( refresh: t.Optional[bool] = None, routing: t.Optional[str] = None, source: t.Optional[t.Union[bool, t.Union[str, t.Sequence[str]]]] = None, - source_exclude_vectors: t.Optional[bool] = None, source_excludes: t.Optional[t.Union[str, t.Sequence[str]]] = None, source_includes: t.Optional[t.Union[str, t.Sequence[str]]] = None, stored_fields: t.Optional[t.Union[str, t.Sequence[str]]] = None, @@ -2326,7 +2338,6 @@ def get( :param routing: A custom value used to route operations to a specific shard. :param source: Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. - :param source_exclude_vectors: Whether vectors should be excluded from _source :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` @@ -2372,8 +2383,6 @@ def get( __query["routing"] = routing if source is not None: __query["_source"] = source - if source_exclude_vectors is not None: - __query["_source_exclude_vectors"] = source_exclude_vectors if source_excludes is not None: __query["_source_excludes"] = source_excludes if source_includes is not None: @@ -2408,8 +2417,8 @@ def get_script( """ .. raw:: html -

                      Get a script or search template. - Retrieves a stored script or search template.

                      +

                      Get a script or search template.

                      +

                      Retrieves a stored script or search template.

                      ``_ @@ -2645,8 +2654,8 @@ def health_report( """ .. raw:: html -

                      Get the cluster health. - Get a report with the health status of an Elasticsearch cluster. +

                      Get the cluster health.

                      +

                      Get a report with the health status of an Elasticsearch cluster. The report contains a list of indicators that compose Elasticsearch functionality.

                      Each indicator has a health status of: green, unknown, yellow or red. The indicator will provide an explanation and metadata describing the reason for its current health status.

                      @@ -2817,13 +2826,11 @@ def index( "id": "elkbee" } } - - In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1. - If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code). - - A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used. - Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order. +

                      In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1. + If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).

                      +

                      A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used. + Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.

                      ``_ @@ -2958,8 +2965,8 @@ def info( """ .. raw:: html -

                      Get cluster info. - Get basic build, version, and cluster information. +

                      Get cluster info.

                      +

                      Get basic build, version, and cluster information. ::: In Serverless, this API is retained for backward compatibility only. Some response fields, such as the version number, should be ignored.

                      @@ -3653,8 +3660,8 @@ def put_script( """ .. raw:: html -

                      Create or update a script or search template. - Creates or updates a stored script or search template.

                      +

                      Create or update a script or search template.

                      +

                      Creates or updates a stored script or search template.

                      ``_ @@ -3873,6 +3880,13 @@ def reindex( 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.

                      +

                      It's recommended to reindex on indices with a green status. Reindexing can fail when a node shuts down or crashes.

                      +
                        +
                      • When requested with wait_for_completion=true (default), the request fails if the node shuts down.
                      • +
                      • When requested with wait_for_completion=false, a task id is returned, for use with the task management APIs. The task may disappear or fail if the node shuts down. + When retrying a failed reindex operation, it might be necessary to set conflicts=proceed or to first delete the partial destination index. + Additionally, dry runs, checking disk space, and fetching index recovery information can help address the root cause.
                      • +

                      Refer to the linked documentation for examples of how to reindex documents.

                      @@ -3981,11 +3995,11 @@ def reindex_rethrottle( self, *, task_id: str, + requests_per_second: float, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, - requests_per_second: t.Optional[float] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html @@ -4009,9 +4023,13 @@ def reindex_rethrottle( """ if task_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'task_id'") + if requests_per_second is None: + raise ValueError("Empty value passed for parameter 'requests_per_second'") __path_parts: t.Dict[str, str] = {"task_id": _quote(task_id)} __path = f'/_reindex/{__path_parts["task_id"]}/_rethrottle' __query: t.Dict[str, t.Any] = {} + if requests_per_second is not None: + __query["requests_per_second"] = requests_per_second if error_trace is not None: __query["error_trace"] = error_trace if filter_path is not None: @@ -4020,8 +4038,6 @@ def reindex_rethrottle( __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if requests_per_second is not None: - __query["requests_per_second"] = requests_per_second __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", @@ -4091,11 +4107,7 @@ 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 self.perform_request( # type: ignore[return-value] "POST", __path, @@ -4109,7 +4121,7 @@ def render_search_template( @_rewrite_parameters( body_fields=("context", "context_setup", "script"), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def scripts_painless_execute( self, *, @@ -4178,11 +4190,7 @@ 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 self.perform_request( # type: ignore[return-value] "POST", __path, @@ -4307,7 +4315,6 @@ def scroll( ), parameter_aliases={ "_source": "source", - "_source_exclude_vectors": "source_exclude_vectors", "_source_excludes": "source_excludes", "_source_includes": "source_includes", "from": "from_", @@ -4391,7 +4398,6 @@ def search( ] ] = None, source: t.Optional[t.Union[bool, t.Mapping[str, t.Any]]] = None, - source_exclude_vectors: t.Optional[bool] = None, source_excludes: t.Optional[t.Union[str, t.Sequence[str]]] = None, source_includes: t.Optional[t.Union[str, t.Sequence[str]]] = None, stats: t.Optional[t.Sequence[str]] = None, @@ -4586,7 +4592,6 @@ def search( 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_exclude_vectors: Whether vectors should be excluded from _source :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` @@ -4711,8 +4716,6 @@ def search( __query["scroll"] = scroll if search_type is not None: __query["search_type"] = search_type - if source_exclude_vectors is not None: - __query["_source_exclude_vectors"] = source_exclude_vectors if source_excludes is not None: __query["_source_excludes"] = source_excludes if source_includes is not None: @@ -5139,11 +5142,19 @@ def search_mvt( ``_ - :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 index: A list of indices, data streams, or aliases to search. It supports + wildcards (`*`). To search all data streams and indices, omit this parameter + or use `*` or `_all`. To search a remote cluster, use the `:` + syntax. + :param field: A field that contains the geospatial data to return. It must be + a `geo_point` or `geo_shape` field. The field must have doc values enabled. + It cannot be a nested field. NOTE: Vector tiles do not natively support geometry + collections. For `geometrycollection` values in a `geo_shape` field, the + API returns a hits layer feature for each element of the collection. This + behavior may change in a future release. + :param zoom: The zoom level of the vector tile to search. It accepts `0` to `29`. + :param x: The X coordinate for the vector tile to search. + :param y: The Y coordinate for the vector tile to search. :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` @@ -5618,11 +5629,7 @@ 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 self.perform_request( # type: ignore[return-value] "POST", __path, @@ -5657,7 +5664,7 @@ 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, @@ -6057,8 +6064,8 @@ def update_by_query( """ .. raw:: html -

                      Update documents. - Updates documents that match the specified query. +

                      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:

                        @@ -6337,11 +6344,11 @@ def update_by_query_rethrottle( self, *, task_id: str, + requests_per_second: float, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, - requests_per_second: t.Optional[float] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html @@ -6359,9 +6366,13 @@ def update_by_query_rethrottle( """ if task_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'task_id'") + if requests_per_second is None: + raise ValueError("Empty value passed for parameter 'requests_per_second'") __path_parts: t.Dict[str, str] = {"task_id": _quote(task_id)} __path = f'/_update_by_query/{__path_parts["task_id"]}/_rethrottle' __query: t.Dict[str, t.Any] = {} + if requests_per_second is not None: + __query["requests_per_second"] = requests_per_second if error_trace is not None: __query["error_trace"] = error_trace if filter_path is not None: @@ -6370,8 +6381,6 @@ def update_by_query_rethrottle( __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if requests_per_second is not None: - __query["requests_per_second"] = requests_per_second __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", diff --git a/elasticsearch/_sync/client/async_search.py b/elasticsearch/_sync/client/async_search.py index 3042ae07a..0d2980ec8 100644 --- a/elasticsearch/_sync/client/async_search.py +++ b/elasticsearch/_sync/client/async_search.py @@ -357,7 +357,7 @@ def submit( :param allow_partial_search_results: Indicate if an error should be returned if there is a partial search failure or timeout :param analyze_wildcard: Specify whether wildcard and prefix queries should be - analyzed (default: false) + analyzed :param analyzer: The analyzer to use for the query string :param batched_reduce_size: Affects how often partial results become available, which happens whenever shard results are reduced. A partial reduction is @@ -373,7 +373,7 @@ def submit( values for field names matching these patterns in the hits.fields property of the response. :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. + that are open, closed or both :param explain: If true, returns detailed information about score computation as part of a hit. :param ext: Configuration of search extensions defined by Elasticsearch plugins. @@ -406,7 +406,7 @@ def submit( you cannot specify an in the request path. :param post_filter: :param preference: Specify the node or shard the operation should be performed - on (default: random) + on :param profile: :param q: Query in the Lucene query string syntax :param query: Defines the search definition using the Query DSL. diff --git a/elasticsearch/_sync/client/autoscaling.py b/elasticsearch/_sync/client/autoscaling.py index 98fe5d109..f9b155340 100644 --- a/elasticsearch/_sync/client/autoscaling.py +++ b/elasticsearch/_sync/client/autoscaling.py @@ -20,7 +20,11 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + _quote, + _rewrite_parameters, +) class AutoscalingClient(NamespacedClient): @@ -46,7 +50,7 @@ def delete_autoscaling_policy( ``_ - :param name: the name of the autoscaling policy + :param name: 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. @@ -153,7 +157,7 @@ def get_autoscaling_policy( ``_ - :param name: the name of the autoscaling policy + :param name: 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. @@ -208,7 +212,7 @@ def put_autoscaling_policy( ``_ - :param name: the name of the autoscaling policy + :param name: 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 diff --git a/elasticsearch/_sync/client/cat.py b/elasticsearch/_sync/client/cat.py index b1ab46d99..0bf20a8af 100644 --- a/elasticsearch/_sync/client/cat.py +++ b/elasticsearch/_sync/client/cat.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -36,6 +36,9 @@ 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[ @@ -47,12 +50,42 @@ 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, 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]: """ @@ -68,13 +101,22 @@ def aliases( :param name: A comma-separated list of aliases to retrieve. Supports wildcards (`*`). To retrieve all aliases, 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 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 master_timeout: The period to wait for a connection to the master node. @@ -84,6 +126,12 @@ def aliases( :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] @@ -94,6 +142,8 @@ 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: @@ -114,6 +164,8 @@ def aliases( __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"} @@ -137,13 +189,57 @@ 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]: """ @@ -158,10 +254,18 @@ def allocation( :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 @@ -172,6 +276,12 @@ 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] @@ -204,6 +314,8 @@ 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"} @@ -221,16 +333,51 @@ 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]: """ @@ -247,9 +394,18 @@ def component_templates( :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 @@ -260,6 +416,12 @@ def component_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] @@ -270,6 +432,8 @@ 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: @@ -290,6 +454,8 @@ 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"} @@ -307,14 +473,25 @@ 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, 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]: """ @@ -332,14 +509,29 @@ def count( :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 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] @@ -350,6 +542,8 @@ 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: @@ -366,6 +560,8 @@ def count( __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"} @@ -389,11 +585,21 @@ 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, 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]: """ @@ -409,15 +615,29 @@ def fielddata( :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 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] @@ -446,6 +666,8 @@ def fielddata( __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"} @@ -462,10 +684,58 @@ def fielddata( 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, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal[ + "active_shards_percent", + "cluster", + "epoch", + "init", + "max_task_wait_time", + "node.data", + "node.total", + "pending_tasks", + "pri", + "relo", + "shards", + "status", + "timestamp", + "unassign", + "unassign.pri", + ], + ] + ], + t.Union[ + str, + t.Literal[ + "active_shards_percent", + "cluster", + "epoch", + "init", + "max_task_wait_time", + "node.data", + "node.total", + "pending_tasks", + "pri", + "relo", + "shards", + "status", + "timestamp", + "unassign", + "unassign.pri", + ], + ], + ] + ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, @@ -493,21 +763,37 @@ def health( ``_ + :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 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: @@ -578,12 +864,321 @@ def indices( t.Sequence[ t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]] ], - t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]], + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]], + ] + ] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + format: t.Optional[str] = None, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal[ + "bulk.avg_size_in_bytes", + "bulk.avg_time", + "bulk.total_operations", + "bulk.total_size_in_bytes", + "bulk.total_time", + "completion.size", + "creation.date", + "creation.date.string", + "dataset.size", + "dense_vector.value_count", + "docs.count", + "docs.deleted", + "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", + "health", + "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", + "memory.total", + "merges.current", + "merges.current_docs", + "merges.current_size", + "merges.total", + "merges.total_docs", + "merges.total_size", + "merges.total_time", + "pri", + "pri.bulk.avg_size_in_bytes", + "pri.bulk.avg_time", + "pri.bulk.total_operations", + "pri.bulk.total_size_in_bytes", + "pri.bulk.total_time", + "pri.completion.size", + "pri.dense_vector.value_count", + "pri.fielddata.evictions", + "pri.fielddata.memory_size", + "pri.flush.total", + "pri.flush.total_time", + "pri.get.current", + "pri.get.exists_time", + "pri.get.exists_total", + "pri.get.missing_time", + "pri.get.missing_total", + "pri.get.time", + "pri.get.total", + "pri.indexing.delete_current", + "pri.indexing.delete_time", + "pri.indexing.delete_total", + "pri.indexing.index_current", + "pri.indexing.index_failed", + "pri.indexing.index_failed_due_to_version_conflict", + "pri.indexing.index_time", + "pri.indexing.index_total", + "pri.memory.total", + "pri.merges.current", + "pri.merges.current_docs", + "pri.merges.current_size", + "pri.merges.total", + "pri.merges.total_docs", + "pri.merges.total_size", + "pri.merges.total_time", + "pri.query_cache.evictions", + "pri.query_cache.memory_size", + "pri.refresh.external_time", + "pri.refresh.external_total", + "pri.refresh.listeners", + "pri.refresh.time", + "pri.refresh.total", + "pri.request_cache.evictions", + "pri.request_cache.hit_count", + "pri.request_cache.memory_size", + "pri.request_cache.miss_count", + "pri.search.fetch_current", + "pri.search.fetch_time", + "pri.search.fetch_total", + "pri.search.open_contexts", + "pri.search.query_current", + "pri.search.query_time", + "pri.search.query_total", + "pri.search.scroll_current", + "pri.search.scroll_time", + "pri.search.scroll_total", + "pri.segments.count", + "pri.segments.fixed_bitset_memory", + "pri.segments.index_writer_memory", + "pri.segments.memory", + "pri.segments.version_map_memory", + "pri.sparse_vector.value_count", + "pri.store.size", + "pri.suggest.current", + "pri.suggest.time", + "pri.suggest.total", + "pri.warmer.current", + "pri.warmer.total", + "pri.warmer.total_time", + "query_cache.evictions", + "query_cache.memory_size", + "refresh.external_time", + "refresh.external_total", + "refresh.listeners", + "refresh.time", + "refresh.total", + "rep", + "request_cache.evictions", + "request_cache.hit_count", + "request_cache.memory_size", + "request_cache.miss_count", + "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", + "sparse_vector.value_count", + "status", + "store.size", + "suggest.current", + "suggest.time", + "suggest.total", + "uuid", + "warmer.current", + "warmer.total", + "warmer.total_time", + ], + ] + ], + t.Union[ + str, + t.Literal[ + "bulk.avg_size_in_bytes", + "bulk.avg_time", + "bulk.total_operations", + "bulk.total_size_in_bytes", + "bulk.total_time", + "completion.size", + "creation.date", + "creation.date.string", + "dataset.size", + "dense_vector.value_count", + "docs.count", + "docs.deleted", + "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", + "health", + "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", + "memory.total", + "merges.current", + "merges.current_docs", + "merges.current_size", + "merges.total", + "merges.total_docs", + "merges.total_size", + "merges.total_time", + "pri", + "pri.bulk.avg_size_in_bytes", + "pri.bulk.avg_time", + "pri.bulk.total_operations", + "pri.bulk.total_size_in_bytes", + "pri.bulk.total_time", + "pri.completion.size", + "pri.dense_vector.value_count", + "pri.fielddata.evictions", + "pri.fielddata.memory_size", + "pri.flush.total", + "pri.flush.total_time", + "pri.get.current", + "pri.get.exists_time", + "pri.get.exists_total", + "pri.get.missing_time", + "pri.get.missing_total", + "pri.get.time", + "pri.get.total", + "pri.indexing.delete_current", + "pri.indexing.delete_time", + "pri.indexing.delete_total", + "pri.indexing.index_current", + "pri.indexing.index_failed", + "pri.indexing.index_failed_due_to_version_conflict", + "pri.indexing.index_time", + "pri.indexing.index_total", + "pri.memory.total", + "pri.merges.current", + "pri.merges.current_docs", + "pri.merges.current_size", + "pri.merges.total", + "pri.merges.total_docs", + "pri.merges.total_size", + "pri.merges.total_time", + "pri.query_cache.evictions", + "pri.query_cache.memory_size", + "pri.refresh.external_time", + "pri.refresh.external_total", + "pri.refresh.listeners", + "pri.refresh.time", + "pri.refresh.total", + "pri.request_cache.evictions", + "pri.request_cache.hit_count", + "pri.request_cache.memory_size", + "pri.request_cache.miss_count", + "pri.search.fetch_current", + "pri.search.fetch_time", + "pri.search.fetch_total", + "pri.search.open_contexts", + "pri.search.query_current", + "pri.search.query_time", + "pri.search.query_total", + "pri.search.scroll_current", + "pri.search.scroll_time", + "pri.search.scroll_total", + "pri.segments.count", + "pri.segments.fixed_bitset_memory", + "pri.segments.index_writer_memory", + "pri.segments.memory", + "pri.segments.version_map_memory", + "pri.sparse_vector.value_count", + "pri.store.size", + "pri.suggest.current", + "pri.suggest.time", + "pri.suggest.total", + "pri.warmer.current", + "pri.warmer.total", + "pri.warmer.total_time", + "query_cache.evictions", + "query_cache.memory_size", + "refresh.external_time", + "refresh.external_total", + "refresh.listeners", + "refresh.time", + "refresh.total", + "rep", + "request_cache.evictions", + "request_cache.hit_count", + "request_cache.memory_size", + "request_cache.miss_count", + "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", + "sparse_vector.value_count", + "status", + "store.size", + "suggest.current", + "suggest.time", + "suggest.total", + "uuid", + "warmer.current", + "warmer.total", + "warmer.total_time", + ], + ], ] ] = 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, health: t.Optional[ t.Union[str, t.Literal["green", "red", "unavailable", "unknown", "yellow"]] ] = None, @@ -623,11 +1218,19 @@ def indices( :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`. - :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 health: The health status used to limit returned indices. By default, the response includes indices of any health status. :param help: When set to `true` will output available columns. This option can't @@ -639,7 +1242,12 @@ def indices( :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] @@ -696,16 +1304,27 @@ def indices( 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, - h: t.Optional[t.Union[str, t.Sequence[str]]] = None, + h: t.Optional[ + t.Union[ + t.Sequence[t.Union[str, t.Literal["host", "id", "ip", "node"]]], + t.Union[str, t.Literal["host", "id", "ip", "node"]], + ] + ] = 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]: """ @@ -718,9 +1337,18 @@ def master( ``_ + :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 @@ -731,11 +1359,19 @@ 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: @@ -756,6 +1392,8 @@ 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"} @@ -898,8 +1536,15 @@ def ml_data_frame_analytics( :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. @@ -907,7 +1552,12 @@ def ml_data_frame_analytics( be combined with any other query string option. :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] @@ -958,6 +1608,9 @@ 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, @@ -1073,6 +1726,14 @@ 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. @@ -1080,7 +1741,12 @@ def ml_datafeeds( be combined with any other query string option. :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] @@ -1093,6 +1759,8 @@ 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: @@ -1438,7 +2106,14 @@ 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. @@ -1446,7 +2121,12 @@ def ml_jobs( be combined with any other query string option. :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] @@ -1623,7 +2303,14 @@ 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. @@ -1633,7 +2320,12 @@ def ml_trained_models( :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: 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] @@ -1686,16 +2378,39 @@ def ml_trained_models( 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, - h: t.Optional[t.Union[str, t.Sequence[str]]] = None, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal[ + "attr", "host", "id", "ip", "node", "pid", "port", "value" + ], + ] + ], + t.Union[ + str, + t.Literal[ + "attr", "host", "id", "ip", "node", "pid", "port", "value" + ], + ], + ] + ] = 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]: """ @@ -1708,9 +2423,18 @@ def nodeattrs( ``_ + :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 @@ -1721,11 +2445,19 @@ 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: @@ -1746,6 +2478,8 @@ 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"} @@ -1984,7 +2718,14 @@ def nodes( ``_ - :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 @@ -1999,7 +2740,12 @@ def nodes( :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: 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] = {} @@ -2047,10 +2793,25 @@ def nodes( 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, - h: t.Optional[t.Union[str, t.Sequence[str]]] = None, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal["insertOrder", "priority", "source", "timeInQueue"], + ] + ], + t.Union[ + str, t.Literal["insertOrder", "priority", "source", "timeInQueue"] + ], + ] + ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, local: t.Optional[bool] = None, @@ -2072,9 +2833,18 @@ def pending_tasks( ``_ + :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 @@ -2085,12 +2855,19 @@ 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: 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] = {} __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: @@ -2129,10 +2906,25 @@ def pending_tasks( 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, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal["component", "description", "id", "name", "version"], + ] + ], + t.Union[ + str, t.Literal["component", "description", "id", "name", "version"] + ], + ] + ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, include_bootstrap: t.Optional[bool] = None, @@ -2140,6 +2932,9 @@ def plugins( 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]: """ @@ -2152,9 +2947,18 @@ def plugins( ``_ + :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 include_bootstrap: Include bootstrap plugins in the response @@ -2166,11 +2970,19 @@ 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: @@ -2193,6 +3005,8 @@ 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"} @@ -2311,7 +3125,14 @@ def recovery( 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 @@ -2323,7 +3144,12 @@ def recovery( :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: 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] @@ -2374,6 +3200,9 @@ def recovery( 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, @@ -2384,6 +3213,9 @@ 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]: """ @@ -2396,6 +3228,14 @@ def repositories( ``_ + :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. @@ -2409,11 +3249,19 @@ 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: @@ -2434,6 +3282,8 @@ 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"} @@ -2451,10 +3301,20 @@ def segments( self, *, index: t.Optional[t.Union[str, t.Sequence[str]]] = None, + allow_closed: t.Optional[bool] = None, + allow_no_indices: 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, + expand_wildcards: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]] + ], + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]], + ] + ] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, format: t.Optional[str] = None, h: t.Optional[ @@ -2505,10 +3365,15 @@ def segments( ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, + ignore_throttled: 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]: """ @@ -2525,13 +3390,36 @@ def segments( :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 allow_closed: If true, allow closed indices to be returned in the response + otherwise if false, keep the legacy behaviour of throwing an exception if + index pattern matches closed indices + :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 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: Type of index that wildcard expressions can match. If + the request can target data streams, this argument determines whether wildcard + expressions match hidden data streams. 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: 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_throttled: If true, concrete, expanded or aliased indices are ignored + when frozen. + :param ignore_unavailable: If true, missing or closed indices are not included + 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 @@ -2540,6 +3428,12 @@ def segments( :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] @@ -2550,10 +3444,16 @@ def segments( __path_parts = {} __path = "/_cat/segments" __query: t.Dict[str, t.Any] = {} + if allow_closed is not None: + __query["allow_closed"] = allow_closed + if allow_no_indices is not None: + __query["allow_no_indices"] = allow_no_indices 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: + __query["expand_wildcards"] = expand_wildcards if filter_path is not None: __query["filter_path"] = filter_path if format is not None: @@ -2564,6 +3464,10 @@ def segments( __query["help"] = help if human is not None: __query["human"] = human + if ignore_throttled is not None: + __query["ignore_throttled"] = ignore_throttled + 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: @@ -2572,6 +3476,8 @@ 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"} @@ -2775,7 +3681,14 @@ def shards( :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. @@ -2785,7 +3698,12 @@ def shards( :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: 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] @@ -2835,6 +3753,9 @@ 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, @@ -2905,6 +3826,14 @@ def snapshots( :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: A comma-separated list of columns names to display. It supports simple @@ -2917,7 +3846,12 @@ def snapshots( :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: 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] @@ -2928,6 +3862,8 @@ 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: @@ -2963,16 +3899,64 @@ def snapshots( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) 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, 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[ + "action", + "id", + "ip", + "node", + "node_id", + "parent_task_id", + "port", + "running_time", + "running_time_ns", + "start_time", + "task_id", + "timestamp", + "type", + "version", + "x_opaque_id", + ], + ] + ], + t.Union[ + str, + t.Literal[ + "action", + "id", + "ip", + "node", + "node_id", + "parent_task_id", + "port", + "running_time", + "running_time_ns", + "start_time", + "task_id", + "timestamp", + "type", + "version", + "x_opaque_id", + ], + ], + ] + ] = None, help: t.Optional[bool] = None, human: t.Optional[bool] = None, nodes: t.Optional[t.Sequence[str]] = None, @@ -2997,11 +3981,20 @@ def tasks( ``_ :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 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 nodes: Unique node identifiers, which are used to limit the response. @@ -3010,7 +4003,12 @@ def 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: 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 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. @@ -3022,6 +4020,8 @@ def 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: @@ -3067,16 +4067,39 @@ 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, - h: t.Optional[t.Union[str, t.Sequence[str]]] = None, + h: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[ + str, + t.Literal[ + "composed_of", "index_patterns", "name", "order", "version" + ], + ] + ], + t.Union[ + str, + t.Literal[ + "composed_of", "index_patterns", "name", "order", "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]: """ @@ -3092,9 +4115,18 @@ def templates( :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. + :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 @@ -3105,6 +4137,12 @@ 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] @@ -3115,6 +4153,8 @@ 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: @@ -3135,6 +4175,8 @@ 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"} @@ -3152,6 +4194,9 @@ 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, @@ -3235,6 +4280,14 @@ def thread_pool( :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. @@ -3248,7 +4301,12 @@ def thread_pool( :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: 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] @@ -3259,6 +4317,8 @@ 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: @@ -3301,6 +4361,9 @@ 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, @@ -3500,6 +4563,14 @@ 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. @@ -3509,7 +4580,12 @@ def transforms( :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] @@ -3522,6 +4598,8 @@ 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: diff --git a/elasticsearch/_sync/client/ccr.py b/elasticsearch/_sync/client/ccr.py index 0eec10516..37699bacc 100644 --- a/elasticsearch/_sync/client/ccr.py +++ b/elasticsearch/_sync/client/ccr.py @@ -125,8 +125,8 @@ def follow( """ .. raw:: html -

                        Create a follower. - Create a cross-cluster replication follower index that follows a specific leader index. +

                        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.

                        @@ -368,8 +368,8 @@ def forget_follower( """ .. raw:: html -

                        Forget a follower. - Remove the cross-cluster replication follower retention leases from the leader.

                        +

                        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. @@ -382,7 +382,7 @@ def forget_follower( ``_ - :param index: the name of the leader index for which specified follower retention + :param index: Name of the leader index for which specified follower retention leases should be removed :param follower_cluster: :param follower_index: @@ -640,8 +640,8 @@ def put_auto_follow_pattern( """ .. raw:: html -

                        Create or update auto-follow patterns. - Create a collection of cross-cluster replication auto-follow patterns for a remote cluster. +

                        Create or update auto-follow patterns.

                        +

                        Create a collection of cross-cluster replication auto-follow patterns for a remote cluster. Newly created indices on the remote cluster that match any of the patterns are automatically configured as follower indices. Indices on the remote cluster that were created before the auto-follow pattern was created will not be auto-followed even if they match the pattern.

                        This API can also be used to update auto-follow patterns. @@ -853,8 +853,8 @@ def resume_follow( """ .. raw:: html -

                        Resume a follower. - Resume a cross-cluster replication follower index that was paused. +

                        Resume a follower.

                        +

                        Resume a cross-cluster replication follower index that was paused. The follower index could have been paused with the pause follower API. Alternatively it could be paused due to replication that cannot be retried due to failures during following tasks. When this API returns, the follower index will resume fetching operations from the leader index.

                        @@ -862,7 +862,7 @@ def resume_follow( ``_ - :param index: The name of the follow index to resume following. + :param index: Name of the follow index to resume following :param master_timeout: Period to wait for a connection to the master node. :param max_outstanding_read_requests: :param max_outstanding_write_requests: diff --git a/elasticsearch/_sync/client/cluster.py b/elasticsearch/_sync/client/cluster.py index a56892d54..68499f3ee 100644 --- a/elasticsearch/_sync/client/cluster.py +++ b/elasticsearch/_sync/client/cluster.py @@ -47,9 +47,8 @@ def allocation_explain( """ .. raw:: html -

                        Explain the shard allocations. - Get explanations for shard allocations in the cluster. - This API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time. +

                        Explain the shard allocations.

                        +

                        Get explanations for shard allocations in the cluster. For unassigned shards, it provides an explanation for why the shard is unassigned. For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise. @@ -58,16 +57,17 @@ def allocation_explain( ``_ - :param current_node: Explain a shard only if it is currently located on the specified - node name or node ID. + :param current_node: Specifies the node ID or the name of the node to only explain + a shard that is currently located on the specified node. :param include_disk_info: If true, returns information about disk usage and shard sizes. :param include_yes_decisions: If true, returns YES decisions in explanation. - :param index: The name of the index that you would like an explanation for. + :param index: Specifies the name of the index that you would like an explanation + for. :param master_timeout: Period to wait for a connection to the master node. - :param primary: If true, returns an explanation for the primary shard for the - specified shard ID. - :param shard: An identifier for the shard that you would like an explanation + :param primary: If true, returns explanation for the primary shard for the given + shard ID. + :param shard: Specifies the ID of the shard that you would like an explanation for. """ __path_parts: t.Dict[str, str] = {} @@ -127,8 +127,8 @@ def delete_component_template( """ .. raw:: html -

                        Delete component templates. - Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

                        +

                        Delete component templates.

                        +

                        Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

                        ``_ @@ -182,8 +182,8 @@ def delete_voting_config_exclusions( """ .. raw:: html -

                        Clear cluster voting config exclusions. - Remove master-eligible nodes from the voting configuration exclusion list.

                        +

                        Clear cluster voting config exclusions.

                        +

                        Remove master-eligible nodes from the voting configuration exclusion list.

                        ``_ @@ -236,8 +236,8 @@ def exists_component_template( """ .. raw:: html -

                        Check component templates. - Returns information about whether a particular component template exists.

                        +

                        Check component templates.

                        +

                        Returns information about whether a particular component template exists.

                        ``_ @@ -296,8 +296,8 @@ def get_component_template( """ .. raw:: html -

                        Get component templates. - Get information about component templates.

                        +

                        Get component templates.

                        +

                        Get information about component templates.

                        ``_ @@ -306,7 +306,7 @@ def get_component_template( request. Wildcard (`*`) expressions are supported. :param flat_settings: If `true`, returns settings in flat format. :param include_defaults: Return all default configurations for the component - template (default: false) + template :param local: If `true`, the request retrieves information from the local node only. If `false`, information is retrieved from the master node. :param master_timeout: Period to wait for a connection to the master node. If @@ -374,8 +374,13 @@ def get_settings( ``_ :param flat_settings: If `true`, returns settings in flat format. - :param include_defaults: If `true`, returns default cluster settings from the - local node. + :param include_defaults: If `true`, also returns default values for all other + cluster settings, reflecting the values in the `elasticsearch.yml` file of + one of the nodes in the cluster. If the nodes in your cluster do not all + have the same values in their `elasticsearch.yml` config files then the values + returned by this API may vary from invocation to invocation and may not reflect + the values that Elasticsearch uses in all situations. Use the `GET _nodes/settings` + API to fetch the settings for each individual node in your cluster. :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. @@ -567,8 +572,8 @@ def info( """ .. raw:: html -

                        Get cluster info. - Returns basic information about the cluster.

                        +

                        Get cluster info.

                        +

                        Returns basic information about the cluster.

                        ``_ @@ -613,8 +618,8 @@ def pending_tasks( """ .. raw:: html -

                        Get the pending cluster tasks. - Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.

                        +

                        Get the pending cluster tasks.

                        +

                        Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.

                        NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.

                        @@ -669,8 +674,8 @@ def post_voting_config_exclusions( """ .. raw:: html -

                        Update voting configuration exclusions. - Update the cluster voting config exclusions by node IDs or node names. +

                        Update voting configuration exclusions.

                        +

                        Update the cluster voting config exclusions by node IDs or node names. By default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks. If you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, use this API to remove departing nodes from the voting configuration manually. The API adds an entry for each specified node to the cluster’s voting configuration exclusions list. @@ -752,8 +757,8 @@ def put_component_template( """ .. raw:: html -

                        Create or update a component template. - Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

                        +

                        Create or update a component template.

                        +

                        Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

                        An index template can be composed of multiple component templates. To use a component template, specify it in an index template’s composed_of list. Component templates are only applied to new data streams and indices as part of a matching index template.

                        @@ -878,10 +883,10 @@ def put_settings( ``_ - :param flat_settings: Return settings in flat format (default: false) - :param master_timeout: Explicit operation timeout for connection to master node + :param flat_settings: Return settings in flat format + :param master_timeout: The period to wait for a connection to the master node. :param persistent: The settings that persist after the cluster restarts. - :param timeout: Explicit operation timeout + :param timeout: The period to wait for a response. :param transient: The settings that do not persist after the cluster restarts. """ __path_parts: t.Dict[str, str] = {} @@ -987,8 +992,8 @@ def reroute( """ .. raw:: html -

                        Reroute the cluster. - Manually change the allocation of individual shards in the cluster. +

                        Reroute the cluster.

                        +

                        Manually change the allocation of individual shards in the cluster. For example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node.

                        It is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as cluster.routing.rebalance.enable) in order to remain in a balanced state. For example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.

                        @@ -1088,8 +1093,8 @@ def state( """ .. raw:: html -

                        Get the cluster state. - Get comprehensive information about the state of the cluster.

                        +

                        Get the cluster state.

                        +

                        Get comprehensive information about the state of the cluster.

                        The cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.

                        The elected master node ensures that every node in the cluster has a copy of the same cluster state. This API lets you retrieve a representation of this internal state for debugging or diagnostic purposes. @@ -1106,19 +1111,19 @@ def state( ``_ - :param metric: Limit the information returned to the specified metrics + :param metric: Limit the information returned to the specified metrics. :param index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices :param allow_no_indices: Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified) :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. - :param flat_settings: Return settings in flat format (default: false) + that are open, closed or both + :param flat_settings: Return settings in flat format :param ignore_unavailable: Whether specified concrete indices should be ignored when unavailable (missing or closed) :param local: Return local information, do not retrieve the state from master - node (default: false) + node :param master_timeout: Timeout for waiting for new cluster state in case it is blocked :param wait_for_metadata_version: Wait for the metadata version to be equal or @@ -1189,8 +1194,8 @@ def stats( """ .. raw:: html -

                        Get cluster statistics. - Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).

                        +

                        Get cluster statistics.

                        +

                        Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).

                        ``_ diff --git a/elasticsearch/_sync/client/connector.py b/elasticsearch/_sync/client/connector.py index 58771108a..ac8e77ae1 100644 --- a/elasticsearch/_sync/client/connector.py +++ b/elasticsearch/_sync/client/connector.py @@ -23,16 +23,17 @@ from .utils import ( SKIP_IN_PATH, Stability, + Visibility, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class ConnectorClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def check_in( self, *, @@ -77,7 +78,7 @@ def check_in( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def delete( self, *, @@ -103,7 +104,7 @@ def delete( :param connector_id: The unique identifier of the connector to be deleted :param delete_sync_jobs: A flag indicating if associated sync jobs should be - also removed. Defaults to false. + also removed. :param hard: A flag indicating if the connector should be hard deleted. """ if connector_id in SKIP_IN_PATH: @@ -134,7 +135,7 @@ def delete( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def get( self, *, @@ -199,7 +200,7 @@ def get( "sync_cursor", ), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL, Visibility.PRIVATE) def last_sync( self, *, @@ -333,7 +334,7 @@ def last_sync( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def list( self, *, @@ -360,7 +361,7 @@ def list( :param connector_name: A comma-separated list of connector names to fetch connector documents for - :param from_: Starting offset (default: 0) + :param from_: Starting offset :param include_deleted: A flag to indicate if the desired connector should be fetched, even if it was soft-deleted. :param index_name: A comma-separated list of connector index names to fetch connector @@ -416,7 +417,7 @@ def list( "service_type", ), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def post( self, *, @@ -500,7 +501,7 @@ def post( "service_type", ), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def put( self, *, @@ -580,7 +581,7 @@ def put( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def sync_job_cancel( self, *, @@ -630,7 +631,7 @@ def sync_job_cancel( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def sync_job_check_in( self, *, @@ -643,8 +644,8 @@ def sync_job_check_in( """ .. raw:: html -

                        Check in a connector sync job. - Check in a connector sync job and set the last_seen field to the current time before updating it in the internal index.

                        +

                        Check in a connector sync job.

                        +

                        Check in a connector sync job and set the last_seen field to the current time before updating it in the internal index.

                        To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

                        @@ -684,7 +685,7 @@ def sync_job_check_in( @_rewrite_parameters( body_fields=("worker_hostname", "sync_cursor"), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def sync_job_claim( self, *, @@ -700,8 +701,8 @@ def sync_job_claim( """ .. raw:: html -

                        Claim a connector sync job. - This action updates the job status to in_progress and sets the last_seen and started_at timestamps to the current time. +

                        Claim a connector sync job.

                        +

                        This action updates the job status to in_progress and sets the last_seen and started_at timestamps to the current time. Additionally, it can set the sync_cursor property for the sync job.

                        This API is not intended for direct connector management by users. It supports the implementation of services that utilize the connector protocol to communicate with Elasticsearch.

                        @@ -753,7 +754,7 @@ def sync_job_claim( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def sync_job_delete( self, *, @@ -804,7 +805,7 @@ def sync_job_delete( @_rewrite_parameters( body_fields=("error",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def sync_job_error( self, *, @@ -819,8 +820,8 @@ def sync_job_error( """ .. raw:: html -

                        Set a connector sync job error. - Set the error field for a connector sync job and set its status to error.

                        +

                        Set a connector sync job error.

                        +

                        Set the error field for a connector sync job and set its status to error.

                        To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

                        @@ -863,7 +864,7 @@ def sync_job_error( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def sync_job_get( self, *, @@ -911,7 +912,7 @@ def sync_job_get( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def sync_job_list( self, *, @@ -955,7 +956,7 @@ def sync_job_list( ``_ :param connector_id: A connector id to fetch connector sync jobs for - :param from_: Starting offset (default: 0) + :param from_: Starting offset :param job_type: A comma-separated list of job types to fetch the sync jobs for :param size: Specifies a max number of results to get :param status: A sync job status to fetch connector sync jobs for @@ -994,7 +995,7 @@ def sync_job_list( @_rewrite_parameters( body_fields=("id", "job_type", "trigger_method"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def sync_job_post( self, *, @@ -1066,7 +1067,7 @@ def sync_job_post( "total_document_count", ), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def sync_job_update_stats( self, *, @@ -1086,8 +1087,8 @@ def sync_job_update_stats( """ .. raw:: html -

                        Set the connector sync job stats. - Stats include: deleted_document_count, indexed_document_count, indexed_document_volume, and total_document_count. +

                        Set the connector sync job stats.

                        +

                        Stats include: deleted_document_count, indexed_document_count, indexed_document_volume, and total_document_count. You can also update last_seen. This API is mainly used by the connector service for updating sync job information.

                        To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. @@ -1160,7 +1161,7 @@ def sync_job_update_stats( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def update_active_filtering( self, *, @@ -1207,7 +1208,7 @@ def update_active_filtering( @_rewrite_parameters( body_fields=("api_key_id", "api_key_secret_id"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def update_api_key_id( self, *, @@ -1269,7 +1270,7 @@ def update_api_key_id( @_rewrite_parameters( body_fields=("configuration", "values"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def update_configuration( self, *, @@ -1328,7 +1329,7 @@ def update_configuration( @_rewrite_parameters( body_fields=("error",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def update_error( self, *, @@ -1387,7 +1388,7 @@ def update_error( @_rewrite_parameters( body_fields=("features",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def update_features( self, *, @@ -1402,8 +1403,8 @@ def update_features( """ .. raw:: html -

                        Update the connector features. - Update the connector features in the connector document. +

                        Update the connector features.

                        +

                        Update the connector features in the connector document. This API can be used to control the following aspects of a connector:

                        • document-level security
                        • @@ -1455,7 +1456,7 @@ def update_features( @_rewrite_parameters( body_fields=("advanced_snippet", "filtering", "rules"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def update_filtering( self, *, @@ -1520,7 +1521,7 @@ def update_filtering( @_rewrite_parameters( body_fields=("validation",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def update_filtering_validation( self, *, @@ -1577,7 +1578,7 @@ def update_filtering_validation( @_rewrite_parameters( body_fields=("index_name",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def update_index_name( self, *, @@ -1634,7 +1635,7 @@ def update_index_name( @_rewrite_parameters( body_fields=("description", "name"), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def update_name( self, *, @@ -1692,7 +1693,7 @@ def update_name( @_rewrite_parameters( body_fields=("is_native",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def update_native( self, *, @@ -1748,7 +1749,7 @@ def update_native( @_rewrite_parameters( body_fields=("pipeline",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def update_pipeline( self, *, @@ -1805,7 +1806,7 @@ def update_pipeline( @_rewrite_parameters( body_fields=("scheduling",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def update_scheduling( self, *, @@ -1861,7 +1862,7 @@ def update_scheduling( @_rewrite_parameters( body_fields=("service_type",), ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def update_service_type( self, *, @@ -1917,7 +1918,7 @@ def update_service_type( @_rewrite_parameters( body_fields=("status",), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def update_status( self, *, diff --git a/elasticsearch/_sync/client/dangling_indices.py b/elasticsearch/_sync/client/dangling_indices.py index b40de169e..b547a0020 100644 --- a/elasticsearch/_sync/client/dangling_indices.py +++ b/elasticsearch/_sync/client/dangling_indices.py @@ -30,7 +30,7 @@ def delete_dangling_index( self, *, index_uuid: str, - accept_data_loss: bool, + accept_data_loss: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, @@ -41,8 +41,8 @@ def delete_dangling_index( """ .. raw:: html -

                          Delete a dangling index. - If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. +

                          Delete a dangling index.

                          +

                          If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. For example, this can happen if you delete more than cluster.indices.tombstones.size indices while an Elasticsearch node is offline.

                          @@ -52,13 +52,11 @@ def delete_dangling_index( API to find the UUID. :param accept_data_loss: This parameter must be set to true to acknowledge that it will no longer be possible to recove data from the dangling index. - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit operation timeout + :param master_timeout: The period to wait for a connection to the master node. + :param timeout: The period to wait for a response. """ if index_uuid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index_uuid'") - if accept_data_loss is None: - raise ValueError("Empty value passed for parameter 'accept_data_loss'") __path_parts: t.Dict[str, str] = {"index_uuid": _quote(index_uuid)} __path = f'/_dangling/{__path_parts["index_uuid"]}' __query: t.Dict[str, t.Any] = {} @@ -91,7 +89,7 @@ def import_dangling_index( self, *, index_uuid: str, - accept_data_loss: bool, + accept_data_loss: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, @@ -116,13 +114,11 @@ def import_dangling_index( from or determine which shard copies are fresh and which are stale, it cannot guarantee that the imported data represents the latest state of the index when it was last in the cluster. - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit operation timeout + :param master_timeout: The period to wait for a connection to the master node. + :param timeout: The period to wait for a response. """ if index_uuid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index_uuid'") - if accept_data_loss is None: - raise ValueError("Empty value passed for parameter 'accept_data_loss'") __path_parts: t.Dict[str, str] = {"index_uuid": _quote(index_uuid)} __path = f'/_dangling/{__path_parts["index_uuid"]}' __query: t.Dict[str, t.Any] = {} diff --git a/elasticsearch/_sync/client/enrich.py b/elasticsearch/_sync/client/enrich.py index a12372552..70374133e 100644 --- a/elasticsearch/_sync/client/enrich.py +++ b/elasticsearch/_sync/client/enrich.py @@ -39,8 +39,8 @@ def delete_policy( """ .. raw:: html -

                          Delete an enrich policy. - Deletes an existing enrich policy and its enrich index.

                          +

                          Delete an enrich policy.

                          +

                          Deletes an existing enrich policy and its enrich index.

                          ``_ @@ -88,8 +88,8 @@ def execute_policy( """ .. raw:: html -

                          Run an enrich policy. - Create the enrich index for an existing enrich policy.

                          +

                          Run an enrich policy.

                          +

                          Create the enrich index for an existing enrich policy.

                          ``_ @@ -140,8 +140,8 @@ def get_policy( """ .. raw:: html -

                          Get an enrich policy. - Returns information about an enrich policy.

                          +

                          Get an enrich policy.

                          +

                          Returns information about an enrich policy.

                          ``_ @@ -198,8 +198,8 @@ def put_policy( """ .. raw:: html -

                          Create an enrich policy. - Creates an enrich policy.

                          +

                          Create an enrich policy.

                          +

                          Creates an enrich policy.

                          ``_ @@ -259,8 +259,8 @@ def stats( """ .. raw:: html -

                          Get enrich stats. - Returns enrich coordinator statistics and information about enrich policies that are currently executing.

                          +

                          Get enrich stats.

                          +

                          Returns enrich coordinator statistics and information about enrich policies that are currently executing.

                          ``_ diff --git a/elasticsearch/_sync/client/eql.py b/elasticsearch/_sync/client/eql.py index 1fe0234dd..d46716198 100644 --- a/elasticsearch/_sync/client/eql.py +++ b/elasticsearch/_sync/client/eql.py @@ -38,8 +38,8 @@ def delete( """ .. raw:: html -

                          Delete an async EQL search. - Delete an async EQL search or a stored synchronous EQL search. +

                          Delete an async EQL search.

                          +

                          Delete an async EQL search or a stored synchronous EQL search. The API also deletes results for the search.

                          @@ -89,8 +89,8 @@ def get( """ .. raw:: html -

                          Get async EQL search results. - Get the current status and available results for an async EQL search or a stored synchronous EQL search.

                          +

                          Get async EQL search results.

                          +

                          Get the current status and available results for an async EQL search or a stored synchronous EQL search.

                          ``_ @@ -143,8 +143,8 @@ def get_status( """ .. raw:: html -

                          Get the async EQL status. - Get the current status for an async EQL search or a stored synchronous EQL search without returning results.

                          +

                          Get the async EQL status.

                          +

                          Get the current status for an async EQL search or a stored synchronous EQL search without returning results.

                          ``_ @@ -242,14 +242,14 @@ def search( """ .. raw:: html -

                          Get EQL search results. - Returns search results for an Event Query Language (EQL) query. +

                          Get EQL search results.

                          +

                          Returns search results for an Event Query Language (EQL) query. EQL assumes each document in a data stream or index corresponds to an event.

                          ``_ - :param index: The name of the index to scope the operation + :param index: Comma-separated list of index names to scope the operation :param query: EQL query you wish to run. :param allow_no_indices: Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices @@ -291,7 +291,7 @@ def search( Defaults to 10 :param tiebreaker_field: Field used to sort hits with the same timestamp in ascending order - :param timestamp_field: Field containing event timestamp. Default "@timestamp" + :param timestamp_field: Field containing event timestamp. :param wait_for_completion_timeout: """ if index in SKIP_IN_PATH: diff --git a/elasticsearch/_sync/client/esql.py b/elasticsearch/_sync/client/esql.py index 0744a81bd..1910149de 100644 --- a/elasticsearch/_sync/client/esql.py +++ b/elasticsearch/_sync/client/esql.py @@ -23,11 +23,14 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) +if t.TYPE_CHECKING: + from ...esql import ESQLBase + class EsqlClient(NamespacedClient): @@ -50,7 +53,7 @@ class EsqlClient(NamespacedClient): def async_query( self, *, - query: t.Optional[str] = None, + query: t.Optional[t.Union[str, "ESQLBase"]] = None, allow_partial_results: t.Optional[bool] = None, columnar: t.Optional[bool] = None, delimiter: t.Optional[str] = None, @@ -85,8 +88,8 @@ def async_query( """ .. raw:: html -

                          Run an async ES|QL query. - Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.

                          +

                          Run an async ES|QL query.

                          +

                          Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.

                          The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.

                          @@ -111,7 +114,12 @@ def async_query( which has the name of all the columns. :param filter: Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on. - :param format: A short version of the Accept header, for example `json` or `yaml`. + :param format: A short version of the Accept header, e.g. json, yaml. `csv`, + `tsv`, and `txt` formats will return results in a tabular format, excluding + other metadata fields from the response. For async requests, nothing will + be returned if the async query doesn't finish within the timeout. The query + ID and running status are available in the `X-Elasticsearch-Async-Id` and + `X-Elasticsearch-Async-Is-Running` HTTP headers of the response, respectively. :param include_ccs_metadata: When set to `true` and performing a cross-cluster query, the response will include an extra `_clusters` object with information about the clusters that participated in the search along with info such as @@ -165,7 +173,7 @@ def async_query( __query["pretty"] = pretty if not __body: if query is not None: - __body["query"] = query + __body["query"] = str(query) if columnar is not None: __body["columnar"] = columnar if filter is not None: @@ -210,8 +218,8 @@ def async_query_delete( """ .. raw:: html -

                          Delete an async ES|QL query. - If the query is still running, it is cancelled. +

                          Delete an async ES|QL query.

                          +

                          If the query is still running, it is cancelled. Otherwise, the stored results are deleted.

                          If the Elasticsearch security features are enabled, only the following users can use this API to delete a query:

                            @@ -276,8 +284,8 @@ def async_query_get( """ .. raw:: html -

                            Get async ES|QL query results. - Get the current status and available results or stored results for an ES|QL asynchronous query. +

                            Get async ES|QL query results.

                            +

                            Get the current status and available results or stored results for an ES|QL asynchronous query. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API.

                            @@ -388,7 +396,7 @@ def async_query_stop( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def get_query( self, *, @@ -401,10 +409,12 @@ def get_query( """ .. raw:: html -

                            Get a specific running ES|QL query information. - Returns an object extended information about a running ES|QL query.

                            +

                            Get a specific running ES|QL query information.

                            +

                            Returns an object extended information about a running ES|QL query.

                            + ``_ + :param id: The query ID """ if id in SKIP_IN_PATH: @@ -431,7 +441,7 @@ def get_query( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def list_queries( self, *, @@ -443,9 +453,11 @@ def list_queries( """ .. raw:: html -

                            Get running ES|QL queries information. - Returns an object containing IDs and other information about the running ES|QL queries.

                            +

                            Get running ES|QL queries information.

                            +

                            Returns an object containing IDs and other information about the running ES|QL queries.

                            + + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_query/queries" @@ -484,7 +496,7 @@ def list_queries( def query( self, *, - query: t.Optional[str] = None, + query: t.Optional[t.Union[str, "ESQLBase"]] = None, allow_partial_results: t.Optional[bool] = None, columnar: t.Optional[bool] = None, delimiter: t.Optional[str] = None, @@ -514,8 +526,8 @@ def query( """ .. raw:: html -

                            Run an ES|QL query. - Get search results for an ES|QL (Elasticsearch query language) query.

                            +

                            Run an ES|QL query.

                            +

                            Get search results for an ES|QL (Elasticsearch query language) query.

                            ``_ @@ -539,7 +551,9 @@ def query( `all_columns` which has the name of all columns. :param filter: Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on. - :param format: A short version of the Accept header, e.g. json, yaml. + :param format: A short version of the Accept header, e.g. json, yaml. `csv`, + `tsv`, and `txt` formats will return results in a tabular format, excluding + other metadata fields from the response. :param include_ccs_metadata: When set to `true` and performing a cross-cluster query, the response will include an extra `_clusters` object with information about the clusters that participated in the search along with info such as @@ -579,7 +593,7 @@ def query( __query["pretty"] = pretty if not __body: if query is not None: - __body["query"] = query + __body["query"] = str(query) if columnar is not None: __body["columnar"] = columnar if filter is not None: diff --git a/elasticsearch/_sync/client/features.py b/elasticsearch/_sync/client/features.py index 85432324e..c13eb401f 100644 --- a/elasticsearch/_sync/client/features.py +++ b/elasticsearch/_sync/client/features.py @@ -20,7 +20,7 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import Stability, _rewrite_parameters, _stability_warning +from .utils import Stability, _availability_warning, _rewrite_parameters class FeaturesClient(NamespacedClient): @@ -38,8 +38,8 @@ def get_features( """ .. raw:: html -

                            Get the features. - Get a list of features that can be included in snapshots using the feature_states field when creating a snapshot. +

                            Get the features.

                            +

                            Get a list of features that can be included in snapshots using the feature_states field when creating a snapshot. You can use this API to determine which feature states to include when taking a snapshot. By default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.

                            A feature state includes one or more system indices necessary for a given feature to function. @@ -76,7 +76,7 @@ def get_features( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def reset_features( self, *, @@ -89,8 +89,8 @@ def reset_features( """ .. raw:: html -

                            Reset the features. - Clear all of the state information stored in system indices by Elasticsearch features, including the security and machine learning indices.

                            +

                            Reset the features.

                            +

                            Clear all of the state information stored in system indices by Elasticsearch features, including the security and machine learning indices.

                            WARNING: Intended for development and testing use only. Do not reset features on a production cluster.

                            Return a cluster to the same state as a new installation by resetting the feature state for all Elasticsearch features. This deletes all state information stored in system indices.

                            diff --git a/elasticsearch/_sync/client/fleet.py b/elasticsearch/_sync/client/fleet.py index 44178398d..4b36d83c2 100644 --- a/elasticsearch/_sync/client/fleet.py +++ b/elasticsearch/_sync/client/fleet.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -101,7 +101,7 @@ def global_checkpoints( @_rewrite_parameters( body_name="searches", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def msearch( self, *, @@ -138,8 +138,8 @@ def msearch( """ .. raw:: html -

                            Run multiple Fleet searches. - Run several Fleet searches with a single API request. +

                            Run multiple Fleet searches.

                            +

                            Run several Fleet searches with a single API request. The API follows the same structure as the multi search API. However, similar to the Fleet search API, it supports the wait_for_checkpoints parameter.

                            @@ -293,7 +293,7 @@ def msearch( "from": "from_", }, ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def search( self, *, @@ -388,8 +388,8 @@ def search( """ .. raw:: html -

                            Run a Fleet search. - The purpose of the Fleet search API is to provide an API where the search will be run only +

                            Run a Fleet search.

                            +

                            The purpose of the Fleet search API is to provide an API where the search will be run only after the provided checkpoint has been processed and is visible for searches inside of Elasticsearch.

                            @@ -642,11 +642,7 @@ def search( __body["track_total_hits"] = track_total_hits if version is not None: __body["version"] = version - 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 self.perform_request( # type: ignore[return-value] "POST", __path, diff --git a/elasticsearch/_sync/client/graph.py b/elasticsearch/_sync/client/graph.py index 735917b80..fc7512530 100644 --- a/elasticsearch/_sync/client/graph.py +++ b/elasticsearch/_sync/client/graph.py @@ -47,8 +47,8 @@ def explore( """ .. raw:: html -

                            Explore graph analytics. - Extract and summarize information about the documents and terms in an Elasticsearch data stream or index. +

                            Explore graph analytics.

                            +

                            Extract and summarize information about the documents and terms in an Elasticsearch data stream or index. The easiest way to understand the behavior of this API is to use the Graph UI to explore connections. An initial request to the _explore API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph. Subsequent requests enable you to spider out from one more vertices of interest. @@ -97,11 +97,7 @@ def explore( __body["query"] = query if vertices is not None: __body["vertices"] = vertices - 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 self.perform_request( # type: ignore[return-value] "POST", __path, diff --git a/elasticsearch/_sync/client/ilm.py b/elasticsearch/_sync/client/ilm.py index 26424284a..c845de530 100644 --- a/elasticsearch/_sync/client/ilm.py +++ b/elasticsearch/_sync/client/ilm.py @@ -40,8 +40,8 @@ def delete_lifecycle( """ .. raw:: html -

                            Delete a lifecycle policy. - You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.

                            +

                            Delete a lifecycle policy.

                            +

                            You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.

                            ``_ @@ -96,8 +96,8 @@ def explain_lifecycle( """ .. raw:: html -

                            Explain the lifecycle state. - Get the current lifecycle status for one or more indices. +

                            Explain the lifecycle state.

                            +

                            Get the current lifecycle status for one or more indices. For data streams, the API retrieves the current lifecycle status for the stream's backing indices.

                            The response indicates when the index entered each lifecycle state, provides the definition of the running phase, and information about any failures.

                            @@ -260,8 +260,8 @@ def migrate_to_data_tiers( """ .. raw:: html -

                            Migrate to data tiers routing. - Switch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers. +

                            Migrate to data tiers routing.

                            +

                            Switch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers. Optionally, delete one legacy index template. Using node roles enables ILM to automatically move the indices between data tiers.

                            Migrating away from custom node attributes routing can be manually performed. @@ -341,8 +341,8 @@ def move_to_step( """ .. raw:: html -

                            Move to a lifecycle step. - Manually move an index into a specific step in the lifecycle policy and run that step.

                            +

                            Move to a lifecycle step.

                            +

                            Manually move an index into a specific step in the lifecycle policy and run that step.

                            WARNING: This operation can result in the loss of data. Manually moving an index into a specific step runs that step even if it has already been performed. This is a potentially destructive action and this should be considered an expert level API.

                            You must specify both the current step and the step to be executed in the body of the request. The request will fail if the current step does not match the step currently running for the index @@ -383,11 +383,7 @@ def move_to_step( __body["current_step"] = current_step if next_step is not None: __body["next_step"] = next_step - 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 self.perform_request( # type: ignore[return-value] "POST", __path, @@ -417,8 +413,8 @@ def put_lifecycle( """ .. raw:: html -

                            Create or update a lifecycle policy. - If the specified policy exists, it is replaced and the policy version is incremented.

                            +

                            Create or update a lifecycle policy.

                            +

                            If the specified policy exists, it is replaced and the policy version is incremented.

                            NOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.

                            @@ -453,11 +449,7 @@ def put_lifecycle( if not __body: if policy is not None: __body["policy"] = policy - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -481,8 +473,8 @@ def remove_policy( """ .. raw:: html -

                            Remove policies from an index. - Remove the assigned lifecycle policies from an index or a data stream's backing indices. +

                            Remove policies from an index.

                            +

                            Remove the assigned lifecycle policies from an index or a data stream's backing indices. It also stops managing the indices.

                            @@ -526,8 +518,8 @@ def retry( """ .. raw:: html -

                            Retry a policy. - Retry running the lifecycle policy for an index that is in the ERROR step. +

                            Retry a policy.

                            +

                            Retry running the lifecycle policy for an index that is in the ERROR step. The API sets the policy back to the step where the error occurred and runs the step. Use the explain lifecycle state API to determine whether an index is in the ERROR step.

                            @@ -574,8 +566,8 @@ def start( """ .. raw:: html -

                            Start the ILM plugin. - Start the index lifecycle management plugin if it is currently stopped. +

                            Start the ILM plugin.

                            +

                            Start the index lifecycle management plugin if it is currently stopped. ILM is started automatically when the cluster is formed. Restarting ILM is necessary only when it has been stopped using the stop ILM API.

                            @@ -627,8 +619,8 @@ def stop( """ .. raw:: html -

                            Stop the ILM plugin. - Halt all lifecycle management operations and stop the index lifecycle management plugin. +

                            Stop the ILM plugin.

                            +

                            Halt all lifecycle management operations and stop the index lifecycle management plugin. This is useful when you are performing maintenance on the cluster and need to prevent ILM from performing any actions on your indices.

                            The API returns as soon as the stop request has been acknowledged, but the plugin might continue to run until in-progress operations complete and the plugin can be safely stopped. Use the get ILM status API to check whether ILM is running.

                            diff --git a/elasticsearch/_sync/client/indices.py b/elasticsearch/_sync/client/indices.py index 8697d971b..9bd49afa2 100644 --- a/elasticsearch/_sync/client/indices.py +++ b/elasticsearch/_sync/client/indices.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -165,8 +165,8 @@ def analyze( """ .. raw:: html -

                            Get tokens from text analysis. - The analyze API performs analysis on a text string and returns the resulting tokens.

                            +

                            Get tokens from text analysis.

                            +

                            The analyze API performs analysis on a text string and returns the resulting tokens.

                            Generating excessive amount of tokens may cause a node to run out of memory. The index.analyze.max_token_count setting enables you to limit the number of tokens that can be produced. If more than this limit of tokens gets generated, an error occurs. @@ -232,11 +232,7 @@ def analyze( __body["text"] = text if tokenizer is not None: __body["tokenizer"] = tokenizer - 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 self.perform_request( # type: ignore[return-value] "POST", __path, @@ -248,7 +244,7 @@ def analyze( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def cancel_migrate_reindex( self, *, @@ -319,8 +315,8 @@ def clear_cache( """ .. raw:: html -

                            Clear the cache. - Clear the cache of one or more indices. +

                            Clear the cache.

                            +

                            Clear the cache of one or more indices. For data streams, the API clears the caches of the stream's backing indices.

                            By default, the clear cache API clears all caches. To clear only specific caches, use the fielddata, query, or request parameters. @@ -412,8 +408,8 @@ def clone( """ .. raw:: html -

                            Clone an index. - Clone an existing index into a new index. +

                            Clone an index.

                            +

                            Clone an existing index into a new index. Each original primary shard is cloned into a new primary shard in the new index.

                            IMPORTANT: Elasticsearch does not apply index templates to the resulting index. The API also does not copy index metadata from the original index. @@ -537,8 +533,8 @@ def close( """ .. raw:: html -

                            Close an index. - A closed index is blocked for read or write operations and does not allow all operations that opened indices allow. +

                            Close an index.

                            +

                            A closed index is blocked for read or write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. Closed indices do not have to maintain internal data structures for indexing or searching documents, which results in a smaller overhead on the cluster.

                            When opening or closing an index, the master node is responsible for restarting the index shards to reflect the new state of the index. @@ -634,8 +630,8 @@ def create( """ .. raw:: html -

                            Create an index. - You can use the create index API to add a new index to an Elasticsearch cluster. +

                            Create an index.

                            +

                            You can use the create index API to add a new index to an Elasticsearch cluster. When creating an index, you can specify the following:

                            • Settings for the index.
                            • @@ -782,7 +778,7 @@ def create_data_stream( @_rewrite_parameters( body_name="create_from", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def create_from( self, *, @@ -812,11 +808,7 @@ def create_from( raise ValueError("Empty value passed for parameter 'source'") if dest in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'dest'") - if create_from is None and body is None: - raise ValueError( - "Empty value passed for parameters 'create_from' and 'body', one of them should be set." - ) - elif create_from is not None and body is not None: + if create_from is not None and body is not None: raise ValueError("Cannot set both 'create_from' and 'body'") __path_parts: t.Dict[str, str] = { "source": _quote(source), @@ -833,7 +825,11 @@ def create_from( if pretty is not None: __query["pretty"] = pretty __body = create_from if create_from is not None else body - __headers = {"accept": "application/json", "content-type": "application/json"} + if not __body: + __body = None + __headers = {"accept": "application/json"} + if __body is not None: + __headers["content-type"] = "application/json" return self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -930,8 +926,8 @@ def delete( """ .. raw:: html -

                              Delete indices. - Deleting an index deletes its documents, shards, and metadata. +

                              Delete indices.

                              +

                              Deleting an index deletes its documents, shards, and metadata. It does not delete related Kibana components, such as data views, visualizations, or dashboards.

                              You cannot delete the current write index of a data stream. To delete the index, you must roll over the data stream so a new write index is created. @@ -1008,8 +1004,8 @@ def delete_alias( """ .. raw:: html -

                              Delete an alias. - Removes a data stream or index from an alias.

                              +

                              Delete an alias.

                              +

                              Removes a data stream or index from an alias.

                              ``_ @@ -1076,18 +1072,18 @@ def delete_data_lifecycle( """ .. raw:: html -

                              Delete data stream lifecycles. - Removes the data stream lifecycle from a data stream, rendering it not managed by the data stream lifecycle.

                              +

                              Delete data stream lifecycles.

                              +

                              Removes the data stream lifecycle from a data stream, rendering it not managed by the data stream lifecycle.

                              ``_ :param name: A comma-separated list of data streams of which the data stream - lifecycle will be deleted; use `*` to get all data streams + lifecycle will be deleted. Use `*` to get all data streams :param expand_wildcards: Whether wildcard expressions should get expanded to open or closed indices (default: open) - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit timestamp for the document + :param master_timeout: The period to wait for a connection to the master node. + :param timeout: The period to wait for a response. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -1140,8 +1136,8 @@ def delete_data_stream( """ .. raw:: html -

                              Delete data streams. - Deletes one or more data streams and their backing indices.

                              +

                              Delete data streams.

                              +

                              Deletes one or more data streams and their backing indices.

                              ``_ @@ -1204,18 +1200,18 @@ def delete_data_stream_options( """ .. raw:: html -

                              Delete data stream options. - Removes the data stream options from a data stream.

                              +

                              Delete data stream options.

                              +

                              Removes the data stream options from a data stream.

                              - ``_ + ``_ :param name: A comma-separated list of data streams of which the data stream - options will be deleted; use `*` to get all data streams + options will be deleted. Use `*` to get all data streams :param expand_wildcards: Whether wildcard expressions should get expanded to - open or closed indices (default: open) - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit timestamp for the document + open or closed indices + :param master_timeout: The period to wait for a connection to the master node. + :param timeout: The period to wait for a response. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -1261,8 +1257,8 @@ def delete_index_template( """ .. raw:: html -

                              Delete an index template. - The provided may contain multiple template names separated by a comma. If multiple template +

                              Delete an index template.

                              +

                              The provided may contain multiple template names separated by a comma. If multiple template names are specified then there is no wildcard support and the provided names should match completely with existing templates.

                              @@ -1319,8 +1315,8 @@ def delete_template( """ .. raw:: html -

                              Delete a legacy index template. - IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

                              +

                              Delete a legacy index template.

                              +

                              IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

                              ``_ @@ -1361,7 +1357,7 @@ def delete_template( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def disk_usage( self, *, @@ -1386,8 +1382,8 @@ def disk_usage( """ .. raw:: html -

                              Analyze the index disk usage. - Analyze the disk usage of each field of an index or data stream. +

                              Analyze the index disk usage.

                              +

                              Analyze the disk usage of each field of an index or data stream. This API might not support indices created in previous Elasticsearch versions. The result of a small index can be inaccurate as some parts of an index might not be analyzed by the API.

                              NOTE: The total size of fields of the analyzed shards of the index in the response is usually smaller than the index store_size value because some small metadata files are ignored and some parts of data files might not be scanned by the API. @@ -1453,7 +1449,7 @@ def disk_usage( @_rewrite_parameters( body_name="config", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def downsample( self, *, @@ -1469,8 +1465,8 @@ def downsample( """ .. raw:: html -

                              Downsample an index. - Aggregate a time series (TSDS) index and store pre-computed statistical summaries (min, max, sum, value_count and avg) for each metric field grouped by a configured time interval. +

                              Downsample an index.

                              +

                              Aggregate a time series (TSDS) index and store pre-computed statistical summaries (min, max, sum, value_count and avg) for each metric field grouped by a configured time interval. For example, a TSDS index that contains metrics sampled every 10 seconds can be downsampled to an hourly index. All documents within an hour interval are summarized and stored as a single document in the downsample index.

                              NOTE: Only indices in a time series data stream are supported. @@ -1546,8 +1542,8 @@ def exists( """ .. raw:: html -

                              Check indices. - Check if one or more indices, index aliases, or data streams exist.

                              +

                              Check indices.

                              +

                              Check if one or more indices, index aliases, or data streams exist.

                              ``_ @@ -1766,8 +1762,8 @@ def exists_template( """ .. raw:: html -

                              Check existence of index templates. - Get information about whether index templates exist. +

                              Check existence of index templates.

                              +

                              Get information about whether index templates exist. Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

                              IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

                              @@ -1826,16 +1822,16 @@ def explain_data_lifecycle( """ .. raw:: html -

                              Get the status for a data stream lifecycle. - Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.

                              +

                              Get the status for a data stream lifecycle.

                              +

                              Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.

                              ``_ - :param index: The name of the index to explain - :param include_defaults: indicates if the API should return the default values + :param index: Comma-separated list of index names to explain + :param include_defaults: Indicates if the API should return the default values the system uses for the index's lifecycle - :param master_timeout: Specify timeout for connection to master + :param master_timeout: The period to wait for a connection to the master node. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1865,7 +1861,7 @@ def explain_data_lifecycle( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def field_usage_stats( self, *, @@ -1889,8 +1885,8 @@ def field_usage_stats( """ .. raw:: html -

                              Get field usage stats. - Get field usage information for each shard and field of an index. +

                              Get field usage stats.

                              +

                              Get field usage information for each shard and field of an index. Field usage statistics are automatically captured when queries are running on a cluster. A shard-level search request that accesses a given field, even if multiple times during that request, is counted as a single use.

                              The response body reports the per-shard usage count of the data structures that back the fields in the index. @@ -1971,8 +1967,8 @@ def flush( """ .. raw:: html -

                              Flush data streams or indices. - Flushing a data stream or index is the process of making sure that any data that is currently only stored in the transaction log is also permanently stored in the Lucene index. +

                              Flush data streams or indices.

                              +

                              Flushing a data stream or index is the process of making sure that any data that is currently only stored in the transaction log is also permanently stored in the Lucene index. When restarting, Elasticsearch replays any unflushed operations from the transaction log into the Lucene index to bring it back into the state that it was in before the restart. Elasticsearch automatically triggers flushes as needed, using heuristics that trade off the size of the unflushed transaction log against the cost of performing each flush.

                              After each operation has been flushed it is permanently stored in the Lucene index. @@ -2065,8 +2061,8 @@ def forcemerge( """ .. raw:: html -

                              Force a merge. - Perform the force merge operation on the shards of one or more indices. +

                              Force a merge.

                              +

                              Perform the force merge operation on the shards of one or more indices. For data streams, the API forces a merge on the shards of the stream's backing indices.

                              Merging reduces the number of segments in each shard by merging some of them together and also frees up the space used by deleted documents. Merging normally happens automatically, but sometimes it is useful to trigger a merge manually.

                              @@ -2117,15 +2113,15 @@ def forcemerge( :param expand_wildcards: Whether to expand wildcard expression to concrete indices that are open, closed or both. :param flush: Specify whether the index should be flushed after performing the - operation (default: true) + operation :param ignore_unavailable: Whether specified concrete indices should be ignored when unavailable (missing or closed) :param max_num_segments: The number of segments the index should be merged into - (default: dynamic) + (defayult: dynamic) :param only_expunge_deletes: Specify whether the operation should only expunge deleted documents :param wait_for_completion: Should the request wait until the force merge is - completed. + completed """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -2200,8 +2196,8 @@ def get( """ .. raw:: html -

                              Get index information. - Get information about one or more indices. For data streams, the API returns information about the +

                              Get index information.

                              +

                              Get information about one or more indices. For data streams, the API returns information about the stream’s backing indices.

                              @@ -2294,8 +2290,8 @@ def get_alias( """ .. raw:: html -

                              Get aliases. - Retrieves information for one or more data stream or index aliases.

                              +

                              Get aliases.

                              +

                              Retrieves information for one or more data stream or index aliases.

                              ``_ @@ -2438,8 +2434,8 @@ def get_data_lifecycle_stats( """ .. raw:: html -

                              Get data stream lifecycle stats. - Get statistics about the data streams that are managed by a data stream lifecycle.

                              +

                              Get data stream lifecycle stats.

                              +

                              Get statistics about the data streams that are managed by a data stream lifecycle.

                              ``_ @@ -2542,57 +2538,6 @@ def get_data_stream( path_parts=__path_parts, ) - @_rewrite_parameters() - def get_data_stream_mappings( - self, - *, - name: t.Union[str, t.Sequence[str]], - 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]: - """ - .. raw:: html - -

                              Get data stream mappings.

                              -

                              Get mapping information for one or more data streams.

                              - - - ``_ - - :param name: A comma-separated list of data streams or data stream patterns. - Supports wildcards (`*`). - :param master_timeout: The 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'") - __path_parts: t.Dict[str, str] = {"name": _quote(name)} - __path = f'/_data_stream/{__path_parts["name"]}/_mappings' - __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 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"} - return self.perform_request( # type: ignore[return-value] - "GET", - __path, - params=__query, - headers=__headers, - endpoint_id="indices.get_data_stream_mappings", - path_parts=__path_parts, - ) - @_rewrite_parameters() def get_data_stream_options( self, @@ -2619,7 +2564,7 @@ def get_data_stream_options(

                              Get the data stream options configuration of one or more data streams.

                              - ``_ + ``_ :param name: Comma-separated list of data streams to limit the request. Supports wildcards (`*`). To target all data streams, omit this parameter or use `*` @@ -2733,8 +2678,8 @@ def get_field_mapping( """ .. raw:: html -

                              Get mapping definitions. - Retrieves mapping definitions for one or more fields. +

                              Get mapping definitions.

                              +

                              Retrieves mapping definitions for one or more fields. For data streams, the API retrieves field mappings for the stream’s backing indices.

                              This API is useful if you don't need a complete mapping or if an index mapping contains a large number of fields.

                              @@ -2812,14 +2757,14 @@ def get_index_template( """ .. raw:: html -

                              Get index templates. - Get information about one or more index templates.

                              +

                              Get index templates.

                              +

                              Get information about one or more index templates.

                              ``_ - :param name: Comma-separated list of index template names used to limit the request. - Wildcard (*) expressions are supported. + :param name: Name of index template to retrieve. Wildcard (*) expressions are + supported. :param flat_settings: If true, returns settings in flat format. :param include_defaults: If true, returns all relevant default configurations for the index template. @@ -2889,8 +2834,8 @@ def get_mapping( """ .. raw:: html -

                              Get mapping definitions. - For data streams, the API retrieves mappings for the stream’s backing indices.

                              +

                              Get mapping definitions.

                              +

                              For data streams, the API retrieves mappings for the stream’s backing indices.

                              ``_ @@ -2950,7 +2895,7 @@ def get_mapping( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def get_migrate_reindex_status( self, *, @@ -3022,8 +2967,8 @@ def get_settings( """ .. raw:: html -

                              Get index settings. - Get setting information for one or more indices. +

                              Get index settings.

                              +

                              Get setting information for one or more indices. For data streams, it returns setting information for the stream's backing indices.

                              @@ -3114,8 +3059,8 @@ def get_template( """ .. raw:: html -

                              Get legacy index templates. - Get information about one or more index templates.

                              +

                              Get legacy index templates.

                              +

                              Get information about one or more index templates.

                              IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

                              @@ -3166,7 +3111,7 @@ def get_template( @_rewrite_parameters( body_name="reindex", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def migrate_reindex( self, *, @@ -3234,8 +3179,8 @@ def migrate_to_data_stream( """ .. raw:: html -

                              Convert an index alias to a data stream. - Converts an index alias to a data stream. +

                              Convert an index alias to a data stream.

                              +

                              Converts an index alias to a data stream. You must have a matching index template that is data stream enabled. The alias must meet the following criteria: The alias must have a write index; @@ -3299,8 +3244,8 @@ def modify_data_stream( """ .. raw:: html -

                              Update data streams. - Performs one or more data stream modification actions in a single atomic operation.

                              +

                              Update data streams.

                              +

                              Performs one or more data stream modification actions in a single atomic operation.

                              ``_ @@ -3363,8 +3308,8 @@ def open( """ .. raw:: html -

                              Open a closed index. - For data streams, the API opens any closed backing indices.

                              +

                              Open a closed index.

                              +

                              For data streams, the API opens any closed backing indices.

                              A closed index is blocked for read/write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. This allows closed indices to not have to maintain internal data structures for indexing or searching documents, resulting in a smaller overhead on the cluster.

                              @@ -3457,8 +3402,8 @@ def promote_data_stream( """ .. raw:: html -

                              Promote a data stream. - Promote a data stream from a replicated data stream managed by cross-cluster replication (CCR) to a regular data stream.

                              +

                              Promote a data stream.

                              +

                              Promote a data stream from a replicated data stream managed by cross-cluster replication (CCR) to a regular data stream.

                              With CCR auto following, a data stream from a remote cluster can be replicated to the local cluster. These data streams can't be rolled over in the local cluster. These replicated data streams roll over only if the upstream data stream rolls over. @@ -3470,7 +3415,7 @@ def promote_data_stream( ``_ - :param name: The name of the data stream + :param name: The name of the data stream to promote :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. @@ -3530,8 +3475,8 @@ def put_alias( """ .. raw:: html -

                              Create or update an alias. - Adds a data stream or index to an alias.

                              +

                              Create or update an alias.

                              +

                              Adds a data stream or index to an alias.

                              ``_ @@ -3616,7 +3561,7 @@ def put_data_lifecycle( *, name: t.Union[str, t.Sequence[str]], data_retention: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, - downsampling: t.Optional[t.Mapping[str, t.Any]] = None, + downsampling: t.Optional[t.Sequence[t.Mapping[str, t.Any]]] = None, enabled: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, expand_wildcards: t.Optional[ @@ -3637,8 +3582,8 @@ def put_data_lifecycle( """ .. raw:: html -

                              Update data stream lifecycles. - Update the data stream lifecycle of the specified data streams.

                              +

                              Update data stream lifecycles.

                              +

                              Update the data stream lifecycle of the specified data streams.

                              ``_ @@ -3689,87 +3634,6 @@ def put_data_lifecycle( __body["downsampling"] = downsampling if enabled is not None: __body["enabled"] = enabled - if not __body: - __body = None # type: ignore[assignment] - __headers = {"accept": "application/json"} - if __body is not None: - __headers["content-type"] = "application/json" - return self.perform_request( # type: ignore[return-value] - "PUT", - __path, - params=__query, - headers=__headers, - body=__body, - endpoint_id="indices.put_data_lifecycle", - path_parts=__path_parts, - ) - - @_rewrite_parameters( - body_name="mappings", - ) - def put_data_stream_mappings( - self, - *, - name: t.Union[str, t.Sequence[str]], - mappings: t.Optional[t.Mapping[str, t.Any]] = None, - body: t.Optional[t.Mapping[str, t.Any]] = None, - dry_run: t.Optional[bool] = None, - 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]: - """ - .. raw:: html - -

                              Update data stream mappings.

                              -

                              This API can be used to override mappings on specific data streams. These overrides will take precedence over what - is specified in the template that the data stream matches. The mapping change is only applied to new write indices - that are created during rollover after this API is called. No indices are changed by this API.

                              - - - ``_ - - :param name: A comma-separated list of data streams or data stream patterns. - :param mappings: - :param dry_run: If `true`, the request does not actually change the mappings - on any data streams. Instead, it simulates changing the settings and reports - back to the user what would have happened had these settings actually been - applied. - :param master_timeout: The 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: The 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'") - if mappings is None and body is None: - raise ValueError( - "Empty value passed for parameters 'mappings' and 'body', one of them should be set." - ) - elif mappings is not None and body is not None: - raise ValueError("Cannot set both 'mappings' and 'body'") - __path_parts: t.Dict[str, str] = {"name": _quote(name)} - __path = f'/_data_stream/{__path_parts["name"]}/_mappings' - __query: t.Dict[str, t.Any] = {} - if dry_run is not None: - __query["dry_run"] = dry_run - if error_trace is not None: - __query["error_trace"] = error_trace - if filter_path is not None: - __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 = mappings if mappings is not None else body __headers = {"accept": "application/json", "content-type": "application/json"} return self.perform_request( # type: ignore[return-value] "PUT", @@ -3777,7 +3641,7 @@ def put_data_stream_mappings( params=__query, headers=__headers, body=__body, - endpoint_id="indices.put_data_stream_mappings", + endpoint_id="indices.put_data_lifecycle", path_parts=__path_parts, ) @@ -3808,11 +3672,11 @@ def put_data_stream_options( """ .. raw:: html -

                              Update data stream options. - Update the data stream options of the specified data streams.

                              +

                              Update data stream options.

                              +

                              Update the data stream options of the specified data streams.

                              - ``_ + ``_ :param name: Comma-separated list of data streams used to limit the request. Supports wildcards (`*`). To target all data streams use `*` or `_all`. @@ -3849,11 +3713,7 @@ def put_data_stream_options( if not __body: if failure_store is not None: __body["failure_store"] = failure_store - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -3983,8 +3843,8 @@ def put_index_template( """ .. raw:: html -

                              Create or update an index template. - Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

                              +

                              Create or update an index template.

                              +

                              Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

                              Elasticsearch applies templates to new indices based on an wildcard pattern that matches the index name. Index templates are applied during data stream or index creation. For data streams, these settings and mappings are applied when the stream's backing indices are created. @@ -4015,7 +3875,7 @@ def put_index_template( via `actions.auto_create_index`. If set to `false`, then indices or data streams matching the template must always be explicitly created, and may never be automatically created. - :param cause: User defined reason for creating/updating the index template + :param cause: User defined reason for creating or updating the index template :param composed_of: An ordered list of component template names. Component templates are merged in the order specified, meaning that the last component template specified has the highest precedence. @@ -4167,8 +4027,8 @@ def put_mapping( """ .. raw:: html -

                              Update field mappings. - Add new fields to an existing data stream or index. +

                              Update field mappings.

                              +

                              Add new fields to an existing data stream or index. You can use the update mapping API to:

                              • Add a new field to an existing index
                              • @@ -4179,13 +4039,13 @@ def put_mapping(
                              • Change a field's mapping using reindexing
                              • Rename a field using a field alias
                              -

                              Learn how to use the update mapping API with practical examples in the Update mapping API examples guide.

                              +

                              Learn how to use the update mapping API with practical examples in the Update mapping API examples guide.

                              ``_ :param index: A comma-separated list of index names the mapping should be added - to (supports wildcards); use `_all` or omit to add the mapping on all indices. + to (supports wildcards). Use `_all` or omit to add the mapping on all indices. :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. @@ -4312,8 +4172,8 @@ def put_settings( """ .. raw:: html -

                              Update index settings. - Changes dynamic index settings in real time. +

                              Update index settings.

                              +

                              Changes dynamic index settings in real time. For data streams, index setting changes are applied to all backing indices by default.

                              To revert a setting to the default value, use a null value. The list of per-index settings that can be updated dynamically on live indices can be found in index settings documentation. @@ -4466,8 +4326,8 @@ def put_template( """ .. raw:: html -

                              Create or update a legacy index template. - Index templates define settings, mappings, and aliases that can be applied automatically to new indices. +

                              Create or update a legacy index template.

                              +

                              Index templates define settings, mappings, and aliases that can be applied automatically to new indices. Elasticsearch applies templates to new indices based on an index pattern that matches the index name.

                              IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

                              Composable templates always take precedence over legacy templates. @@ -4487,7 +4347,7 @@ def put_template( :param name: The name of the template :param aliases: Aliases for the index. - :param cause: User defined reason for creating/updating the index template + :param cause: User defined reason for creating or updating the index template :param create: If true, this request cannot replace or update existing index templates. :param index_patterns: Array of wildcard expressions used to match the names @@ -4574,8 +4434,8 @@ def recovery( """ .. raw:: html -

                              Get index recovery information. - Get information about ongoing and completed shard recoveries for one or more indices. +

                              Get index recovery information.

                              +

                              Get information about ongoing and completed shard recoveries for one or more indices. For data streams, the API returns information for the stream's backing indices.

                              All recoveries, whether ongoing or complete, are kept in the cluster state and may be reported on at any time.

                              Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or creating a replica shard from a primary shard. @@ -4672,11 +4532,12 @@ def refresh( """ .. raw:: html -

                              Refresh an index. - A refresh makes recent operations performed on one or more indices available for search. +

                              Refresh an index.

                              +

                              A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.

                              By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds. You can change this default interval with the index.refresh_interval setting.

                              +

                              In Elastic Cloud Serverless, the default refresh interval is 5 seconds across all indices.

                              Refresh requests are synchronous and do not return a response until the refresh operation completes.

                              Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.

                              @@ -4755,8 +4616,8 @@ def reload_search_analyzers( """ .. raw:: html -

                              Reload search analyzers. - Reload an index's search analyzers and their resources. +

                              Reload search analyzers.

                              +

                              Reload an index's search analyzers and their resources. For data streams, the API reloads search analyzers and resources for the stream's backing indices.

                              IMPORTANT: After reloading the search analyzers you should clear the request cache to make sure it doesn't contain responses derived from the previous versions of the analyzer.

                              You can use the reload search analyzers API to pick up changes to synonym files used in the synonym_graph or synonym token filter of a search analyzer. @@ -5070,8 +4931,8 @@ def resolve_index( """ .. raw:: html -

                              Resolve indices. - Resolve the names and/or index patterns for indices, aliases, and data streams. +

                              Resolve indices.

                              +

                              Resolve the names and/or index patterns for indices, aliases, and data streams. Multiple patterns and remote clusters are supported.

                              @@ -5149,8 +5010,8 @@ def rollover( """ .. raw:: html -

                              Roll over to a new index. - TIP: It is recommended to use the index lifecycle rollover action to automate rollovers.

                              +

                              Roll over to a new index.

                              +

                              TIP: It is recommended to use the index lifecycle rollover action to automate rollovers.

                              The rollover API creates a new index for a data stream or index alias. The API behavior depends on the rollover target.

                              Roll over a data stream

                              @@ -5286,8 +5147,8 @@ def segments( """ .. raw:: html -

                              Get index segments. - Get low-level information about the Lucene segments in index shards. +

                              Get index segments.

                              +

                              Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the stream's backing indices.

                              @@ -5367,8 +5228,8 @@ def shard_stores( """ .. raw:: html -

                              Get index shard stores. - Get store information about replica shards in one or more indices. +

                              Get index shard stores.

                              +

                              Get store information about replica shards in one or more indices. For data streams, the API retrieves store information for the stream's backing indices.

                              The index shard stores API returns the following information:

                                @@ -5451,8 +5312,8 @@ def shrink( """ .. raw:: html -

                                Shrink an index. - Shrink an index into a new index with fewer primary shards.

                                +

                                Shrink an index.

                                +

                                Shrink an index into a new index with fewer primary shards.

                                Before you can shrink an index:

                                • The index must be read-only.
                                • @@ -5527,11 +5388,7 @@ def shrink( __body["aliases"] = aliases if settings is not None: __body["settings"] = settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -5542,7 +5399,9 @@ def shrink( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_name="index_template", + ) def simulate_index_template( self, *, @@ -5553,14 +5412,16 @@ def simulate_index_template( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, include_defaults: t.Optional[bool] = None, + index_template: t.Optional[t.Mapping[str, t.Any]] = None, + body: t.Optional[t.Mapping[str, t.Any]] = None, master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html -

                                  Simulate an index. - Get the index configuration that would be applied to the specified index from an existing index template.

                                  +

                                  Simulate an index.

                                  +

                                  Get the index configuration that would be applied to the specified index from an existing index template.

                                  ``_ @@ -5572,12 +5433,15 @@ def simulate_index_template( only be dry-run added if new or can also replace an existing one :param include_defaults: If true, returns all relevant default configurations for the index template. + :param index_template: :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'") + if index_template is not None and body is not None: + raise ValueError("Cannot set both 'index_template' and 'body'") __path_parts: t.Dict[str, str] = {"name": _quote(name)} __path = f'/_index_template/_simulate_index/{__path_parts["name"]}' __query: t.Dict[str, t.Any] = {} @@ -5597,12 +5461,18 @@ def simulate_index_template( __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + __body = index_template if index_template is not None else body + if not __body: + __body = None __headers = {"accept": "application/json"} + if __body is not None: + __headers["content-type"] = "application/json" return self.perform_request( # type: ignore[return-value] "POST", __path, params=__query, headers=__headers, + body=__body, endpoint_id="indices.simulate_index_template", path_parts=__path_parts, ) @@ -5649,8 +5519,8 @@ def simulate_template( """ .. raw:: html -

                                  Simulate an index template. - Get the index configuration that would be applied by a particular index template.

                                  +

                                  Simulate an index template.

                                  +

                                  Get the index configuration that would be applied by a particular index template.

                                  ``_ @@ -5788,8 +5658,8 @@ def split( """ .. raw:: html -

                                  Split an index. - Split an index into a new index with more primary shards.

                                  +

                                  Split an index.

                                  +

                                  Split an index into a new index with more primary shards.

                                  • Before you can split an index:

                                    @@ -5870,11 +5740,7 @@ def split( __body["aliases"] = aliases if settings is not None: __body["settings"] = settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -5917,8 +5783,8 @@ def stats( """ .. raw:: html -

                                    Get index statistics. - For data streams, the API retrieves statistics for the stream's backing indices.

                                    +

                                    Get index statistics.

                                    +

                                    For data streams, the API retrieves statistics for the stream's backing indices.

                                    By default, the returned statistics are index-level with primaries and total aggregations. primaries are the values for only the primary shards. total are the accumulated values for both primary and replica shards.

                                    @@ -5931,7 +5797,7 @@ def stats( :param index: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices - :param metric: Limit the information returned the specific metrics. + :param metric: Limit the information returned the specific metrics :param completion_fields: Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics. :param expand_wildcards: Type of index that wildcard patterns can match. If the @@ -5951,8 +5817,8 @@ def stats( are requested). :param include_unloaded_segments: If true, the response includes information from segments that are not loaded into memory. - :param level: Indicates whether statistics are aggregated at the cluster, index, - or shard level. + :param level: Indicates whether statistics are aggregated at the cluster, indices, + or shards level. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH and metric not in SKIP_IN_PATH: @@ -6022,8 +5888,8 @@ def update_aliases( """ .. raw:: html -

                                    Create or update an alias. - Adds a data stream or index to an alias.

                                    +

                                    Create or update an alias.

                                    +

                                    Adds a data stream or index to an alias.

                                    ``_ @@ -6101,8 +5967,8 @@ def validate_query( """ .. raw:: html -

                                    Validate a query. - Validates a query without running it.

                                    +

                                    Validate a query.

                                    +

                                    Validates a query without running it.

                                    ``_ diff --git a/elasticsearch/_sync/client/inference.py b/elasticsearch/_sync/client/inference.py index b7bab7f1c..3434faa1c 100644 --- a/elasticsearch/_sync/client/inference.py +++ b/elasticsearch/_sync/client/inference.py @@ -44,7 +44,7 @@ def completion( """ .. raw:: html -

                                    Perform completion inference on the service

                                    +

                                    Perform completion inference on the service.

                                    ``_ @@ -78,11 +78,7 @@ def completion( __body["input"] = input if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "POST", __path, @@ -120,7 +116,7 @@ def delete( """ .. raw:: html -

                                    Delete an inference endpoint

                                    +

                                    Delete an inference endpoint.

                                    ``_ @@ -194,7 +190,7 @@ def get( """ .. raw:: html -

                                    Get an inference endpoint

                                    +

                                    Get an inference endpoint.

                                    ``_ @@ -338,11 +334,7 @@ def inference( __body["query"] = query if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "POST", __path, @@ -391,21 +383,23 @@ def put(
                                    • AlibabaCloud AI Search (completion, rerank, sparse_embedding, text_embedding)
                                    • Amazon Bedrock (completion, text_embedding)
                                    • +
                                    • Amazon SageMaker (chat_completion, completion, rerank, sparse_embedding, text_embedding)
                                    • Anthropic (completion)
                                    • -
                                    • Azure AI Studio (completion, 'rerank', text_embedding)
                                    • +
                                    • Azure AI Studio (completion, text_embedding)
                                    • Azure OpenAI (completion, text_embedding)
                                    • Cohere (completion, rerank, text_embedding)
                                    • -
                                    • DeepSeek (completion, chat_completion)
                                    • +
                                    • DeepSeek (chat_completion, completion)
                                    • Elasticsearch (rerank, sparse_embedding, text_embedding - this service is for built-in models and models uploaded through Eland)
                                    • ELSER (sparse_embedding)
                                    • Google AI Studio (completion, text_embedding)
                                    • -
                                    • Google Vertex AI (rerank, text_embedding)
                                    • +
                                    • Google Vertex AI (chat_completion, completion, rerank, text_embedding)
                                    • Hugging Face (chat_completion, completion, rerank, text_embedding)
                                    • +
                                    • JinaAI (rerank, text_embedding)
                                    • +
                                    • Llama (chat_completion, completion, text_embedding)
                                    • Mistral (chat_completion, completion, text_embedding)
                                    • OpenAI (chat_completion, completion, text_embedding)
                                    • -
                                    • VoyageAI (text_embedding, rerank)
                                    • +
                                    • VoyageAI (rerank, text_embedding)
                                    • Watsonx inference integration (text_embedding)
                                    • -
                                    • JinaAI (text_embedding, rerank)
                                    @@ -544,11 +538,7 @@ def put_alibabacloud( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -644,11 +634,7 @@ def put_amazonbedrock( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -659,6 +645,108 @@ def put_amazonbedrock( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=( + "service", + "service_settings", + "chunking_settings", + "task_settings", + ), + ) + def put_amazonsagemaker( + self, + *, + task_type: t.Union[ + str, + t.Literal[ + "chat_completion", + "completion", + "rerank", + "sparse_embedding", + "text_embedding", + ], + ], + amazonsagemaker_inference_id: str, + service: t.Optional[t.Union[str, t.Literal["amazon_sagemaker"]]] = None, + service_settings: t.Optional[t.Mapping[str, t.Any]] = None, + chunking_settings: 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, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + task_settings: t.Optional[t.Mapping[str, t.Any]] = 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]: + """ + .. raw:: html + +

                                    Create an Amazon SageMaker inference endpoint.

                                    +

                                    Create an inference endpoint to perform an inference task with the amazon_sagemaker service.

                                    + + + ``_ + + :param task_type: The type of the inference task that the model will perform. + :param amazonsagemaker_inference_id: The unique identifier of the inference endpoint. + :param service: The type of service supported for the specified task type. In + this case, `amazon_sagemaker`. + :param service_settings: Settings used to install the inference model. These + settings are specific to the `amazon_sagemaker` service and `service_settings.api` + you specified. + :param chunking_settings: The chunking configuration object. + :param task_settings: Settings to configure the inference task. These settings + are specific to the task type and `service_settings.api` you specified. + :param timeout: Specifies the amount of time to wait for the inference endpoint + to be created. + """ + if task_type in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'task_type'") + if amazonsagemaker_inference_id in SKIP_IN_PATH: + raise ValueError( + "Empty value passed for parameter 'amazonsagemaker_inference_id'" + ) + if service is None and body is None: + raise ValueError("Empty value passed for parameter 'service'") + if service_settings is None and body is None: + raise ValueError("Empty value passed for parameter 'service_settings'") + __path_parts: t.Dict[str, str] = { + "task_type": _quote(task_type), + "amazonsagemaker_inference_id": _quote(amazonsagemaker_inference_id), + } + __path = f'/_inference/{__path_parts["task_type"]}/{__path_parts["amazonsagemaker_inference_id"]}' + __query: t.Dict[str, t.Any] = {} + __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 filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout + if not __body: + if service is not None: + __body["service"] = service + if service_settings is not None: + __body["service_settings"] = service_settings + if chunking_settings is not None: + __body["chunking_settings"] = chunking_settings + if task_settings is not None: + __body["task_settings"] = task_settings + __headers = {"accept": "application/json", "content-type": "application/json"} + return self.perform_request( # type: ignore[return-value] + "PUT", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="inference.put_amazonsagemaker", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=( "service", @@ -741,11 +829,7 @@ def put_anthropic( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -767,7 +851,7 @@ def put_anthropic( def put_azureaistudio( self, *, - task_type: t.Union[str, t.Literal["completion", "rerank", "text_embedding"]], + task_type: t.Union[str, t.Literal["completion", "text_embedding"]], azureaistudio_inference_id: str, service: t.Optional[t.Union[str, t.Literal["azureaistudio"]]] = None, service_settings: t.Optional[t.Mapping[str, t.Any]] = None, @@ -837,11 +921,7 @@ def put_azureaistudio( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -941,11 +1021,7 @@ def put_azureopenai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1035,11 +1111,7 @@ def put_cohere( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1166,11 +1238,7 @@ def put_custom( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1250,11 +1318,7 @@ def put_deepseek( __body["service_settings"] = service_settings if chunking_settings is not None: __body["chunking_settings"] = chunking_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1362,11 +1426,7 @@ def put_elasticsearch( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1460,11 +1520,7 @@ def put_elser( __body["service_settings"] = service_settings if chunking_settings is not None: __body["chunking_settings"] = chunking_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1546,11 +1602,7 @@ def put_googleaistudio( __body["service_settings"] = service_settings if chunking_settings is not None: __body["chunking_settings"] = chunking_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1644,11 +1696,7 @@ def put_googlevertexai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1776,11 +1824,7 @@ def put_hugging_face( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1872,11 +1916,7 @@ def put_jinaai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1958,11 +1998,7 @@ def put_mistral( __body["service_settings"] = service_settings if chunking_settings is not None: __body["chunking_settings"] = chunking_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -2056,11 +2092,7 @@ def put_openai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -2151,11 +2183,7 @@ def put_voyageai( __body["chunking_settings"] = chunking_settings if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -2235,11 +2263,7 @@ def put_watsonx( __body["service"] = service if service_settings is not None: __body["service_settings"] = service_settings - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -2270,7 +2294,7 @@ def rerank( """ .. raw:: html -

                                    Perform reranking inference on the service

                                    +

                                    Perform reranking inference on the service.

                                    ``_ @@ -2312,11 +2336,7 @@ def rerank( __body["query"] = query if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "POST", __path, @@ -2346,7 +2366,7 @@ def sparse_embedding( """ .. raw:: html -

                                    Perform sparse embedding inference on the service

                                    +

                                    Perform sparse embedding inference on the service.

                                    ``_ @@ -2380,11 +2400,7 @@ def sparse_embedding( __body["input"] = input if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "POST", __path, @@ -2396,7 +2412,7 @@ def sparse_embedding( ) @_rewrite_parameters( - body_fields=("input", "task_settings"), + body_fields=("input", "input_type", "task_settings"), ) def text_embedding( self, @@ -2406,6 +2422,7 @@ def text_embedding( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + input_type: t.Optional[str] = None, pretty: t.Optional[bool] = None, task_settings: t.Optional[t.Any] = None, timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, @@ -2414,13 +2431,20 @@ def text_embedding( """ .. raw:: html -

                                    Perform text embedding inference on the service

                                    +

                                    Perform text embedding inference on the service.

                                    ``_ :param inference_id: The inference Id :param input: Inference input. Either a string or an array of strings. + :param input_type: The input data type for the text embedding model. Possible + values include: * `SEARCH` * `INGEST` * `CLASSIFICATION` * `CLUSTERING` Not + all services support all values. Unsupported values will trigger a validation + exception. Accepted values depend on the configured inference service, refer + to the relevant service-specific documentation for more info. > info > The + `input_type` parameter specified on the root level of the request body will + take precedence over the `input_type` parameter specified in `task_settings`. :param task_settings: Optional task settings :param timeout: Specifies the amount of time to wait for the inference request to complete. @@ -2446,13 +2470,11 @@ def text_embedding( if not __body: if input is not None: __body["input"] = input + if input_type is not None: + __body["input_type"] = input_type if task_settings is not None: __body["task_settings"] = task_settings - 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 self.perform_request( # type: ignore[return-value] "POST", __path, diff --git a/elasticsearch/_sync/client/ingest.py b/elasticsearch/_sync/client/ingest.py index 5fd38bd78..a31cb9cee 100644 --- a/elasticsearch/_sync/client/ingest.py +++ b/elasticsearch/_sync/client/ingest.py @@ -151,8 +151,8 @@ def delete_pipeline( """ .. raw:: html -

                                    Delete pipelines. - Delete one or more ingest pipelines.

                                    +

                                    Delete pipelines.

                                    +

                                    Delete one or more ingest pipelines.

                                    ``_ @@ -204,8 +204,8 @@ def geo_ip_stats( """ .. raw:: html -

                                    Get GeoIP statistics. - Get download statistics for GeoIP2 databases that are used with the GeoIP processor.

                                    +

                                    Get GeoIP statistics.

                                    +

                                    Get download statistics for GeoIP2 databases that are used with the GeoIP processor.

                                    ``_ @@ -355,7 +355,7 @@ def get_pipeline( :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 summary: Return pipelines without their definitions (default: false) + :param summary: Return pipelines without their definitions """ __path_parts: t.Dict[str, str] if id not in SKIP_IN_PATH: @@ -399,8 +399,8 @@ def processor_grok( """ .. raw:: html -

                                    Run a grok processor. - Extract structured fields out of a single text field within a document. +

                                    Run a grok processor.

                                    +

                                    Extract structured fields out of a single text field within a document. You must choose which field to extract matched fields from, as well as the grok pattern you expect will match. A grok pattern is like a regular expression that supports aliased expressions that can be reused.

                                    @@ -609,8 +609,8 @@ def put_pipeline( """ .. raw:: html -

                                    Create or update a pipeline. - Changes made using this API take effect immediately.

                                    +

                                    Create or update a pipeline.

                                    +

                                    Changes made using this API take effect immediately.

                                    ``_ diff --git a/elasticsearch/_sync/client/license.py b/elasticsearch/_sync/client/license.py index aca82098d..9f7f492e3 100644 --- a/elasticsearch/_sync/client/license.py +++ b/elasticsearch/_sync/client/license.py @@ -310,8 +310,7 @@ def post_start_basic( ``_ - :param acknowledge: whether the user has acknowledged acknowledge messages (default: - false) + :param acknowledge: Whether the user has acknowledged acknowledge messages :param master_timeout: Period to wait for a connection to the master node. :param timeout: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. @@ -358,8 +357,8 @@ def post_start_trial( """ .. raw:: html -

                                    Start a trial. - Start a 30-day trial, which gives access to all subscription features.

                                    +

                                    Start a trial.

                                    +

                                    Start a 30-day trial, which gives access to all subscription features.

                                    NOTE: You are allowed to start a trial only if your cluster has not already activated a trial for the current major product version. For example, if you have already activated a trial for v8.0, you cannot start a new trial until v9.0. You can, however, request an extended trial at https://www.elastic.co/trialextension.

                                    To check the status of your trial, use the get trial status API.

                                    @@ -367,10 +366,9 @@ def post_start_trial( ``_ - :param acknowledge: whether the user has acknowledged acknowledge messages (default: - false) + :param acknowledge: Whether the user has acknowledged acknowledge messages :param master_timeout: Period to wait for a connection to the master node. - :param type: The type of trial license to generate (default: "trial") + :param type: The type of trial license to generate """ __path_parts: t.Dict[str, str] = {} __path = "/_license/start_trial" diff --git a/elasticsearch/_sync/client/logstash.py b/elasticsearch/_sync/client/logstash.py index f8abefa14..1241a7d26 100644 --- a/elasticsearch/_sync/client/logstash.py +++ b/elasticsearch/_sync/client/logstash.py @@ -38,8 +38,8 @@ def delete_pipeline( """ .. raw:: html -

                                    Delete a Logstash pipeline. - Delete a pipeline that is used for Logstash Central Management. +

                                    Delete a Logstash pipeline.

                                    +

                                    Delete a pipeline that is used for Logstash Central Management. If the request succeeds, you receive an empty response with an appropriate status code.

                                    @@ -83,8 +83,8 @@ def get_pipeline( """ .. raw:: html -

                                    Get Logstash pipelines. - Get pipelines that are used for Logstash Central Management.

                                    +

                                    Get Logstash pipelines.

                                    +

                                    Get pipelines that are used for Logstash Central Management.

                                    ``_ @@ -141,7 +141,9 @@ def put_pipeline( ``_ - :param id: An identifier for the pipeline. + :param id: An identifier for the pipeline. Pipeline IDs must begin with a letter + or underscore and contain only letters, underscores, dashes, hyphens and + numbers. :param pipeline: """ if id in SKIP_IN_PATH: diff --git a/elasticsearch/_sync/client/migration.py b/elasticsearch/_sync/client/migration.py index 20ebb44fd..1303f90fc 100644 --- a/elasticsearch/_sync/client/migration.py +++ b/elasticsearch/_sync/client/migration.py @@ -38,8 +38,8 @@ def deprecations( """ .. raw:: html -

                                    Get deprecation information. - Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.

                                    +

                                    Get deprecation information.

                                    +

                                    Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.

                                    TIP: This APIs is designed for indirect use by the Upgrade Assistant. You are strongly recommended to use the Upgrade Assistant.

                                    @@ -87,8 +87,8 @@ def get_feature_upgrade_status( """ .. raw:: html -

                                    Get feature migration information. - Version upgrades sometimes require changes to how features store configuration information and data in system indices. +

                                    Get feature migration information.

                                    +

                                    Version upgrades sometimes require changes to how features store configuration information and data in system indices. Check which features need to be migrated and the status of any migrations that are in progress.

                                    TIP: This API is designed for indirect use by the Upgrade Assistant. You are strongly recommended to use the Upgrade Assistant.

                                    @@ -129,8 +129,8 @@ def post_feature_upgrade( """ .. raw:: html -

                                    Start the feature migration. - Version upgrades sometimes require changes to how features store configuration information and data in system indices. +

                                    Start the feature migration.

                                    +

                                    Version upgrades sometimes require changes to how features store configuration information and data in system indices. This API starts the automatic migration process.

                                    Some functionality might be temporarily unavailable during the migration process.

                                    TIP: The API is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.

                                    diff --git a/elasticsearch/_sync/client/ml.py b/elasticsearch/_sync/client/ml.py index 690197642..f519c99ea 100644 --- a/elasticsearch/_sync/client/ml.py +++ b/elasticsearch/_sync/client/ml.py @@ -20,7 +20,14 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + Visibility, + _availability_warning, + _quote, + _rewrite_parameters, +) class MlClient(NamespacedClient): @@ -1101,8 +1108,8 @@ def flush_job( """ .. raw:: html -

                                    Force buffered data to be processed. - The flush jobs API is only applicable when sending data for analysis using +

                                    Force buffered data to be processed.

                                    +

                                    The flush jobs API is only applicable when sending data for analysis using the post data API. Depending on the content of the buffer, then it might additionally calculate new results. Both flush and close operations are similar, however the flush is more efficient if you are expecting to send @@ -1269,8 +1276,8 @@ def get_buckets( """ .. raw:: html -

                                    Get anomaly detection job results for buckets. - The API presents a chronological view of the records, grouped by bucket.

                                    +

                                    Get anomaly detection job results for buckets.

                                    +

                                    The API presents a chronological view of the records, grouped by bucket.

                                    ``_ @@ -1598,8 +1605,8 @@ def get_data_frame_analytics( """ .. raw:: html -

                                    Get data frame analytics job configuration info. - You can get information for multiple data frame analytics jobs in a single +

                                    Get data frame analytics job configuration info.

                                    +

                                    You can get information for multiple data frame analytics jobs in a single API request by using a comma-separated list of data frame analytics jobs or a wildcard expression.

                                    @@ -1744,8 +1751,8 @@ def get_datafeed_stats( """ .. raw:: html -

                                    Get datafeed stats. - You can get statistics for multiple datafeeds in a single API request by +

                                    Get datafeed stats.

                                    +

                                    You can get statistics for multiple datafeeds in a single API request by using a comma-separated list of datafeeds or a wildcard expression. You can get statistics for all datafeeds by using _all, by specifying * as the <feed_id>, or by omitting the <feed_id>. If the datafeed is stopped, the @@ -1809,8 +1816,8 @@ def get_datafeeds( """ .. raw:: html -

                                    Get datafeeds configuration info. - You can get information for multiple datafeeds in a single API request by +

                                    Get datafeeds configuration info.

                                    +

                                    You can get information for multiple datafeeds in a single API request by using a comma-separated list of datafeeds or a wildcard expression. You can get information for all datafeeds by using _all, by specifying * as the <feed_id>, or by omitting the <feed_id>. @@ -1880,8 +1887,8 @@ def get_filters( """ .. raw:: html -

                                    Get filters. - You can get a single filter or all filters.

                                    +

                                    Get filters.

                                    +

                                    You can get a single filter or all filters.

                                    ``_ @@ -1946,8 +1953,8 @@ def get_influencers( """ .. raw:: html -

                                    Get anomaly detection job results for influencers. - Influencers are the entities that have contributed to, or are to blame for, +

                                    Get anomaly detection job results for influencers.

                                    +

                                    Influencers are the entities that have contributed to, or are to blame for, the anomalies. Influencer results are available only if an influencer_field_name is specified in the job configuration.

                                    @@ -2093,8 +2100,8 @@ def get_jobs( """ .. raw:: html -

                                    Get anomaly detection jobs configuration info. - You can get information for multiple anomaly detection jobs in a single API +

                                    Get anomaly detection jobs configuration info.

                                    +

                                    You can get information for multiple anomaly detection jobs in a single API request by using a group name, a comma-separated list of jobs, or a wildcard expression. You can get information for all anomaly detection jobs by using _all, by specifying * as the <job_id>, or by omitting the <job_id>.

                                    @@ -2161,8 +2168,8 @@ def get_memory_stats( """ .. raw:: html -

                                    Get machine learning memory usage info. - Get information about how machine learning jobs and trained models are using memory, +

                                    Get machine learning memory usage info.

                                    +

                                    Get information about how machine learning jobs and trained models are using memory, on each node, both within the JVM heap, and natively, outside of the JVM.

                                    @@ -2515,8 +2522,8 @@ def get_records( """ .. raw:: html -

                                    Get anomaly records for an anomaly detection job. - Records contain the detailed analytical results. They describe the anomalous +

                                    Get anomaly records for an anomaly detection job.

                                    +

                                    Records contain the detailed analytical results. They describe the anomalous activity that has been identified in the input data based on the detector configuration. There can be many anomaly records depending on the characteristics and size @@ -2708,8 +2715,8 @@ def get_trained_models_stats( """ .. raw:: html -

                                    Get trained models usage info. - You can get usage information for multiple trained +

                                    Get trained models usage info.

                                    +

                                    You can get usage information for multiple trained models in a single API request by using a comma-separated list of model IDs or a wildcard expression.

                                    @@ -2836,8 +2843,8 @@ def info( """ .. raw:: html -

                                    Get machine learning information. - Get defaults and limits used by machine learning. +

                                    Get machine learning information.

                                    +

                                    Get defaults and limits used by machine learning. This endpoint is designed to be used by a user interface that needs to fully understand machine learning configurations where some options are not specified, meaning that the defaults should be used. This endpoint may be @@ -3045,10 +3052,7 @@ def post_data( if reset_start is not None: __query["reset_start"] = reset_start __body = data if data is not None else body - __headers = { - "accept": "application/json", - "content-type": "application/x-ndjson", - } + __headers = {"accept": "application/json", "content-type": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", __path, @@ -3076,8 +3080,8 @@ def preview_data_frame_analytics( """ .. raw:: html -

                                    Preview features used by data frame analytics. - Preview the extracted features used by a data frame analytics config.

                                    +

                                    Preview features used by data frame analytics.

                                    +

                                    Preview the extracted features used by a data frame analytics config.

                                    ``_ @@ -3142,8 +3146,8 @@ def preview_datafeed( """ .. raw:: html -

                                    Preview a datafeed. - This API returns the first "page" of search results from a datafeed. +

                                    Preview a datafeed.

                                    +

                                    This API returns the first "page" of search results from a datafeed. You can preview an existing datafeed or provide configuration details for a datafeed and anomaly detection job in the API. The preview shows the structure of the data that will be passed to the anomaly detection engine. @@ -3364,8 +3368,8 @@ def put_data_frame_analytics( """ .. raw:: html -

                                    Create a data frame analytics job. - This API creates a data frame analytics job that performs an analysis on the +

                                    Create a data frame analytics job.

                                    +

                                    This API creates a data frame analytics job that performs an analysis on the source indices and stores the outcome in a destination index. By default, the query used in the source configuration is {"match_all": {}}.

                                    If the destination index does not exist, it is created automatically when you start the job.

                                    @@ -3545,8 +3549,8 @@ def put_datafeed( """ .. raw:: html -

                                    Create a datafeed. - Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job. +

                                    Create a datafeed.

                                    +

                                    Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job. You can associate only one datafeed with each anomaly detection job. The datafeed contains a query that runs at a defined interval (frequency). If you are concerned about delayed data, you can add a delay (query_delay') at each interval. By default, the datafeed uses the following query: {"match_all": {"boost": 1}}`.

                                    @@ -3714,8 +3718,8 @@ def put_filter( """ .. raw:: html -

                                    Create a filter. - A filter contains a list of strings. It can be used by one or more anomaly detection jobs. +

                                    Create a filter.

                                    +

                                    A filter contains a list of strings. It can be used by one or more anomaly detection jobs. Specifically, filters are referenced in the custom_rules property of detector configuration objects.

                                    @@ -4019,8 +4023,8 @@ def put_trained_model( """ .. raw:: html -

                                    Create a trained model. - Enable you to supply a trained model that is not created by data frame analytics.

                                    +

                                    Create a trained model.

                                    +

                                    Enable you to supply a trained model that is not created by data frame analytics.

                                    ``_ @@ -4125,8 +4129,8 @@ def put_trained_model_alias( """ .. raw:: html -

                                    Create or update a trained model alias. - A trained model alias is a logical name used to reference a single trained +

                                    Create or update a trained model alias.

                                    +

                                    A trained model alias is a logical name used to reference a single trained model. You can use aliases instead of trained model identifiers to make it easier to reference your models. For example, you can use aliases in inference @@ -4282,8 +4286,8 @@ def put_trained_model_vocabulary( """ .. raw:: html -

                                    Create a trained model vocabulary. - This API is supported only for natural language processing (NLP) models. +

                                    Create a trained model vocabulary.

                                    +

                                    This API is supported only for natural language processing (NLP) models. The vocabulary is stored in the index as described in inference_config.*.vocabulary of the trained model definition.

                                    @@ -4343,8 +4347,8 @@ def reset_job( """ .. raw:: html -

                                    Reset an anomaly detection job. - All model state and results are deleted. The job is ready to start over as if +

                                    Reset an anomaly detection job.

                                    +

                                    All model state and results are deleted. The job is ready to start over as if it had just been created. It is not currently possible to reset multiple jobs using wildcards or a comma separated list.

                                    @@ -4404,8 +4408,8 @@ def revert_model_snapshot( """ .. raw:: html -

                                    Revert to a snapshot. - The machine learning features react quickly to anomalous input, learning new +

                                    Revert to a snapshot.

                                    +

                                    The machine learning features react quickly to anomalous input, learning new behaviors in data. Highly anomalous input increases the variance in the models whilst the system learns whether this is a new step-change in behavior or a one-off event. In the case where this anomalous input is known to be a @@ -4474,8 +4478,8 @@ def set_upgrade_mode( """ .. raw:: html -

                                    Set upgrade_mode for ML indices. - Sets a cluster wide upgrade_mode setting that prepares machine learning +

                                    Set upgrade_mode for ML indices.

                                    +

                                    Sets a cluster wide upgrade_mode setting that prepares machine learning indices for an upgrade. When upgrading your cluster, in some circumstances you must restart your nodes and reindex your machine learning indices. In those circumstances, @@ -4521,7 +4525,9 @@ def set_upgrade_mode( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_fields=("timeout",), + ) def start_data_frame_analytics( self, *, @@ -4531,12 +4537,13 @@ def start_data_frame_analytics( human: t.Optional[bool] = 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]: """ .. raw:: html -

                                    Start a data frame analytics job. - A data frame analytics job can be started and stopped multiple times +

                                    Start a data frame analytics job.

                                    +

                                    A data frame analytics job can be started and stopped multiple times throughout its lifecycle. If the destination index does not exist, it is created automatically the first time you start the data frame analytics job. The @@ -4562,6 +4569,7 @@ def start_data_frame_analytics( __path_parts: t.Dict[str, str] = {"id": _quote(id)} __path = f'/_ml/data_frame/analytics/{__path_parts["id"]}/_start' __query: t.Dict[str, t.Any] = {} + __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 filter_path is not None: @@ -4570,14 +4578,20 @@ def start_data_frame_analytics( __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout + if not __body: + 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" return self.perform_request( # type: ignore[return-value] "POST", __path, params=__query, headers=__headers, + body=__body, endpoint_id="ml.start_data_frame_analytics", path_parts=__path_parts, ) @@ -4685,8 +4699,8 @@ def start_trained_model_deployment( """ .. raw:: html -

                                    Start a trained model deployment. - It allocates the model to every machine learning node.

                                    +

                                    Start a trained model deployment.

                                    +

                                    It allocates the model to every machine learning node.

                                    ``_ @@ -4707,7 +4721,7 @@ def start_trained_model_deployment( is greater than the number of hardware threads it will automatically be changed to a value less than the number of hardware threads. If adaptive_allocations is enabled, do not set this value, because it’s automatically set. - :param priority: The deployment priority. + :param priority: The deployment priority :param queue_capacity: Specifies the number of inference requests that are allowed in the queue. After the number of requests exceeds this value, new requests are rejected with a 429 error. @@ -4769,7 +4783,9 @@ def start_trained_model_deployment( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_fields=("allow_no_match", "force", "timeout"), + ) def stop_data_frame_analytics( self, *, @@ -4781,12 +4797,13 @@ def stop_data_frame_analytics( human: t.Optional[bool] = 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]: """ .. raw:: html -

                                    Stop data frame analytics jobs. - A data frame analytics job can be started and stopped multiple times +

                                    Stop data frame analytics jobs.

                                    +

                                    A data frame analytics job can be started and stopped multiple times throughout its lifecycle.

                                    @@ -4812,26 +4829,33 @@ def stop_data_frame_analytics( __path_parts: t.Dict[str, str] = {"id": _quote(id)} __path = f'/_ml/data_frame/analytics/{__path_parts["id"]}/_stop' __query: t.Dict[str, t.Any] = {} - if allow_no_match is not None: - __query["allow_no_match"] = allow_no_match + __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 filter_path is not None: __query["filter_path"] = filter_path - if force is not None: - __query["force"] = force if human is not None: __query["human"] = human if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout + if not __body: + if allow_no_match is not None: + __body["allow_no_match"] = allow_no_match + if force is not None: + __body["force"] = force + 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" return self.perform_request( # type: ignore[return-value] "POST", __path, params=__query, headers=__headers, + body=__body, endpoint_id="ml.stop_data_frame_analytics", path_parts=__path_parts, ) @@ -4855,8 +4879,8 @@ def stop_datafeed( """ .. raw:: html -

                                    Stop datafeeds. - A datafeed that is stopped ceases to retrieve data from Elasticsearch. A datafeed can be started and stopped +

                                    Stop datafeeds.

                                    +

                                    A datafeed that is stopped ceases to retrieve data from Elasticsearch. A datafeed can be started and stopped multiple times throughout its lifecycle.

                                    @@ -4907,7 +4931,9 @@ def stop_datafeed( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_fields=("allow_no_match", "force", "id"), + ) def stop_trained_model_deployment( self, *, @@ -4917,7 +4943,9 @@ def stop_trained_model_deployment( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, force: t.Optional[bool] = None, human: t.Optional[bool] = None, + id: t.Optional[str] = None, pretty: t.Optional[bool] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html @@ -4937,30 +4965,40 @@ def stop_trained_model_deployment( no matches or only partial matches. :param force: Forcefully stops the deployment, even if it is used by ingest pipelines. You can't use these pipelines until you restart the model deployment. + :param id: If provided, must be the same identifier as in the path. """ if model_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'model_id'") __path_parts: t.Dict[str, str] = {"model_id": _quote(model_id)} __path = f'/_ml/trained_models/{__path_parts["model_id"]}/deployment/_stop' __query: t.Dict[str, t.Any] = {} - if allow_no_match is not None: - __query["allow_no_match"] = allow_no_match + __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 filter_path is not None: __query["filter_path"] = filter_path - if force is not None: - __query["force"] = force if human is not None: __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if not __body: + if allow_no_match is not None: + __body["allow_no_match"] = allow_no_match + if force is not None: + __body["force"] = force + if id is not None: + __body["id"] = id + if not __body: + __body = None # type: ignore[assignment] __headers = {"accept": "application/json"} + if __body is not None: + __headers["content-type"] = "application/json" return self.perform_request( # type: ignore[return-value] "POST", __path, params=__query, headers=__headers, + body=__body, endpoint_id="ml.stop_trained_model_deployment", path_parts=__path_parts, ) @@ -5101,8 +5139,8 @@ def update_datafeed( """ .. raw:: html -

                                    Update a datafeed. - You must stop and start the datafeed for the changes to be applied. +

                                    Update a datafeed.

                                    +

                                    You must stop and start the datafeed for the changes to be applied. When Elasticsearch security features are enabled, your datafeed remembers which roles the user who updated it had at the time of the update and runs the query using those same roles. If you provide secondary authorization headers, those credentials are used instead.

                                    @@ -5265,8 +5303,8 @@ def update_filter( """ .. raw:: html -

                                    Update a filter. - Updates the description of a filter, adds items, or removes items from the list.

                                    +

                                    Update a filter.

                                    +

                                    Updates the description of a filter, adds items, or removes items from the list.

                                    ``_ @@ -5359,8 +5397,8 @@ def update_job( """ .. raw:: html -

                                    Update an anomaly detection job. - Updates certain properties of an anomaly detection job.

                                    +

                                    Update an anomaly detection job.

                                    +

                                    Updates certain properties of an anomaly detection job.

                                    ``_ @@ -5491,8 +5529,8 @@ def update_model_snapshot( """ .. raw:: html -

                                    Update a snapshot. - Updates certain properties of a snapshot.

                                    +

                                    Update a snapshot.

                                    +

                                    Updates certain properties of a snapshot.

                                    ``_ @@ -5625,8 +5663,8 @@ def upgrade_job_snapshot( """ .. raw:: html -

                                    Upgrade a snapshot. - Upgrade an anomaly detection model snapshot to the latest major version. +

                                    Upgrade a snapshot.

                                    +

                                    Upgrade an anomaly detection model snapshot to the latest major version. Over time, older snapshot formats are deprecated and removed. Anomaly detection jobs support only snapshots that are from the current or previous major version. @@ -5692,6 +5730,7 @@ def upgrade_job_snapshot( "results_index_name", ), ) + @_availability_warning(Stability.STABLE, Visibility.PRIVATE) def validate( self, *, @@ -5716,7 +5755,7 @@ def validate(

                                    Validate an anomaly detection job.

                                    - ``_ + ``_ :param analysis_config: :param analysis_limits: @@ -5773,6 +5812,7 @@ def validate( @_rewrite_parameters( body_name="detector", ) + @_availability_warning(Stability.STABLE, Visibility.PRIVATE) def validate_detector( self, *, diff --git a/elasticsearch/_sync/client/monitoring.py b/elasticsearch/_sync/client/monitoring.py index 59cee2235..9973ef7c6 100644 --- a/elasticsearch/_sync/client/monitoring.py +++ b/elasticsearch/_sync/client/monitoring.py @@ -20,7 +20,7 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import _rewrite_parameters +from .utils import Stability, Visibility, _availability_warning, _rewrite_parameters class MonitoringClient(NamespacedClient): @@ -28,6 +28,7 @@ class MonitoringClient(NamespacedClient): @_rewrite_parameters( body_name="operations", ) + @_availability_warning(Stability.STABLE, Visibility.PRIVATE) def bulk( self, *, @@ -44,8 +45,8 @@ def bulk( """ .. raw:: html -

                                    Send monitoring data. - This API is used by the monitoring features to send monitoring data.

                                    +

                                    Send monitoring data.

                                    +

                                    This API is used by the monitoring features to send monitoring data.

                                    ``_ diff --git a/elasticsearch/_sync/client/nodes.py b/elasticsearch/_sync/client/nodes.py index ef6c67b10..54de3868f 100644 --- a/elasticsearch/_sync/client/nodes.py +++ b/elasticsearch/_sync/client/nodes.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class NodesClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def clear_repositories_metering_archive( self, *, @@ -46,8 +46,8 @@ def clear_repositories_metering_archive( """ .. raw:: html -

                                    Clear the archived repositories metering. - Clear the archived repositories metering information in the cluster.

                                    +

                                    Clear the archived repositories metering.

                                    +

                                    Clear the archived repositories metering information in the cluster.

                                    ``_ @@ -86,7 +86,7 @@ def clear_repositories_metering_archive( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def get_repositories_metering_info( self, *, @@ -99,8 +99,8 @@ def get_repositories_metering_info( """ .. raw:: html -

                                    Get cluster repositories metering. - Get repositories metering information for a cluster. +

                                    Get cluster repositories metering.

                                    +

                                    Get repositories metering information for a cluster. This API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time. Additionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.

                                    @@ -157,8 +157,8 @@ def hot_threads( """ .. raw:: html -

                                    Get the hot threads for nodes. - Get a breakdown of the hot threads on each selected node in the cluster. +

                                    Get the hot threads for nodes.

                                    +

                                    Get a breakdown of the hot threads on each selected node in the cluster. The output is plain text with a breakdown of the top hot threads for each node.

                                    @@ -169,7 +169,7 @@ def hot_threads( select, or to get a task from an empty queue) are filtered out. :param interval: The interval to do the second sampling of threads. :param snapshots: Number of samples of thread stacktrace. - :param sort: The sort order for 'cpu' type (default: total) + :param sort: The sort order for 'cpu' type :param threads: Specifies the number of hot threads to provide information for. :param timeout: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. @@ -378,8 +378,8 @@ def stats( """ .. raw:: html -

                                    Get node statistics. - Get statistics for nodes in a cluster. +

                                    Get node statistics.

                                    +

                                    Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.

                                    @@ -387,7 +387,7 @@ def stats( :param node_id: Comma-separated list of node IDs or names used to limit returned information. - :param metric: Limit the information returned to the specified metrics + :param metric: :param index_metric: Limit the information returned for indices metric to the specific index metrics. It can be used only if indices (or all) metric is specified. @@ -404,8 +404,8 @@ def stats( are requested). :param include_unloaded_segments: If `true`, the response includes information from segments that are not loaded into memory. - :param level: Indicates whether statistics are aggregated at the cluster, index, - or shard level. + :param level: Indicates whether statistics are aggregated at the node, indices, + or shards level. :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 types: A comma-separated list of document types for the indexing index @@ -501,8 +501,8 @@ def usage( ``_ :param node_id: A comma-separated list of node IDs or names to limit the returned - information; use `_local` to return information from the node you're connecting - to, leave empty to get information from all nodes + information. Use `_local` to return information from the node you're connecting + to, leave empty to get information from all nodes. :param metric: Limits the information returned to the specific metrics. A comma-separated list of the following options: `_all`, `rest_actions`. :param timeout: Period to wait for a response. If no response is received before diff --git a/elasticsearch/_sync/client/query_rules.py b/elasticsearch/_sync/client/query_rules.py index 351c4dd80..9d5298da5 100644 --- a/elasticsearch/_sync/client/query_rules.py +++ b/elasticsearch/_sync/client/query_rules.py @@ -39,8 +39,8 @@ def delete_rule( """ .. raw:: html -

                                    Delete a query rule. - Delete a query rule within a query ruleset. +

                                    Delete a query rule.

                                    +

                                    Delete a query rule within a query ruleset. This is a destructive action that is only recoverable by re-adding the same rule with the create or update query rule API.

                                    @@ -92,8 +92,8 @@ def delete_ruleset( """ .. raw:: html -

                                    Delete a query ruleset. - Remove a query ruleset and its associated data. +

                                    Delete a query ruleset.

                                    +

                                    Remove a query ruleset and its associated data. This is a destructive action that is not recoverable.

                                    @@ -138,8 +138,8 @@ def get_rule( """ .. raw:: html -

                                    Get a query rule. - Get details about a query rule within a query ruleset.

                                    +

                                    Get a query rule.

                                    +

                                    Get details about a query rule within a query ruleset.

                                    ``_ @@ -190,8 +190,8 @@ def get_ruleset( """ .. raw:: html -

                                    Get a query ruleset. - Get details about a query ruleset.

                                    +

                                    Get a query ruleset.

                                    +

                                    Get details about a query ruleset.

                                    ``_ @@ -237,8 +237,8 @@ def list_rulesets( """ .. raw:: html -

                                    Get all query rulesets. - Get summarized information about the query rulesets.

                                    +

                                    Get all query rulesets.

                                    +

                                    Get summarized information about the query rulesets.

                                    ``_ @@ -294,8 +294,8 @@ def put_rule( """ .. raw:: html -

                                    Create or update a query rule. - Create or update a query rule within a query ruleset.

                                    +

                                    Create or update a query rule.

                                    +

                                    Create or update a query rule within a query ruleset.

                                    IMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. @@ -380,8 +380,8 @@ def put_ruleset( """ .. raw:: html -

                                    Create or update a query ruleset. - There is a limit of 100 rules per ruleset. +

                                    Create or update a query ruleset.

                                    +

                                    There is a limit of 100 rules per ruleset. This limit can be increased by using the xpack.applications.rules.max_rules_per_ruleset cluster setting.

                                    IMPORTANT: Due to limitations within pinned queries, you can only select documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. @@ -442,8 +442,8 @@ def test( """ .. raw:: html -

                                    Test a query ruleset. - Evaluate match criteria against a query ruleset to identify the rules that would match that criteria.

                                    +

                                    Test a query ruleset.

                                    +

                                    Evaluate match criteria against a query ruleset to identify the rules that would match that criteria.

                                    ``_ diff --git a/elasticsearch/_sync/client/rollup.py b/elasticsearch/_sync/client/rollup.py index 8f098e2ff..5aef61411 100644 --- a/elasticsearch/_sync/client/rollup.py +++ b/elasticsearch/_sync/client/rollup.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class RollupClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def delete_job( self, *, @@ -95,7 +95,7 @@ def delete_job( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def get_jobs( self, *, @@ -108,8 +108,8 @@ def get_jobs( """ .. raw:: html -

                                    Get rollup job information. - Get the configuration, stats, and status of rollup jobs.

                                    +

                                    Get rollup job information.

                                    +

                                    Get the configuration, stats, and status of rollup jobs.

                                    NOTE: This API returns only active (both STARTED and STOPPED) jobs. If a job was created, ran for a while, then was deleted, the API does not return any details about it. For details about a historical rollup job, the rollup capabilities API may be more useful.

                                    @@ -147,7 +147,7 @@ def get_jobs( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def get_rollup_caps( self, *, @@ -160,8 +160,8 @@ def get_rollup_caps( """ .. raw:: html -

                                    Get the rollup job capabilities. - Get the capabilities of any rollup jobs that have been configured for a specific index or index pattern.

                                    +

                                    Get the rollup job capabilities.

                                    +

                                    Get the capabilities of any rollup jobs that have been configured for a specific index or index pattern.

                                    This API is useful because a rollup job is often configured to rollup only a subset of fields from the source index. Furthermore, only certain aggregations can be configured for various fields, leading to a limited subset of functionality depending on that configuration. This API enables you to inspect an index and determine:

                                    @@ -203,7 +203,7 @@ def get_rollup_caps( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def get_rollup_index_caps( self, *, @@ -216,8 +216,8 @@ def get_rollup_index_caps( """ .. raw:: html -

                                    Get the rollup index capabilities. - Get the rollup capabilities of all jobs inside of a rollup index. +

                                    Get the rollup index capabilities.

                                    +

                                    Get the rollup capabilities of all jobs inside of a rollup index. A single rollup index may store the data for multiple rollup jobs and may have a variety of capabilities depending on those jobs. This API enables you to determine:

                                    • What jobs are stored in an index (or indices specified via a pattern)?
                                    • @@ -266,7 +266,7 @@ def get_rollup_index_caps( ), ignore_deprecated_options={"headers"}, ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def put_job( self, *, @@ -392,7 +392,7 @@ def put_job( @_rewrite_parameters( body_fields=("aggregations", "aggs", "query", "size"), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def rollup_search( self, *, @@ -412,8 +412,8 @@ def rollup_search( """ .. raw:: html -

                                      Search rolled-up data. - The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data. +

                                      Search rolled-up data.

                                      +

                                      The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data. It rewrites standard Query DSL into a format that matches the rollup documents then takes the response and rewrites it back to what a client would expect given the original query.

                                      The request body supports a subset of features from the regular search API. The following functionality is not available:

                                      @@ -482,7 +482,7 @@ def rollup_search( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def start_job( self, *, @@ -495,8 +495,8 @@ def start_job( """ .. raw:: html -

                                      Start rollup jobs. - If you try to start a job that does not exist, an exception occurs. +

                                      Start rollup jobs.

                                      +

                                      If you try to start a job that does not exist, an exception occurs. If you try to start a job that is already started, nothing happens.

                                      @@ -528,7 +528,7 @@ def start_job( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def stop_job( self, *, @@ -543,8 +543,8 @@ def stop_job( """ .. raw:: html -

                                      Stop rollup jobs. - If you try to stop a job that does not exist, an exception occurs. +

                                      Stop rollup jobs.

                                      +

                                      If you try to stop a job that does not exist, an exception occurs. If you try to stop a job that is already stopped, nothing happens.

                                      Since only a stopped job can be deleted, it can be useful to block the API until the indexer has fully stopped. This is accomplished with the wait_for_completion query parameter, and optionally a timeout. For example:

                                      diff --git a/elasticsearch/_sync/client/search_application.py b/elasticsearch/_sync/client/search_application.py index b81980475..10961594d 100644 --- a/elasticsearch/_sync/client/search_application.py +++ b/elasticsearch/_sync/client/search_application.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class SearchApplicationClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def delete( self, *, @@ -77,7 +77,7 @@ def delete( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def delete_behavioral_analytics( self, *, @@ -90,8 +90,8 @@ def delete_behavioral_analytics( """ .. raw:: html -

                                      Delete a behavioral analytics collection. - The associated data stream is also deleted.

                                      +

                                      Delete a behavioral analytics collection.

                                      +

                                      The associated data stream is also deleted.

                                      ``_ @@ -122,7 +122,7 @@ def delete_behavioral_analytics( ) @_rewrite_parameters() - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def get( self, *, @@ -166,7 +166,7 @@ def get( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def get_behavioral_analytics( self, *, @@ -215,7 +215,7 @@ def get_behavioral_analytics( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def list( self, *, @@ -230,8 +230,8 @@ def list( """ .. raw:: html -

                                      Get search applications. - Get information about search applications.

                                      +

                                      Get search applications.

                                      +

                                      Get information about search applications.

                                      ``_ @@ -270,7 +270,7 @@ def list( @_rewrite_parameters( body_name="payload", ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def post_behavioral_analytics_event( self, *, @@ -338,7 +338,7 @@ def post_behavioral_analytics_event( @_rewrite_parameters( body_name="search_application", ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def put( self, *, @@ -398,7 +398,7 @@ def put( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def put_behavioral_analytics( self, *, @@ -445,7 +445,7 @@ def put_behavioral_analytics( body_fields=("params",), ignore_deprecated_options={"params"}, ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def render_query( self, *, @@ -460,8 +460,8 @@ def render_query( """ .. raw:: html -

                                      Render a search application query. - Generate an Elasticsearch query using the specified query parameters and the search template associated with the search application or a default template if none is specified. +

                                      Render a search application query.

                                      +

                                      Generate an Elasticsearch query using the specified query parameters and the search template associated with the search application or a default template if none is specified. If a parameter used in the search template is not specified in params, the parameter's default value will be used. The API returns the specific Elasticsearch query that would be generated and run by calling the search application search API.

                                      You must have read privileges on the backing alias of the search application.

                                      @@ -510,7 +510,7 @@ def render_query( body_fields=("params",), ignore_deprecated_options={"params"}, ) - @_stability_warning(Stability.BETA) + @_availability_warning(Stability.BETA) def search( self, *, @@ -526,8 +526,8 @@ def search( """ .. raw:: html -

                                      Run a search application search. - Generate and run an Elasticsearch query that uses the specified query parameteter and the search template associated with the search application or default template. +

                                      Run a search application search.

                                      +

                                      Generate and run an Elasticsearch query that uses the specified query parameteter and the search template associated with the search application or default template. Unspecified template parameters are assigned their default values if applicable.

                                      diff --git a/elasticsearch/_sync/client/searchable_snapshots.py b/elasticsearch/_sync/client/searchable_snapshots.py index 2160988c0..baa48ae6c 100644 --- a/elasticsearch/_sync/client/searchable_snapshots.py +++ b/elasticsearch/_sync/client/searchable_snapshots.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class SearchableSnapshotsClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def cache_stats( self, *, @@ -46,8 +46,8 @@ def cache_stats( """ .. raw:: html -

                                      Get cache statistics. - Get statistics about the shared cache for partially mounted indices.

                                      +

                                      Get cache statistics.

                                      +

                                      Get statistics about the shared cache for partially mounted indices.

                                      ``_ @@ -84,7 +84,7 @@ def cache_stats( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def clear_cache( self, *, @@ -107,8 +107,8 @@ def clear_cache( """ .. raw:: html -

                                      Clear the cache. - Clear indices and data streams from the shared cache for partially mounted indices.

                                      +

                                      Clear the cache.

                                      +

                                      Clear indices and data streams from the shared cache for partially mounted indices.

                                      ``_ @@ -119,7 +119,7 @@ def clear_cache( into no concrete indices. (This includes `_all` string or when no indices have been specified) :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. + that are open, closed or both :param ignore_unavailable: Whether specified concrete indices should be ignored when unavailable (missing or closed) """ @@ -184,8 +184,8 @@ def mount( """ .. raw:: html -

                                      Mount a snapshot. - Mount a snapshot as a searchable snapshot index. +

                                      Mount a snapshot.

                                      +

                                      Mount a snapshot as a searchable snapshot index. Do not use this API for snapshots managed by index lifecycle management (ILM). Manually mounting ILM-managed snapshots can interfere with ILM processes.

                                      diff --git a/elasticsearch/_sync/client/security.py b/elasticsearch/_sync/client/security.py index 2672a7951..80e441c32 100644 --- a/elasticsearch/_sync/client/security.py +++ b/elasticsearch/_sync/client/security.py @@ -288,8 +288,8 @@ def bulk_update_api_keys( """ .. raw:: html -

                                      Bulk update API keys. - Update the attributes for multiple API keys.

                                      +

                                      Bulk update API keys.

                                      +

                                      Update the attributes for multiple API keys.

                                      IMPORTANT: It is not possible to use an API key as the authentication credential for this API. To update API keys, the owner user's credentials are required.

                                      This API is similar to the update API key API but enables you to apply the same update to multiple API keys in one API call. This operation can greatly improve performance over making individual updates.

                                      It is not possible to update expired or invalidated API keys.

                                      @@ -892,8 +892,8 @@ def create_service_token( Token names must be unique in the context of the associated service account. They must also be globally unique with their fully qualified names, which are comprised of the service account principal and token name, such as `//`. - :param refresh: If `true` then refresh the affected shards to make this operation - visible to search, if `wait_for` (the default) then wait for a refresh to + :param refresh: If `true` (the default) then refresh 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` then do nothing with refreshes. """ if namespace in SKIP_IN_PATH: @@ -1208,8 +1208,8 @@ def delete_service_token( :param namespace: The namespace, which is a top-level grouping of service accounts. :param service: The service name. :param name: The name of the service account token. - :param refresh: If `true` then refresh the affected shards to make this operation - visible to search, if `wait_for` (the default) then wait for a refresh to + :param refresh: If `true` (the default) then refresh 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` then do nothing with refreshes. """ if namespace in SKIP_IN_PATH: @@ -3711,7 +3711,8 @@ def query_role( :param size: The number of hits to return. It 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` parameter. - :param sort: The sort definition. You can sort on `username`, `roles`, or `enabled`. + :param sort: The sort definition. You can sort on `name`, `description`, `metadata`, + `applications.application`, `applications.privileges`, and `applications.resources`. In addition, sort can also be applied to the `_doc` field to sort by index order. """ diff --git a/elasticsearch/_sync/client/shutdown.py b/elasticsearch/_sync/client/shutdown.py index d7ec41511..fc3e30cf2 100644 --- a/elasticsearch/_sync/client/shutdown.py +++ b/elasticsearch/_sync/client/shutdown.py @@ -20,7 +20,11 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + _quote, + _rewrite_parameters, +) class ShutdownClient(NamespacedClient): @@ -33,19 +37,15 @@ def delete_node( 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["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = 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["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = None, + timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ .. raw:: html -

                                      Cancel node shutdown preparations. - Remove a node from the shutdown list so it can resume normal operations. +

                                      Cancel node shutdown preparations.

                                      +

                                      Remove a node from the shutdown list so it can resume normal operations. You must explicitly clear the shutdown request when a node rejoins the cluster or when a node has permanently left the cluster. Shutdown requests are never removed automatically by Elasticsearch.

                                      NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. @@ -97,9 +97,7 @@ def get_node( 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["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -114,7 +112,8 @@ def get_node( ``_ - :param node_id: Which node for which to retrieve the shutdown status + :param node_id: Comma-separated list of nodes for which to retrieve the shutdown + status :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. @@ -162,14 +161,10 @@ def put_node( 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["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, target_node_name: t.Optional[str] = None, - timeout: 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, body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ diff --git a/elasticsearch/_sync/client/simulate.py b/elasticsearch/_sync/client/simulate.py index 5f22ae433..6ce875584 100644 --- a/elasticsearch/_sync/client/simulate.py +++ b/elasticsearch/_sync/client/simulate.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -40,7 +40,7 @@ class SimulateClient(NamespacedClient): "pipeline_substitutions", ), ) - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def ingest( self, *, @@ -66,8 +66,8 @@ def ingest( """ .. raw:: html -

                                      Simulate data ingestion. - Run ingest pipelines against a set of provided documents, optionally with substitute pipeline definitions, to simulate ingesting data into an index.

                                      +

                                      Simulate data ingestion.

                                      +

                                      Run ingest pipelines against a set of provided documents, optionally with substitute pipeline definitions, to simulate ingesting data into an index.

                                      This API is meant to be used for troubleshooting or pipeline development, as it does not actually index any data into Elasticsearch.

                                      The API runs the default and final pipeline for that index against a set of documents provided in the body of the request. If a pipeline contains a reroute processor, it follows that reroute processor to the new index, running that index's pipelines as well the same way that a non-simulated ingest would. diff --git a/elasticsearch/_sync/client/slm.py b/elasticsearch/_sync/client/slm.py index 9b701de80..e4e270b2f 100644 --- a/elasticsearch/_sync/client/slm.py +++ b/elasticsearch/_sync/client/slm.py @@ -40,8 +40,8 @@ def delete_lifecycle( """ .. raw:: html -

                                      Delete a policy. - Delete a snapshot lifecycle policy definition. +

                                      Delete a policy.

                                      +

                                      Delete a snapshot lifecycle policy definition. This operation prevents any future snapshots from being taken but does not cancel in-progress snapshots or remove previously-taken snapshots.

                                      @@ -96,8 +96,8 @@ def execute_lifecycle( """ .. raw:: html -

                                      Run a policy. - Immediately create a snapshot according to the snapshot lifecycle policy without waiting for the scheduled time. +

                                      Run a policy.

                                      +

                                      Immediately create a snapshot according to the snapshot lifecycle policy without waiting for the scheduled time. The snapshot policy is normally applied according to its schedule, but you might want to manually run a policy before performing an upgrade or other maintenance.

                                      @@ -151,8 +151,8 @@ def execute_retention( """ .. raw:: html -

                                      Run a retention policy. - Manually apply the retention policy to force immediate removal of snapshots that are expired according to the snapshot lifecycle policy retention rules. +

                                      Run a retention policy.

                                      +

                                      Manually apply the retention policy to force immediate removal of snapshots that are expired according to the snapshot lifecycle policy retention rules. The retention policy is normally applied according to its schedule.

                                      @@ -204,13 +204,13 @@ def get_lifecycle( """ .. raw:: html -

                                      Get policy information. - Get snapshot lifecycle policy definitions and information about the latest snapshot attempts.

                                      +

                                      Get policy information.

                                      +

                                      Get snapshot lifecycle policy definitions and information about the latest snapshot attempts.

                                      ``_ - :param policy_id: Comma-separated list of snapshot lifecycle policies to retrieve + :param policy_id: A comma-separated list of snapshot lifecycle policy identifiers. :param master_timeout: The 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. @@ -261,8 +261,8 @@ def get_stats( """ .. raw:: html -

                                      Get snapshot lifecycle management statistics. - Get global and policy-level statistics about actions taken by snapshot lifecycle management.

                                      +

                                      Get snapshot lifecycle management statistics.

                                      +

                                      Get global and policy-level statistics about actions taken by snapshot lifecycle management.

                                      ``_ @@ -373,8 +373,8 @@ def put_lifecycle( """ .. raw:: html -

                                      Create or update a policy. - Create or update a snapshot lifecycle policy. +

                                      Create or update a policy.

                                      +

                                      Create or update a snapshot lifecycle policy. If the policy already exists, this request increments the policy version. Only the latest version of a policy is stored.

                                      @@ -431,11 +431,7 @@ def put_lifecycle( __body["retention"] = retention if schedule is not None: __body["schedule"] = schedule - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -460,8 +456,8 @@ def start( """ .. raw:: html -

                                      Start snapshot lifecycle management. - Snapshot lifecycle management (SLM) starts automatically when a cluster is formed. +

                                      Start snapshot lifecycle management.

                                      +

                                      Snapshot lifecycle management (SLM) starts automatically when a cluster is formed. Manually starting SLM is necessary only if it has been stopped using the stop SLM API.

                                      @@ -514,8 +510,8 @@ def stop( """ .. raw:: html -

                                      Stop snapshot lifecycle management. - Stop all snapshot lifecycle management (SLM) operations and the SLM plugin. +

                                      Stop snapshot lifecycle management.

                                      +

                                      Stop all snapshot lifecycle management (SLM) operations and the SLM plugin. This API is useful when you are performing maintenance on a cluster and need to prevent SLM from performing any actions on your data streams or indices. Stopping SLM does not stop any snapshots that are in progress. You can manually trigger snapshots with the run snapshot lifecycle policy API even if SLM is stopped.

                                      diff --git a/elasticsearch/_sync/client/snapshot.py b/elasticsearch/_sync/client/snapshot.py index 09691ce8e..faf8e3181 100644 --- a/elasticsearch/_sync/client/snapshot.py +++ b/elasticsearch/_sync/client/snapshot.py @@ -23,9 +23,9 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) @@ -46,8 +46,8 @@ def cleanup_repository( """ .. raw:: html -

                                      Clean up the snapshot repository. - Trigger the review of the contents of a snapshot repository and delete any stale data not referenced by existing snapshots.

                                      +

                                      Clean up the snapshot repository.

                                      +

                                      Trigger the review of the contents of a snapshot repository and delete any stale data not referenced by existing snapshots.

                                      ``_ @@ -110,8 +110,8 @@ def clone( """ .. raw:: html -

                                      Clone a snapshot. - Clone part of all of a snapshot into another snapshot in the same repository.

                                      +

                                      Clone a snapshot.

                                      +

                                      Clone part of all of a snapshot into another snapshot in the same repository.

                                      ``_ @@ -207,8 +207,8 @@ def create( """ .. raw:: html -

                                      Create a snapshot. - Take a snapshot of a cluster or of data streams and indices.

                                      +

                                      Create a snapshot.

                                      +

                                      Take a snapshot of a cluster or of data streams and indices.

                                      ``_ @@ -330,8 +330,8 @@ def create_repository( """ .. raw:: html -

                                      Create or update a snapshot repository. - IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters. +

                                      Create or update a snapshot repository.

                                      +

                                      IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters. To register a snapshot repository, the cluster's global metadata must be writeable. Ensure there are no cluster blocks (for example, cluster.blocks.read_only and clsuter.blocks.read_only_allow_delete settings) that prevent write access.

                                      Several options for this API can be specified using a query parameter or a request body parameter. @@ -470,8 +470,8 @@ def delete_repository( """ .. raw:: html -

                                      Delete snapshot repositories. - When a repository is unregistered, Elasticsearch removes only the reference to the location where the repository is storing the snapshots. +

                                      Delete snapshot repositories.

                                      +

                                      When a repository is unregistered, Elasticsearch removes only the reference to the location where the repository is storing the snapshots. The snapshots themselves are left untouched and in place.

                                      @@ -950,7 +950,7 @@ def repository_analyze( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def repository_verify_integrity( self, *, @@ -971,8 +971,8 @@ def repository_verify_integrity( """ .. raw:: html -

                                      Verify the repository integrity. - Verify the integrity of the contents of a snapshot repository.

                                      +

                                      Verify the repository integrity.

                                      +

                                      Verify the integrity of the contents of a snapshot repository.

                                      This API enables you to perform a comprehensive check of the contents of a repository, looking for any anomalies in its data or metadata which might prevent you from restoring snapshots from the repository or which might cause future snapshot create or delete operations to fail.

                                      If you suspect the integrity of the contents of one of your snapshot repositories, cease all write activity to this repository immediately, set its read_only option to true, and use this API to verify its integrity. Until you do so:

                                      @@ -1110,8 +1110,8 @@ def restore( """ .. raw:: html -

                                      Restore a snapshot. - Restore a snapshot of a cluster or data streams and indices.

                                      +

                                      Restore a snapshot.

                                      +

                                      Restore a snapshot of a cluster or data streams and indices.

                                      You can restore a snapshot only to a running cluster with an elected master node. The snapshot repository must be registered and available to the cluster. The snapshot and cluster versions must be compatible.

                                      @@ -1259,18 +1259,13 @@ def status( """ .. raw:: html -

                                      Get the snapshot status. - Get a detailed description of the current state for each shard participating in the snapshot.

                                      +

                                      Get the snapshot status.

                                      +

                                      Get a detailed description of the current state for each shard participating in the snapshot.

                                      Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. If this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.

                                      If you omit the <snapshot> request path parameter, the request retrieves information only for currently running snapshots. This usage is preferred. If needed, you can specify <repository> and <snapshot> to retrieve information for specific snapshots, even if they're not currently running.

                                      -

                                      Note that the stats will not be available for any shard snapshots in an ongoing snapshot completed by a node that (even momentarily) left the cluster. - Loading the stats from the repository is an expensive operation (see the WARNING below). - Therefore the stats values for such shards will be -1 even though the "stage" value will be "DONE", in order to minimize latency. - A "description" field will be present for a shard snapshot completed by a departed node explaining why the shard snapshot's stats results are invalid. - Consequently, the total stats for the index will be less than expected due to the missing values from these shards.

                                      WARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive. The API requires a read from the repository for each shard in each snapshot. For example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).

                                      @@ -1342,8 +1337,8 @@ def verify_repository( """ .. raw:: html -

                                      Verify a snapshot repository. - Check for common misconfigurations in a snapshot repository.

                                      +

                                      Verify a snapshot repository.

                                      +

                                      Check for common misconfigurations in a snapshot repository.

                                      ``_ diff --git a/elasticsearch/_sync/client/sql.py b/elasticsearch/_sync/client/sql.py index 90cb01681..b14eef35c 100644 --- a/elasticsearch/_sync/client/sql.py +++ b/elasticsearch/_sync/client/sql.py @@ -89,8 +89,8 @@ def delete_async( """ .. raw:: html -

                                      Delete an async SQL search. - Delete an async SQL search or a stored synchronous SQL search. +

                                      Delete an async SQL search.

                                      +

                                      Delete an async SQL search or a stored synchronous SQL search. If the search is still running, the API cancels it.

                                      If the Elasticsearch security features are enabled, only the following users can use this API to delete a search:

                                        @@ -145,8 +145,8 @@ def get_async( """ .. raw:: html -

                                        Get async SQL search results. - Get the current status and available results for an async SQL search or stored synchronous SQL search.

                                        +

                                        Get async SQL search results.

                                        +

                                        Get the current status and available results for an async SQL search or stored synchronous SQL search.

                                        If the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.

                                        @@ -208,8 +208,8 @@ def get_async_status( """ .. raw:: html -

                                        Get the async SQL search status. - Get the current status of an async SQL search or a stored synchronous SQL search.

                                        +

                                        Get the async SQL search status.

                                        +

                                        Get the current status of an async SQL search or a stored synchronous SQL search.

                                        ``_ @@ -283,7 +283,7 @@ def query( keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, keep_on_completion: t.Optional[bool] = None, page_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, - params: t.Optional[t.Mapping[str, t.Any]] = None, + params: t.Optional[t.Sequence[t.Any]] = None, pretty: t.Optional[bool] = None, query: t.Optional[str] = None, request_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, @@ -297,8 +297,8 @@ def query( """ .. raw:: html -

                                        Get SQL search results. - Run an SQL request.

                                        +

                                        Get SQL search results.

                                        +

                                        Run an SQL request.

                                        ``_ @@ -422,8 +422,8 @@ def translate( """ .. raw:: html -

                                        Translate SQL into Elasticsearch queries. - Translate an SQL search into a search API request containing Query DSL. +

                                        Translate SQL into Elasticsearch queries.

                                        +

                                        Translate an SQL search into a search API request containing Query DSL. It accepts the same request body parameters as the SQL search API, excluding cursor.

                                        diff --git a/elasticsearch/_sync/client/streams.py b/elasticsearch/_sync/client/streams.py new file mode 100644 index 000000000..e269f26f3 --- /dev/null +++ b/elasticsearch/_sync/client/streams.py @@ -0,0 +1,186 @@ +# Licensed to Elasticsearch B.V. under one or more contributor +# license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright +# ownership. Elasticsearch B.V. licenses this file to you under +# the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +import typing as t + +from elastic_transport import ObjectApiResponse, TextApiResponse + +from ._base import NamespacedClient +from .utils import ( + Stability, + _availability_warning, + _rewrite_parameters, +) + + +class StreamsClient(NamespacedClient): + + @_rewrite_parameters() + @_availability_warning(Stability.EXPERIMENTAL) + def logs_disable( + self, + *, + 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, + ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: + """ + .. raw:: html + +

                                        Disable logs stream.

                                        +

                                        Turn off the logs stream feature for this cluster.

                                        + + + ``_ + + :param master_timeout: The 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: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_streams/logs/_disable" + __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 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": "text/plain,application/json"} + return self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + endpoint_id="streams.logs_disable", + path_parts=__path_parts, + ) + + @_rewrite_parameters() + @_availability_warning(Stability.EXPERIMENTAL) + def logs_enable( + self, + *, + 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, + ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: + """ + .. raw:: html + +

                                        Enable logs stream.

                                        +

                                        Turn on the logs stream feature for this cluster.

                                        +

                                        NOTE: To protect existing data, this feature can be turned on only if the + cluster does not have existing indices or data streams that match the pattern logs|logs.*. + If those indices or data streams exist, a 409 - Conflict response and error is returned.

                                        + + + ``_ + + :param master_timeout: The 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: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_streams/logs/_enable" + __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 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": "text/plain,application/json"} + return self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + endpoint_id="streams.logs_enable", + path_parts=__path_parts, + ) + + @_rewrite_parameters() + @_availability_warning(Stability.EXPERIMENTAL) + def status( + self, + *, + 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["d", "h", "m", "micros", "ms", "nanos", "s"]] + ] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + .. raw:: html + +

                                        Get the status of streams.

                                        +

                                        Get the current status for all types of streams.

                                        + + + ``_ + + :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 = "/_streams/status" + __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 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"} + return self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="streams.status", + path_parts=__path_parts, + ) diff --git a/elasticsearch/_sync/client/synonyms.py b/elasticsearch/_sync/client/synonyms.py index 8731f40fd..b0199685f 100644 --- a/elasticsearch/_sync/client/synonyms.py +++ b/elasticsearch/_sync/client/synonyms.py @@ -95,8 +95,8 @@ def delete_synonym_rule( """ .. raw:: html -

                                        Delete a synonym rule. - Delete a synonym rule from a synonym set.

                                        +

                                        Delete a synonym rule.

                                        +

                                        Delete a synonym rule from a synonym set.

                                        ``_ @@ -204,8 +204,8 @@ def get_synonym_rule( """ .. raw:: html -

                                        Get a synonym rule. - Get a synonym rule from a synonym set.

                                        +

                                        Get a synonym rule.

                                        +

                                        Get a synonym rule from a synonym set.

                                        ``_ @@ -257,8 +257,8 @@ def get_synonyms_sets( """ .. raw:: html -

                                        Get all synonym sets. - Get a summary of all defined synonym sets.

                                        +

                                        Get all synonym sets.

                                        +

                                        Get a summary of all defined synonym sets.

                                        ``_ @@ -311,8 +311,8 @@ def put_synonym( """ .. raw:: html -

                                        Create or update a synonym set. - Synonyms sets are limited to a maximum of 10,000 synonym rules per set. +

                                        Create or update a synonym set.

                                        +

                                        Synonyms sets are limited to a maximum of 10,000 synonym rules per set. If you need to manage more synonym rules, you can create multiple synonym sets.

                                        When an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices. This is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.

                                        @@ -378,8 +378,8 @@ def put_synonym_rule( """ .. raw:: html -

                                        Create or update a synonym rule. - Create or update a synonym rule in a synonym set.

                                        +

                                        Create or update a synonym rule.

                                        +

                                        Create or update a synonym rule in a synonym set.

                                        If any of the synonym rules included is invalid, the API returns an error.

                                        When you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.

                                        diff --git a/elasticsearch/_sync/client/tasks.py b/elasticsearch/_sync/client/tasks.py index d9fc0b385..f3f0ba034 100644 --- a/elasticsearch/_sync/client/tasks.py +++ b/elasticsearch/_sync/client/tasks.py @@ -23,16 +23,16 @@ from .utils import ( SKIP_IN_PATH, Stability, + _availability_warning, _quote, _rewrite_parameters, - _stability_warning, ) class TasksClient(NamespacedClient): @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def cancel( self, *, @@ -106,7 +106,7 @@ def cancel( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def get( self, *, @@ -121,8 +121,8 @@ def get( """ .. raw:: html -

                                        Get task information. - Get information about a task currently running in the cluster.

                                        +

                                        Get task information.

                                        +

                                        Get information about a task currently running in the cluster.

                                        WARNING: The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible.

                                        If the task identifier is not found, a 404 response code indicates that there are no resources that match the request.

                                        @@ -164,7 +164,7 @@ def get( ) @_rewrite_parameters() - @_stability_warning(Stability.EXPERIMENTAL) + @_availability_warning(Stability.EXPERIMENTAL) def list( self, *, @@ -185,8 +185,8 @@ def list( """ .. raw:: html -

                                        Get all tasks. - Get information about the tasks currently running on one or more nodes in the cluster.

                                        +

                                        Get all tasks.

                                        +

                                        Get information about the tasks currently running on one or more nodes in the cluster.

                                        WARNING: The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible.

                                        Identifying running tasks

                                        diff --git a/elasticsearch/_sync/client/text_structure.py b/elasticsearch/_sync/client/text_structure.py index fa3218f81..5a64961c7 100644 --- a/elasticsearch/_sync/client/text_structure.py +++ b/elasticsearch/_sync/client/text_structure.py @@ -55,8 +55,8 @@ def find_field_structure( """ .. raw:: html -

                                        Find the structure of a text field. - Find the structure of a text field in an Elasticsearch index.

                                        +

                                        Find the structure of a text field.

                                        +

                                        Find the structure of a text field in an Elasticsearch index.

                                        This API provides a starting point for extracting further information from log messages already ingested into Elasticsearch. For example, if you have ingested data into a very simple index that has just @timestamp and message fields, you can use this API to see what common structure exists in the message field.

                                        The response from the API contains:

                                        @@ -241,8 +241,8 @@ def find_message_structure( """ .. raw:: html -

                                        Find the structure of text messages. - Find the structure of a list of text messages. +

                                        Find the structure of text messages.

                                        +

                                        Find the structure of a list of text messages. The messages must contain data that is suitable to be ingested into Elasticsearch.

                                        This API provides a starting point for ingesting data into Elasticsearch in a format that is suitable for subsequent use with other Elastic Stack functionality. Use this API rather than the find text structure API if your input text has already been split up into separate messages by some other process.

                                        @@ -402,7 +402,11 @@ def find_structure( delimiter: t.Optional[str] = None, ecs_compatibility: t.Optional[str] = None, explain: t.Optional[bool] = None, - format: t.Optional[str] = None, + format: t.Optional[ + t.Union[ + str, t.Literal["delimited", "ndjson", "semi_structured_text", "xml"] + ] + ] = None, grok_pattern: t.Optional[str] = None, has_header_row: t.Optional[bool] = None, line_merge_size_limit: t.Optional[int] = None, @@ -416,8 +420,8 @@ def find_structure( """ .. raw:: html -

                                        Find the structure of a text file. - The text file must contain data that is suitable to be ingested into Elasticsearch.

                                        +

                                        Find the structure of a text file.

                                        +

                                        The text file must contain data that is suitable to be ingested into Elasticsearch.

                                        This API provides a starting point for ingesting data into Elasticsearch in a format that is suitable for subsequent use with other Elastic Stack functionality. Unlike other Elasticsearch endpoints, the data that is posted to this endpoint does not need to be UTF-8 encoded and in JSON format. It must, however, be text; binary text formats are not currently supported. @@ -615,8 +619,8 @@ def test_grok_pattern( """ .. raw:: html -

                                        Test a Grok pattern. - Test a Grok pattern on one or more lines of text. +

                                        Test a Grok pattern.

                                        +

                                        Test a Grok pattern on one or more lines of text. The API indicates whether the lines match the pattern together with the offsets and lengths of the matched substrings.

                                        diff --git a/elasticsearch/_sync/client/transform.py b/elasticsearch/_sync/client/transform.py index ea9941f74..2ed2652da 100644 --- a/elasticsearch/_sync/client/transform.py +++ b/elasticsearch/_sync/client/transform.py @@ -85,6 +85,45 @@ def delete_transform( path_parts=__path_parts, ) + @_rewrite_parameters() + def get_node_stats( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + .. raw:: html + +

                                        Get node stats.

                                        +

                                        Get per-node information about transform usage.

                                        + + + ``_ + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_transform/_node_stats" + __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 human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="transform.get_node_stats", + path_parts=__path_parts, + ) + @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) @@ -104,8 +143,8 @@ def get_transform( """ .. raw:: html -

                                        Get transforms. - Get configuration information for transforms.

                                        +

                                        Get transforms.

                                        +

                                        Get configuration information for transforms.

                                        ``_ @@ -262,8 +301,8 @@ def preview_transform( """ .. raw:: html -

                                        Preview a transform. - Generates a preview of the results that you will get when you create a transform with the same configuration.

                                        +

                                        Preview a transform.

                                        +

                                        Generates a preview of the results that you will get when you create a transform with the same configuration.

                                        It returns a maximum of 100 results. The calculations are based on all the current data in the source index. It also generates a list of mappings and settings for the destination index. These values are determined based on the field types of the source index and the transform aggregations.

                                        @@ -386,8 +425,8 @@ def put_transform( """ .. raw:: html -

                                        Create a transform. - Creates a transform.

                                        +

                                        Create a transform.

                                        +

                                        Creates a transform.

                                        A transform copies data from source indices, transforms it, and persists it into an entity-centric destination index. You can also think of the destination index as a two-dimensional tabular data structure (known as a data frame). The ID for each document in the data frame is generated from a hash of the entity, so there is a unique row per entity.

                                        @@ -602,6 +641,66 @@ def schedule_now_transform( path_parts=__path_parts, ) + @_rewrite_parameters() + def set_upgrade_mode( + self, + *, + enabled: t.Optional[bool] = None, + error_trace: t.Optional[bool] = None, + 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]: + """ + .. raw:: html + +

                                        Set upgrade_mode for transform indices.

                                        +

                                        Sets a cluster wide upgrade_mode setting that prepares transform + indices for an upgrade. + When upgrading your cluster, in some circumstances you must restart your + nodes and reindex your transform indices. In those circumstances, + there must be no transforms running. You can close the transforms, + do the upgrade, then open all the transforms again. Alternatively, + you can use this API to temporarily halt tasks associated with the transforms + and prevent new transforms from opening. You can also use this API + during upgrades that do not require you to reindex your transform + indices, though stopping transforms is not a requirement in that case. + You can see the current value for the upgrade_mode setting by using the get + transform info API.

                                        + + + ``_ + + :param enabled: When `true`, it enables `upgrade_mode` which temporarily halts + all transform tasks and prohibits new transform tasks from starting. + :param timeout: The time to wait for the request to be completed. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_transform/set_upgrade_mode" + __query: t.Dict[str, t.Any] = {} + if enabled is not None: + __query["enabled"] = enabled + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout + __headers = {"accept": "application/json"} + return self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + endpoint_id="transform.set_upgrade_mode", + path_parts=__path_parts, + ) + @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) @@ -689,8 +788,8 @@ def stop_transform( """ .. raw:: html -

                                        Stop transforms. - Stops one or more transforms.

                                        +

                                        Stop transforms.

                                        +

                                        Stops one or more transforms.

                                        ``_ @@ -786,8 +885,8 @@ def update_transform( """ .. raw:: html -

                                        Update a transform. - Updates certain properties of a transform.

                                        +

                                        Update a transform.

                                        +

                                        Updates certain properties of a transform.

                                        All updated properties except description do not take effect until after the transform starts the next checkpoint, thus there is data consistency in each checkpoint. To use this API, you must have read and view_index_metadata privileges for the source indices. You must also have index and read privileges for the destination index. When diff --git a/elasticsearch/_sync/client/utils.py b/elasticsearch/_sync/client/utils.py index 48ebcb217..afade6e2d 100644 --- a/elasticsearch/_sync/client/utils.py +++ b/elasticsearch/_sync/client/utils.py @@ -79,6 +79,12 @@ class Stability(Enum): EXPERIMENTAL = auto() +class Visibility(Enum): + PUBLIC = auto() + FEATURE_FLAG = auto() + PRIVATE = auto() + + _TYPE_HOSTS = Union[ str, Sequence[Union[str, Mapping[str, Union[str, int]], NodeConfig]] ] @@ -419,15 +425,23 @@ def wrapped(*args: Any, **kwargs: Any) -> Any: return wrapper -def _stability_warning( +def _availability_warning( stability: Stability, + visibility: Visibility = Visibility.PUBLIC, version: Optional[str] = None, message: Optional[str] = None, ) -> Callable[[F], F]: def wrapper(api: F) -> F: @wraps(api) def wrapped(*args: Any, **kwargs: Any) -> Any: - if stability == Stability.BETA: + if visibility == Visibility.PRIVATE: + warnings.warn( + "This API is private. " + "Private APIs are not subject to the support SLA of official GA features.", + category=GeneralAvailabilityWarning, + stacklevel=warn_stacklevel(), + ) + elif stability == Stability.BETA: warnings.warn( "This API is in beta and is subject to change. " "The design and code is less mature than official GA features and is being provided as-is with no warranties. " diff --git a/elasticsearch/_sync/client/watcher.py b/elasticsearch/_sync/client/watcher.py index 9839cb80b..73f5eecb2 100644 --- a/elasticsearch/_sync/client/watcher.py +++ b/elasticsearch/_sync/client/watcher.py @@ -39,8 +39,8 @@ def ack_watch( """ .. raw:: html -

                                        Acknowledge a watch. - Acknowledging a watch enables you to manually throttle the execution of the watch's actions.

                                        +

                                        Acknowledge a watch.

                                        +

                                        Acknowledging a watch enables you to manually throttle the execution of the watch's actions.

                                        The acknowledgement state of an action is stored in the status.actions.<id>.ack.state structure.

                                        IMPORTANT: If the specified watch is currently being executed, this API will return an error The reason for this behavior is to prevent overwriting the watch status from a watch execution.

                                        @@ -101,8 +101,8 @@ def activate_watch( """ .. raw:: html -

                                        Activate a watch. - A watch can be either active or inactive.

                                        +

                                        Activate a watch.

                                        +

                                        A watch can be either active or inactive.

                                        ``_ @@ -145,8 +145,8 @@ def deactivate_watch( """ .. raw:: html -

                                        Deactivate a watch. - A watch can be either active or inactive.

                                        +

                                        Deactivate a watch.

                                        +

                                        A watch can be either active or inactive.

                                        ``_ @@ -189,8 +189,8 @@ def delete_watch( """ .. raw:: html -

                                        Delete a watch. - When the watch is removed, the document representing the watch in the .watches index is gone and it will never be run again.

                                        +

                                        Delete a watch.

                                        +

                                        When the watch is removed, the document representing the watch in the .watches index is gone and it will never be run again.

                                        Deleting a watch does not delete any watch execution records related to this watch from the watch history.

                                        IMPORTANT: Deleting a watch must be done by using only this API. Do not delete the watch directly from the .watches index using the Elasticsearch delete document API @@ -266,8 +266,8 @@ def execute_watch( """ .. raw:: html -

                                        Run a watch. - This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

                                        +

                                        Run a watch.

                                        +

                                        This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

                                        For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can run the watch without running all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.

                                        @@ -362,8 +362,8 @@ def get_settings( """ .. raw:: html -

                                        Get Watcher index settings. - Get settings for the Watcher internal index (.watches). +

                                        Get Watcher index settings.

                                        +

                                        Get settings for the Watcher internal index (.watches). Only a subset of settings are shown, for example index.auto_expand_replicas and index.number_of_replicas.

                                        @@ -476,8 +476,8 @@ def put_watch( """ .. raw:: html -

                                        Create or update a watch. - When a watch is registered, a new document that represents the watch is added to the .watches index and its trigger is immediately registered with the relevant trigger engine. +

                                        Create or update a watch.

                                        +

                                        When a watch is registered, a new document that represents the watch is added to the .watches index and its trigger is immediately registered with the relevant trigger engine. Typically for the schedule trigger, the scheduler is the trigger engine.

                                        IMPORTANT: You must use Kibana or this API to create a watch. Do not add a watch directly to the .watches index by using the Elasticsearch index API. @@ -494,9 +494,9 @@ def put_watch( :param active: The initial state of the watch. The default value is `true`, which means the watch is active by default. :param condition: The condition that defines if the actions should be run. - :param if_primary_term: only update the watch if the last operation that has + :param if_primary_term: Only update the watch if the last operation that has changed the watch has the specified primary term - :param if_seq_no: only update the watch if the last operation that has changed + :param if_seq_no: Only update the watch if the last operation that has changed the watch has the specified sequence number :param input: The input that defines the input that loads the data for the watch. :param metadata: Metadata JSON that will be copied into the history entries. @@ -552,11 +552,7 @@ def put_watch( __body["transform"] = transform if trigger is not None: __body["trigger"] = trigger - 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 self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -595,8 +591,8 @@ def query_watches( """ .. raw:: html -

                                        Query watches. - Get all registered watches in a paginated manner and optionally filter watches by a query.

                                        +

                                        Query watches.

                                        +

                                        Get all registered watches in a paginated manner and optionally filter watches by a query.

                                        Note that only the _id and metadata.* fields are queryable or sortable.

                                        @@ -671,8 +667,8 @@ def start( """ .. raw:: html -

                                        Start the watch service. - Start the Watcher service if it is not already running.

                                        +

                                        Start the watch service.

                                        +

                                        Start the Watcher service if it is not already running.

                                        ``_ @@ -736,8 +732,8 @@ def stats( """ .. raw:: html -

                                        Get Watcher statistics. - This API always returns basic metrics. +

                                        Get Watcher statistics.

                                        +

                                        This API always returns basic metrics. You retrieve more metrics by using the metric parameter.

                                        @@ -788,8 +784,8 @@ def stop( """ .. raw:: html -

                                        Stop the watch service. - Stop the Watcher service if it is running.

                                        +

                                        Stop the watch service.

                                        +

                                        Stop the Watcher service if it is running.

                                        ``_ @@ -844,8 +840,8 @@ def update_settings( """ .. raw:: html -

                                        Update Watcher index settings. - Update settings for the Watcher internal index (.watches). +

                                        Update Watcher index settings.

                                        +

                                        Update settings for the Watcher internal index (.watches). Only a subset of settings can be modified. This includes index.auto_expand_replicas, index.number_of_replicas, index.routing.allocation.exclude.*, index.routing.allocation.include.* and index.routing.allocation.require.*. diff --git a/elasticsearch/_sync/client/xpack.py b/elasticsearch/_sync/client/xpack.py index b44cd0909..7361c5a18 100644 --- a/elasticsearch/_sync/client/xpack.py +++ b/elasticsearch/_sync/client/xpack.py @@ -45,8 +45,8 @@ def info( """ .. raw:: html -

                                        Get information. - The information provided by the API includes:

                                        +

                                        Get information.

                                        +

                                        The information provided by the API includes:

                                        • Build information including the build number and timestamp.
                                        • License information about the currently installed license.
                                        • @@ -56,7 +56,8 @@ def info( ``_ - :param accept_enterprise: If this param is used it must be set to true + :param accept_enterprise: If used, this otherwise ignored parameter must be set + to true :param categories: A comma-separated list of the information categories to include in the response. For example, `build,license,features`. """ @@ -98,8 +99,8 @@ def usage( """ .. raw:: html -

                                          Get usage information. - Get information about the features that are currently enabled and available under the current license. +

                                          Get usage information.

                                          +

                                          Get information about the features that are currently enabled and available under the current license. The API also provides some usage statistics.

                                          diff --git a/elasticsearch/_version.py b/elasticsearch/_version.py index 0624a7ff1..e926f8270 100644 --- a/elasticsearch/_version.py +++ b/elasticsearch/_version.py @@ -15,4 +15,5 @@ # specific language governing permissions and limitations # under the License. -__versionstr__ = "9.0.2" +__versionstr__ = "9.1.2" +__es_specification_commit__ = "69144c05ec6727c4ee39aec454f7ad6a57d240fc" diff --git a/elasticsearch/client.py b/elasticsearch/client.py index 926ed5fe3..d2ee717c8 100644 --- a/elasticsearch/client.py +++ b/elasticsearch/client.py @@ -62,6 +62,7 @@ from ._sync.client.snapshot import SnapshotClient as SnapshotClient # noqa: F401 from ._sync.client.sql import SqlClient as SqlClient # noqa: F401 from ._sync.client.ssl import SslClient as SslClient # noqa: F401 +from ._sync.client.streams import StreamsClient as StreamsClient # noqa: F401 from ._sync.client.synonyms import SynonymsClient as SynonymsClient # noqa: F401 from ._sync.client.tasks import TasksClient as TasksClient # noqa: F401 from ._sync.client.text_structure import ( # noqa: F401 @@ -115,6 +116,7 @@ "SnapshotClient", "SqlClient", "SslClient", + "StreamsClient", "TasksClient", "TextStructureClient", "TransformClient", diff --git a/elasticsearch/compat.py b/elasticsearch/compat.py index 007971306..b44b9daea 100644 --- a/elasticsearch/compat.py +++ b/elasticsearch/compat.py @@ -15,11 +15,14 @@ # specific language governing permissions and limitations # under the License. +import asyncio import inspect import os import sys +from contextlib import asynccontextmanager, contextmanager from pathlib import Path -from typing import Tuple, Type, Union +from threading import Thread +from typing import Any, AsyncIterator, Callable, Coroutine, Iterator, Tuple, Type, Union string_types: Tuple[Type[str], Type[bytes]] = (str, bytes) @@ -76,9 +79,48 @@ def warn_stacklevel() -> int: return 0 +@contextmanager +def safe_thread( + target: Callable[..., Any], *args: Any, **kwargs: Any +) -> Iterator[Thread]: + """Run a thread within a context manager block. + + The thread is automatically joined when the block ends. If the thread raised + an exception, it is raised in the caller's context. + """ + captured_exception = None + + def run() -> None: + try: + target(*args, **kwargs) + except BaseException as exc: + nonlocal captured_exception + captured_exception = exc + + thread = Thread(target=run) + thread.start() + yield thread + thread.join() + if captured_exception: + raise captured_exception + + +@asynccontextmanager +async def safe_task(coro: Coroutine[Any, Any, Any]) -> AsyncIterator[asyncio.Task[Any]]: + """Run a background task within a context manager block. + + The task is awaited when the block ends. + """ + task = asyncio.create_task(coro) + yield task + await task + + __all__ = [ "string_types", "to_str", "to_bytes", "warn_stacklevel", + "safe_thread", + "safe_task", ] diff --git a/elasticsearch/dsl/__init__.py b/elasticsearch/dsl/__init__.py index e109db219..59294d632 100644 --- a/elasticsearch/dsl/__init__.py +++ b/elasticsearch/dsl/__init__.py @@ -38,23 +38,30 @@ TermsFacet, ) from .field import ( + AggregateMetricDouble, + Alias, Binary, Boolean, Byte, Completion, ConstantKeyword, + CountedKeyword, CustomField, Date, + DateNanos, DateRange, DenseVector, Double, DoubleRange, Field, + Flattened, Float, FloatRange, GeoPoint, GeoShape, HalfFloat, + Histogram, + IcuCollationKeyword, Integer, IntegerRange, Ip, @@ -63,21 +70,28 @@ Keyword, Long, LongRange, + MatchOnlyText, Murmur3, Nested, Object, + Passthrough, Percolator, Point, RangeField, RankFeature, RankFeatures, + RankVectors, ScaledFloat, SearchAsYouType, + SemanticText, Shape, Short, SparseVector, Text, TokenCount, + UnsignedLong, + Version, + Wildcard, construct_field, ) from .function import SF @@ -108,6 +122,8 @@ "A", "Agg", "AggResponse", + "AggregateMetricDouble", + "Alias", "AsyncComposableIndexTemplate", "AsyncDocument", "AsyncEmptySearch", @@ -126,9 +142,11 @@ "Completion", "ComposableIndexTemplate", "ConstantKeyword", + "CountedKeyword", "CustomField", "Date", "DateHistogramFacet", + "DateNanos", "DateRange", "DenseVector", "Document", @@ -142,12 +160,15 @@ "FacetedResponse", "FacetedSearch", "Field", + "Flattened", "Float", "FloatRange", "GeoPoint", "GeoShape", "HalfFloat", + "Histogram", "HistogramFacet", + "IcuCollationKeyword", "IllegalOperation", "Index", "IndexTemplate", @@ -162,12 +183,14 @@ "LongRange", "M", "Mapping", + "MatchOnlyText", "MetaField", "MultiSearch", "Murmur3", "Nested", "NestedFacet", "Object", + "Passthrough", "Percolator", "Point", "Q", @@ -177,11 +200,13 @@ "RangeField", "RankFeature", "RankFeatures", + "RankVectors", "Response", "SF", "ScaledFloat", "Search", "SearchAsYouType", + "SemanticText", "Shape", "Short", "SparseVector", @@ -189,9 +214,12 @@ "Text", "TokenCount", "UnknownDslObject", + "UnsignedLong", "UpdateByQuery", "UpdateByQueryResponse", "ValidationException", + "Version", + "Wildcard", "analyzer", "async_connections", "char_filter", diff --git a/elasticsearch/dsl/_async/document.py b/elasticsearch/dsl/_async/document.py index de6e9eecc..68908f390 100644 --- a/elasticsearch/dsl/_async/document.py +++ b/elasticsearch/dsl/_async/document.py @@ -20,6 +20,7 @@ TYPE_CHECKING, Any, AsyncIterable, + AsyncIterator, Dict, List, Optional, @@ -30,9 +31,8 @@ from typing_extensions import Self, dataclass_transform -from elasticsearch.exceptions import NotFoundError, RequestError -from elasticsearch.helpers import async_bulk - +from ...exceptions import NotFoundError, RequestError +from ...helpers import async_bulk from .._async.index import AsyncIndex from ..async_connections import get_connection from ..document_base import DocumentBase, DocumentMeta, mapped_field @@ -41,7 +41,8 @@ from .search import AsyncSearch if TYPE_CHECKING: - from elasticsearch import AsyncElasticsearch + from ... import AsyncElasticsearch + from ...esql.esql import ESQLBase class AsyncIndexMeta(DocumentMeta): @@ -520,3 +521,85 @@ async def __anext__(self) -> Dict[str, Any]: return action return await async_bulk(es, Generate(actions), **kwargs) + + @classmethod + async def esql_execute( + cls, + query: "ESQLBase", + return_additional: bool = False, + ignore_missing_fields: bool = False, + using: Optional[AsyncUsingType] = None, + **kwargs: Any, + ) -> AsyncIterator[Union[Self, Tuple[Self, Dict[str, Any]]]]: + """ + Execute the given ES|QL query and return an iterator of 2-element tuples, + where the first element is an instance of this ``Document`` and the + second a dictionary with any remaining columns requested in the query. + + :arg query: an ES|QL query object created with the ``esql_from()`` method. + :arg return_additional: if ``False`` (the default), this method returns + document objects. If set to ``True``, the method returns tuples with + a document in the first element and a dictionary with any additional + columns returned by the query in the second element. + :arg ignore_missing_fields: if ``False`` (the default), all the fields of + the document must be present in the query, or else an exception is + raised. Set to ``True`` to allow missing fields, which will result in + partially initialized document objects. + :arg using: connection alias to use, defaults to ``'default'`` + :arg kwargs: additional options for the ``client.esql.query()`` function. + """ + es = cls._get_connection(using) + response = await es.esql.query(query=str(query), **kwargs) + query_columns = [col["name"] for col in response.body.get("columns", [])] + + # Here we get the list of columns defined in the document, which are the + # columns that we will take from each result to assemble the document + # object. + # When `for_esql=False` is passed below by default, the list will include + # nested fields, which ES|QL does not return, causing an error. When passing + # `ignore_missing_fields=True` the list will be generated with + # `for_esql=True`, so the error will not occur, but the documents will + # not have any Nested objects in them. + doc_fields = set(cls._get_field_names(for_esql=ignore_missing_fields)) + if not ignore_missing_fields and not doc_fields.issubset(set(query_columns)): + raise ValueError( + f"Not all fields of {cls.__name__} were returned by the query. " + "Make sure your document does not use Nested fields, which are " + "currently not supported in ES|QL. To force the query to be " + "evaluated in spite of the missing fields, pass set the " + "ignore_missing_fields=True option in the esql_execute() call." + ) + non_doc_fields: set[str] = set(query_columns) - doc_fields - {"_id"} + index_id = query_columns.index("_id") + + results = response.body.get("values", []) + for column_values in results: + # create a dictionary with all the document fields, expanding the + # dot notation returned by ES|QL into the recursive dictionaries + # used by Document.from_dict() + doc_dict: Dict[str, Any] = {} + for col, val in zip(query_columns, column_values): + if col in doc_fields: + cols = col.split(".") + d = doc_dict + for c in cols[:-1]: + if c not in d: + d[c] = {} + d = d[c] + d[cols[-1]] = val + + # create the document instance + obj = cls(meta={"_id": column_values[index_id]}) + obj._from_dict(doc_dict) + + if return_additional: + # build a dict with any other values included in the response + other = { + col: val + for col, val in zip(query_columns, column_values) + if col in non_doc_fields + } + + yield obj, other + else: + yield obj diff --git a/elasticsearch/dsl/_async/index.py b/elasticsearch/dsl/_async/index.py index 58369579b..0795d47d2 100644 --- a/elasticsearch/dsl/_async/index.py +++ b/elasticsearch/dsl/_async/index.py @@ -30,7 +30,7 @@ if TYPE_CHECKING: from elastic_transport import ObjectApiResponse - from elasticsearch import AsyncElasticsearch + from ... import AsyncElasticsearch class AsyncIndexTemplate: diff --git a/elasticsearch/dsl/_async/search.py b/elasticsearch/dsl/_async/search.py index 2ea277a07..b4911fd58 100644 --- a/elasticsearch/dsl/_async/search.py +++ b/elasticsearch/dsl/_async/search.py @@ -29,9 +29,8 @@ from typing_extensions import Self -from elasticsearch.exceptions import ApiError -from elasticsearch.helpers import async_scan - +from ...exceptions import ApiError +from ...helpers import async_scan from ..async_connections import get_connection from ..response import Response from ..search_base import MultiSearchBase, SearchBase diff --git a/elasticsearch/dsl/_sync/document.py b/elasticsearch/dsl/_sync/document.py index f68be4aae..4821f4f98 100644 --- a/elasticsearch/dsl/_sync/document.py +++ b/elasticsearch/dsl/_sync/document.py @@ -21,6 +21,7 @@ Any, Dict, Iterable, + Iterator, List, Optional, Tuple, @@ -30,9 +31,8 @@ from typing_extensions import Self, dataclass_transform -from elasticsearch.exceptions import NotFoundError, RequestError -from elasticsearch.helpers import bulk - +from ...exceptions import NotFoundError, RequestError +from ...helpers import bulk from .._sync.index import Index from ..connections import get_connection from ..document_base import DocumentBase, DocumentMeta, mapped_field @@ -41,7 +41,8 @@ from .search import Search if TYPE_CHECKING: - from elasticsearch import Elasticsearch + from ... import Elasticsearch + from ...esql.esql import ESQLBase class IndexMeta(DocumentMeta): @@ -512,3 +513,85 @@ def __next__(self) -> Dict[str, Any]: return action return bulk(es, Generate(actions), **kwargs) + + @classmethod + def esql_execute( + cls, + query: "ESQLBase", + return_additional: bool = False, + ignore_missing_fields: bool = False, + using: Optional[UsingType] = None, + **kwargs: Any, + ) -> Iterator[Union[Self, Tuple[Self, Dict[str, Any]]]]: + """ + Execute the given ES|QL query and return an iterator of 2-element tuples, + where the first element is an instance of this ``Document`` and the + second a dictionary with any remaining columns requested in the query. + + :arg query: an ES|QL query object created with the ``esql_from()`` method. + :arg return_additional: if ``False`` (the default), this method returns + document objects. If set to ``True``, the method returns tuples with + a document in the first element and a dictionary with any additional + columns returned by the query in the second element. + :arg ignore_missing_fields: if ``False`` (the default), all the fields of + the document must be present in the query, or else an exception is + raised. Set to ``True`` to allow missing fields, which will result in + partially initialized document objects. + :arg using: connection alias to use, defaults to ``'default'`` + :arg kwargs: additional options for the ``client.esql.query()`` function. + """ + es = cls._get_connection(using) + response = es.esql.query(query=str(query), **kwargs) + query_columns = [col["name"] for col in response.body.get("columns", [])] + + # Here we get the list of columns defined in the document, which are the + # columns that we will take from each result to assemble the document + # object. + # When `for_esql=False` is passed below by default, the list will include + # nested fields, which ES|QL does not return, causing an error. When passing + # `ignore_missing_fields=True` the list will be generated with + # `for_esql=True`, so the error will not occur, but the documents will + # not have any Nested objects in them. + doc_fields = set(cls._get_field_names(for_esql=ignore_missing_fields)) + if not ignore_missing_fields and not doc_fields.issubset(set(query_columns)): + raise ValueError( + f"Not all fields of {cls.__name__} were returned by the query. " + "Make sure your document does not use Nested fields, which are " + "currently not supported in ES|QL. To force the query to be " + "evaluated in spite of the missing fields, pass set the " + "ignore_missing_fields=True option in the esql_execute() call." + ) + non_doc_fields: set[str] = set(query_columns) - doc_fields - {"_id"} + index_id = query_columns.index("_id") + + results = response.body.get("values", []) + for column_values in results: + # create a dictionary with all the document fields, expanding the + # dot notation returned by ES|QL into the recursive dictionaries + # used by Document.from_dict() + doc_dict: Dict[str, Any] = {} + for col, val in zip(query_columns, column_values): + if col in doc_fields: + cols = col.split(".") + d = doc_dict + for c in cols[:-1]: + if c not in d: + d[c] = {} + d = d[c] + d[cols[-1]] = val + + # create the document instance + obj = cls(meta={"_id": column_values[index_id]}) + obj._from_dict(doc_dict) + + if return_additional: + # build a dict with any other values included in the response + other = { + col: val + for col, val in zip(query_columns, column_values) + if col in non_doc_fields + } + + yield obj, other + else: + yield obj diff --git a/elasticsearch/dsl/_sync/index.py b/elasticsearch/dsl/_sync/index.py index b2d5830d9..9f9f1e0d1 100644 --- a/elasticsearch/dsl/_sync/index.py +++ b/elasticsearch/dsl/_sync/index.py @@ -30,7 +30,7 @@ if TYPE_CHECKING: from elastic_transport import ObjectApiResponse - from elasticsearch import Elasticsearch + from ... import Elasticsearch class IndexTemplate: diff --git a/elasticsearch/dsl/_sync/search.py b/elasticsearch/dsl/_sync/search.py index 4dfbdb92b..7538eb4f1 100644 --- a/elasticsearch/dsl/_sync/search.py +++ b/elasticsearch/dsl/_sync/search.py @@ -28,9 +28,8 @@ from typing_extensions import Self -from elasticsearch.exceptions import ApiError -from elasticsearch.helpers import scan - +from ...exceptions import ApiError +from ...helpers import scan from ..connections import get_connection from ..response import Response from ..search_base import MultiSearchBase, SearchBase diff --git a/elasticsearch/dsl/aggs.py b/elasticsearch/dsl/aggs.py index 802d6eca0..439955c98 100644 --- a/elasticsearch/dsl/aggs.py +++ b/elasticsearch/dsl/aggs.py @@ -653,6 +653,54 @@ def __init__( ) +class CartesianBounds(Agg[_R]): + """ + A metric aggregation that computes the spatial bounding box containing + all values for a Point or Shape field. + + :arg field: The field on which to run the aggregation. + :arg missing: The value to apply to documents that do not have a + value. By default, documents without a value are ignored. + :arg script: + """ + + name = "cartesian_bounds" + + def __init__( + self, + *, + field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, + missing: Union[str, int, float, bool, "DefaultType"] = DEFAULT, + script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, + **kwargs: Any, + ): + super().__init__(field=field, missing=missing, script=script, **kwargs) + + +class CartesianCentroid(Agg[_R]): + """ + A metric aggregation that computes the weighted centroid from all + coordinate values for point and shape fields. + + :arg field: The field on which to run the aggregation. + :arg missing: The value to apply to documents that do not have a + value. By default, documents without a value are ignored. + :arg script: + """ + + name = "cartesian_centroid" + + def __init__( + self, + *, + field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, + missing: Union[str, int, float, bool, "DefaultType"] = DEFAULT, + script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, + **kwargs: Any, + ): + super().__init__(field=field, missing=missing, script=script, **kwargs) + + class CategorizeText(Bucket[_R]): """ A multi-bucket aggregation that groups semi-structured text into @@ -735,6 +783,43 @@ def __init__( ) +class ChangePoint(Pipeline[_R]): + """ + A sibling pipeline that detects, spikes, dips, and change points in a + metric. Given a distribution of values provided by the sibling multi- + bucket aggregation, this aggregation indicates the bucket of any spike + or dip and/or the bucket at which the largest change in the + distribution of values, if they are statistically significant. There + must be at least 22 bucketed values. Fewer than 1,000 is preferred. + + :arg format: `DecimalFormat` pattern for the output value. If + specified, the formatted value is returned in the aggregation’s + `value_as_string` property. + :arg gap_policy: Policy to apply when gaps are found in the data. + Defaults to `skip` if omitted. + :arg buckets_path: Path to the buckets that contain one set of values + to correlate. + """ + + name = "change_point" + + def __init__( + self, + *, + format: Union[str, "DefaultType"] = DEFAULT, + gap_policy: Union[ + Literal["skip", "insert_zeros", "keep_values"], "DefaultType" + ] = DEFAULT, + buckets_path: Union[ + str, Sequence[str], Mapping[str, str], "DefaultType" + ] = DEFAULT, + **kwargs: Any, + ): + super().__init__( + format=format, gap_policy=gap_policy, buckets_path=buckets_path, **kwargs + ) + + class Children(Bucket[_R]): """ A single bucket aggregation that selects child documents that have the @@ -1410,7 +1495,7 @@ def __init__( "DefaultType", ] = DEFAULT, field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - precision: Union[float, str, "DefaultType"] = DEFAULT, + precision: Union[int, str, "DefaultType"] = DEFAULT, shard_size: Union[int, "DefaultType"] = DEFAULT, size: Union[int, "DefaultType"] = DEFAULT, **kwargs: Any, @@ -1494,7 +1579,7 @@ def __init__( self, *, field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - precision: Union[float, "DefaultType"] = DEFAULT, + precision: Union[int, "DefaultType"] = DEFAULT, shard_size: Union[int, "DefaultType"] = DEFAULT, size: Union[int, "DefaultType"] = DEFAULT, bounds: Union[ @@ -2595,7 +2680,7 @@ def __init__( self, *, keyed: Union[bool, "DefaultType"] = DEFAULT, - percents: Union[Sequence[float], "DefaultType"] = DEFAULT, + percents: Union[float, Sequence[float], "DefaultType"] = DEFAULT, hdr: Union["types.HdrMethod", Dict[str, Any], "DefaultType"] = DEFAULT, tdigest: Union["types.TDigest", Dict[str, Any], "DefaultType"] = DEFAULT, format: Union[str, "DefaultType"] = DEFAULT, @@ -2980,6 +3065,14 @@ class SignificantTerms(Bucket[_R]): the foreground sample with a term divided by the number of documents in the background with the term. :arg script_heuristic: Customized score, implemented via a script. + :arg p_value: Significant terms heuristic that calculates the p-value + between the term existing in foreground and background sets. The + p-value is the probability of obtaining test results at least as + extreme as the results actually observed, under the assumption + that the null hypothesis is correct. The p-value is calculated + assuming that the foreground set and the background set are + independent https://en.wikipedia.org/wiki/Bernoulli_trial, with + the null hypothesis that the probabilities are the same. :arg shard_min_doc_count: Regulates the certainty a shard has if the term should actually be added to the candidate list or not with respect to the `min_doc_count`. Terms will only be considered if @@ -3033,6 +3126,9 @@ def __init__( script_heuristic: Union[ "types.ScriptedHeuristic", Dict[str, Any], "DefaultType" ] = DEFAULT, + p_value: Union[ + "types.PValueHeuristic", Dict[str, Any], "DefaultType" + ] = DEFAULT, shard_min_doc_count: Union[int, "DefaultType"] = DEFAULT, shard_size: Union[int, "DefaultType"] = DEFAULT, size: Union[int, "DefaultType"] = DEFAULT, @@ -3051,6 +3147,7 @@ def __init__( mutual_information=mutual_information, percentage=percentage, script_heuristic=script_heuristic, + p_value=p_value, shard_min_doc_count=shard_min_doc_count, shard_size=shard_size, size=size, diff --git a/elasticsearch/dsl/async_connections.py b/elasticsearch/dsl/async_connections.py index 8a23d3828..0b51e3226 100644 --- a/elasticsearch/dsl/async_connections.py +++ b/elasticsearch/dsl/async_connections.py @@ -17,8 +17,7 @@ from typing import Type -from elasticsearch import AsyncElasticsearch - +from .. import AsyncElasticsearch from .connections import Connections diff --git a/elasticsearch/dsl/connections.py b/elasticsearch/dsl/connections.py index 8acd80c6e..679eaaf40 100644 --- a/elasticsearch/dsl/connections.py +++ b/elasticsearch/dsl/connections.py @@ -17,8 +17,7 @@ from typing import Any, Dict, Generic, Type, TypeVar, Union -from elasticsearch import Elasticsearch, __versionstr__ - +from .. import Elasticsearch, __versionstr__ from .serializer import serializer _T = TypeVar("_T") diff --git a/elasticsearch/dsl/document_base.py b/elasticsearch/dsl/document_base.py index 09da7d459..892f57f0b 100644 --- a/elasticsearch/dsl/document_base.py +++ b/elasticsearch/dsl/document_base.py @@ -34,6 +34,11 @@ overload, ) +try: + import annotationlib +except ImportError: + annotationlib = None # type: ignore[assignment] + try: from types import UnionType except ImportError: @@ -49,6 +54,7 @@ if TYPE_CHECKING: from elastic_transport import ObjectApiResponse + from ..esql.esql import ESQLBase from .index_base import IndexBase @@ -331,6 +337,16 @@ def __init__(self, name: str, bases: Tuple[type, ...], attrs: Dict[str, Any]): # # ignore attributes # field10: ClassVar[string] = "a regular class variable" annotations = attrs.get("__annotations__", {}) + if not annotations and annotationlib: + # Python 3.14+ uses annotationlib + annotate = annotationlib.get_annotate_from_class_namespace(attrs) + if annotate: + annotations = ( + annotationlib.call_annotate_function( + annotate, format=annotationlib.Format.VALUE + ) + or {} + ) fields = {n for n in attrs if isinstance(attrs[n], Field)} fields.update(annotations.keys()) field_defaults = {} @@ -602,3 +618,44 @@ def to_dict(self, include_meta: bool = False, skip_empty: bool = True) -> Dict[s meta["_source"] = d return meta + + @classmethod + def _get_field_names( + cls, for_esql: bool = False, nested_class: Optional[type[InnerDoc]] = None + ) -> List[str]: + """Return the list of field names used by this document. + If the document has nested objects, their fields are reported using dot + notation. If the ``for_esql`` argument is set to ``True``, the list omits + nested fields, which are currently unsupported in ES|QL. + """ + fields = [] + class_ = nested_class or cls + for field_name in class_._doc_type.mapping: + field = class_._doc_type.mapping[field_name] + if isinstance(field, Object): + if for_esql and isinstance(field, Nested): + # ES|QL does not recognize Nested fields at this time + continue + sub_fields = cls._get_field_names( + for_esql=for_esql, nested_class=field._doc_class + ) + for sub_field in sub_fields: + fields.append(f"{field_name}.{sub_field}") + else: + fields.append(field_name) + return fields + + @classmethod + def esql_from(cls) -> "ESQLBase": + """Return a base ES|QL query for instances of this document class. + + The returned query is initialized with ``FROM`` and ``KEEP`` statements, + and can be completed as desired. + """ + from ..esql import ESQL # here to avoid circular imports + + return ( + ESQL.from_(cls) + .metadata("_id") + .keep("_id", *tuple(cls._get_field_names(for_esql=True))) + ) diff --git a/elasticsearch/dsl/field.py b/elasticsearch/dsl/field.py index c33261458..c1e309d8c 100644 --- a/elasticsearch/dsl/field.py +++ b/elasticsearch/dsl/field.py @@ -119,9 +119,16 @@ def __init__( def __getitem__(self, subfield: str) -> "Field": return cast(Field, self._params.get("fields", {})[subfield]) - def _serialize(self, data: Any) -> Any: + def _serialize(self, data: Any, skip_empty: bool) -> Any: return data + def _safe_serialize(self, data: Any, skip_empty: bool) -> Any: + try: + return self._serialize(data, skip_empty) + except TypeError: + # older method signature, without skip_empty + return self._serialize(data) # type: ignore[call-arg] + def _deserialize(self, data: Any) -> Any: return data @@ -133,10 +140,16 @@ def empty(self) -> Optional[Any]: return AttrList([]) return self._empty() - def serialize(self, data: Any) -> Any: + def serialize(self, data: Any, skip_empty: bool = True) -> Any: if isinstance(data, (list, AttrList, tuple)): - return list(map(self._serialize, cast(Iterable[Any], data))) - return self._serialize(data) + return list( + map( + self._safe_serialize, + cast(Iterable[Any], data), + [skip_empty] * len(data), + ) + ) + return self._safe_serialize(data, skip_empty) def deserialize(self, data: Any) -> Any: if isinstance(data, (list, AttrList, tuple)): @@ -186,7 +199,7 @@ def _deserialize(self, data: Any) -> Range["_SupportsComparison"]: data = {k: self._core_field.deserialize(v) for k, v in data.items()} # type: ignore[union-attr] return Range(data) - def _serialize(self, data: Any) -> Optional[Dict[str, Any]]: + def _serialize(self, data: Any, skip_empty: bool) -> Optional[Dict[str, Any]]: if data is None: return None if not isinstance(data, collections.abc.Mapping): @@ -550,7 +563,7 @@ def _deserialize(self, data: Any) -> "InnerDoc": return self._wrap(data) def _serialize( - self, data: Optional[Union[Dict[str, Any], "InnerDoc"]] + self, data: Optional[Union[Dict[str, Any], "InnerDoc"]], skip_empty: bool ) -> Optional[Dict[str, Any]]: if data is None: return None @@ -559,7 +572,11 @@ def _serialize( if isinstance(data, collections.abc.Mapping): return data - return data.to_dict() + try: + return data.to_dict(skip_empty=skip_empty) + except TypeError: + # this would only happen if an AttrDict was given instead of an InnerDoc + return data.to_dict() def clean(self, data: Any) -> Any: data = super().clean(data) @@ -768,7 +785,7 @@ def clean(self, data: str) -> str: def _deserialize(self, data: Any) -> bytes: return base64.b64decode(data) - def _serialize(self, data: Any) -> Optional[str]: + def _serialize(self, data: Any, skip_empty: bool) -> Optional[str]: if data is None: return None return base64.b64encode(data).decode() @@ -2619,7 +2636,7 @@ def _deserialize(self, data: Any) -> Union["IPv4Address", "IPv6Address"]: # the ipaddress library for pypy only accepts unicode. return ipaddress.ip_address(unicode(data)) - def _serialize(self, data: Any) -> Optional[str]: + def _serialize(self, data: Any, skip_empty: bool) -> Optional[str]: if data is None: return None return str(data) @@ -3367,7 +3384,7 @@ def __init__( def _deserialize(self, data: Any) -> "Query": return Q(data) # type: ignore[no-any-return] - def _serialize(self, data: Any) -> Optional[Dict[str, Any]]: + def _serialize(self, data: Any, skip_empty: bool) -> Optional[Dict[str, Any]]: if data is None: return None return data.to_dict() # type: ignore[no-any-return] @@ -3849,17 +3866,18 @@ class SemanticText(Field): by using the Update mapping API. Use the Create inference API to create the endpoint. If not specified, the inference endpoint defined by inference_id will be used at both index and query time. - :arg index_options: Settings for index_options that override any - defaults used by semantic_text, for example specific quantization - settings. :arg chunking_settings: Settings for chunking text into smaller passages. If specified, these will override the chunking settings sent in the inference endpoint associated with inference_id. If chunking settings are updated, they will not be applied to existing documents until they are reindexed. + :arg fields: """ name = "semantic_text" + _param_defs = { + "fields": {"type": "field", "hash": True}, + } def __init__( self, @@ -3867,12 +3885,10 @@ def __init__( meta: Union[Mapping[str, str], "DefaultType"] = DEFAULT, inference_id: Union[str, "DefaultType"] = DEFAULT, search_inference_id: Union[str, "DefaultType"] = DEFAULT, - index_options: Union[ - "types.SemanticTextIndexOptions", Dict[str, Any], "DefaultType" - ] = DEFAULT, chunking_settings: Union[ "types.ChunkingSettings", Dict[str, Any], "DefaultType" ] = DEFAULT, + fields: Union[Mapping[str, Field], "DefaultType"] = DEFAULT, **kwargs: Any, ): if meta is not DEFAULT: @@ -3881,10 +3897,10 @@ def __init__( kwargs["inference_id"] = inference_id if search_inference_id is not DEFAULT: kwargs["search_inference_id"] = search_inference_id - if index_options is not DEFAULT: - kwargs["index_options"] = index_options if chunking_settings is not DEFAULT: kwargs["chunking_settings"] = chunking_settings + if fields is not DEFAULT: + kwargs["fields"] = fields super().__init__(*args, **kwargs) diff --git a/elasticsearch/dsl/query.py b/elasticsearch/dsl/query.py index 0a2cef032..27d7dac6c 100644 --- a/elasticsearch/dsl/query.py +++ b/elasticsearch/dsl/query.py @@ -370,6 +370,7 @@ def __init__( _value: Union[ "types.CommonTermsQuery", Dict[str, Any], "DefaultType" ] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -666,6 +667,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.FuzzyQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -708,6 +710,7 @@ def __init__( Dict[str, Any], "DefaultType", ] = DEFAULT, + /, *, type: Union[Literal["memory", "indexed"], "DefaultType"] = DEFAULT, validation_method: Union[ @@ -771,6 +774,7 @@ def __init__( Dict[str, Any], "DefaultType", ] = DEFAULT, + /, *, distance: Union[str, "DefaultType"] = DEFAULT, distance_type: Union[Literal["arc", "plane"], "DefaultType"] = DEFAULT, @@ -810,6 +814,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.GeoGridQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -839,6 +844,7 @@ def __init__( _value: Union[ "types.GeoPolygonPoints", Dict[str, Any], "DefaultType" ] = DEFAULT, + /, *, validation_method: Union[ Literal["coerce", "ignore_malformed", "strict"], "DefaultType" @@ -885,6 +891,7 @@ def __init__( _value: Union[ "types.GeoShapeFieldQuery", Dict[str, Any], "DefaultType" ] = DEFAULT, + /, *, ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, boost: Union[float, "DefaultType"] = DEFAULT, @@ -1060,6 +1067,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.IntervalsQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -1147,6 +1155,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.MatchQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -1212,6 +1221,7 @@ def __init__( _value: Union[ "types.MatchBoolPrefixQuery", Dict[str, Any], "DefaultType" ] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -1272,6 +1282,7 @@ def __init__( _value: Union[ "types.MatchPhraseQuery", Dict[str, Any], "DefaultType" ] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -1297,6 +1308,7 @@ def __init__( _value: Union[ "types.MatchPhrasePrefixQuery", Dict[str, Any], "DefaultType" ] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -1780,6 +1792,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.PrefixQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -1946,6 +1959,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["wrappers.Range[Any]", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -2024,6 +2038,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.RegexpQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -2194,6 +2209,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.ShapeFieldQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, *, ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, boost: Union[float, "DefaultType"] = DEFAULT, @@ -2552,6 +2568,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.SpanTermQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -2672,6 +2689,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.TermQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -2706,6 +2724,7 @@ def __init__( Dict[str, Any], "DefaultType", ] = DEFAULT, + /, *, boost: Union[float, "DefaultType"] = DEFAULT, _name: Union[str, "DefaultType"] = DEFAULT, @@ -2739,6 +2758,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.TermsSetQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -2764,6 +2784,7 @@ def __init__( _value: Union[ "types.TextExpansionQuery", Dict[str, Any], "DefaultType" ] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -2788,6 +2809,7 @@ def __init__( _value: Union[ "types.WeightedTokensQuery", Dict[str, Any], "DefaultType" ] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: @@ -2809,6 +2831,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["types.WildcardQuery", Dict[str, Any], "DefaultType"] = DEFAULT, + /, **kwargs: Any, ): if _field is not DEFAULT: diff --git a/elasticsearch/dsl/response/__init__.py b/elasticsearch/dsl/response/__init__.py index 712cda27b..b58464e16 100644 --- a/elasticsearch/dsl/response/__init__.py +++ b/elasticsearch/dsl/response/__init__.py @@ -233,10 +233,13 @@ def search_after(self) -> "SearchBase[_R]": "types.SimpleValueAggregate", "types.DerivativeAggregate", "types.BucketMetricValueAggregate", + "types.ChangePointAggregate", "types.StatsAggregate", "types.StatsBucketAggregate", "types.ExtendedStatsAggregate", "types.ExtendedStatsBucketAggregate", + "types.CartesianBoundsAggregate", + "types.CartesianCentroidAggregate", "types.GeoBoundsAggregate", "types.GeoCentroidAggregate", "types.HistogramAggregate", diff --git a/elasticsearch/dsl/response/aggs.py b/elasticsearch/dsl/response/aggs.py index 8994fa761..51360f3f6 100644 --- a/elasticsearch/dsl/response/aggs.py +++ b/elasticsearch/dsl/response/aggs.py @@ -63,7 +63,7 @@ def _wrap_bucket(self, data: Dict[str, Any]) -> Bucket[_R]: ) def __iter__(self) -> Iterator["Agg"]: # type: ignore[override] - return iter(self.buckets) # type: ignore[arg-type] + return iter(self.buckets) def __len__(self) -> int: return len(self.buckets) diff --git a/elasticsearch/dsl/serializer.py b/elasticsearch/dsl/serializer.py index 3080f1dad..641e78f4b 100644 --- a/elasticsearch/dsl/serializer.py +++ b/elasticsearch/dsl/serializer.py @@ -17,8 +17,7 @@ from typing import Any -from elasticsearch.serializer import JSONSerializer - +from ..serializer import JSONSerializer from .utils import AttrList diff --git a/elasticsearch/dsl/types.py b/elasticsearch/dsl/types.py index 383a69d83..520eb15b0 100644 --- a/elasticsearch/dsl/types.py +++ b/elasticsearch/dsl/types.py @@ -150,24 +150,23 @@ class ChunkingSettings(AttrDict[Any]): or`separator_group` Learn more about different chunking strategies in the linked documentation. Defaults to `sentence` if omitted. - :arg separator_group: (required) This parameter is only applicable - when using the `recursive` chunking strategy. Sets a predefined - list of separators in the saved chunking settings based on the - selected text type. Values can be `markdown` or `plaintext`. - Using this parameter is an alternative to manually specifying a - custom `separators` list. - :arg separators: (required) A list of strings used as possible split - points when chunking text with the `recursive` strategy. Each - string can be a plain string or a regular expression (regex) - pattern. The system tries each separator in order to split the - text, starting from the first item in the list. After splitting, - it attempts to recombine smaller pieces into larger chunks that - stay within the `max_chunk_size` limit, to reduce the total number - of chunks generated. :arg max_chunk_size: (required) The maximum size of a chunk in words. This value cannot be higher than `300` or lower than `20` (for `sentence` strategy) or `10` (for `word` strategy). Defaults to `250` if omitted. + :arg separator_group: Only applicable to the `recursive` strategy and + required when using it. Sets a predefined list of separators in + the saved chunking settings based on the selected text type. + Values can be `markdown` or `plaintext`. Using this parameter is + an alternative to manually specifying a custom `separators` list. + :arg separators: Only applicable to the `recursive` strategy and + required when using it. A list of strings used as possible split + points when chunking text. Each string can be a plain string or a + regular expression (regex) pattern. The system tries each + separator in order to split the text, starting from the first item + in the list. After splitting, it attempts to recombine smaller + pieces into larger chunks that stay within the `max_chunk_size` + limit, to reduce the total number of chunks generated. :arg overlap: The number of overlapping words for chunks. It is applicable only to a `word` chunking strategy. This value cannot be higher than half the `max_chunk_size` value. Defaults to `100` @@ -178,9 +177,9 @@ class ChunkingSettings(AttrDict[Any]): """ strategy: Union[str, DefaultType] + max_chunk_size: Union[int, DefaultType] separator_group: Union[str, DefaultType] separators: Union[Sequence[str], DefaultType] - max_chunk_size: Union[int, DefaultType] overlap: Union[int, DefaultType] sentence_overlap: Union[int, DefaultType] @@ -188,21 +187,21 @@ def __init__( self, *, strategy: Union[str, DefaultType] = DEFAULT, + max_chunk_size: Union[int, DefaultType] = DEFAULT, separator_group: Union[str, DefaultType] = DEFAULT, separators: Union[Sequence[str], DefaultType] = DEFAULT, - max_chunk_size: Union[int, DefaultType] = DEFAULT, overlap: Union[int, DefaultType] = DEFAULT, sentence_overlap: Union[int, DefaultType] = DEFAULT, **kwargs: Any, ): if strategy is not DEFAULT: kwargs["strategy"] = strategy + if max_chunk_size is not DEFAULT: + kwargs["max_chunk_size"] = max_chunk_size if separator_group is not DEFAULT: kwargs["separator_group"] = separator_group if separators is not DEFAULT: kwargs["separators"] = separators - if max_chunk_size is not DEFAULT: - kwargs["max_chunk_size"] = max_chunk_size if overlap is not DEFAULT: kwargs["overlap"] = overlap if sentence_overlap is not DEFAULT: @@ -939,6 +938,7 @@ def __init__( Dict[str, Any], "DefaultType", ] = DEFAULT, + /, *, mode: Union[ Literal["min", "max", "sum", "avg", "median"], DefaultType @@ -2775,6 +2775,31 @@ def __init__( super().__init__(kwargs) +class PValueHeuristic(AttrDict[Any]): + """ + :arg background_is_superset: + :arg normalize_above: Should the results be normalized when above the + given value. Allows for consistent significance results at various + scales. Note: `0` is a special value which means no normalization + """ + + background_is_superset: Union[bool, DefaultType] + normalize_above: Union[int, DefaultType] + + def __init__( + self, + *, + background_is_superset: Union[bool, DefaultType] = DEFAULT, + normalize_above: Union[int, DefaultType] = DEFAULT, + **kwargs: Any, + ): + if background_is_superset is not DEFAULT: + kwargs["background_is_superset"] = background_is_superset + if normalize_above is not DEFAULT: + kwargs["normalize_above"] = normalize_above + super().__init__(kwargs) + + class PercentageScoreHeuristic(AttrDict[Any]): pass @@ -3165,26 +3190,6 @@ def __init__( super().__init__(kwargs) -class SemanticTextIndexOptions(AttrDict[Any]): - """ - :arg dense_vector: - """ - - dense_vector: Union["DenseVectorIndexOptions", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - dense_vector: Union[ - "DenseVectorIndexOptions", Dict[str, Any], DefaultType - ] = DEFAULT, - **kwargs: Any, - ): - if dense_vector is not DEFAULT: - kwargs["dense_vector"] = dense_vector - super().__init__(kwargs) - - class ShapeFieldQuery(AttrDict[Any]): """ :arg indexed_shape: Queries using a pre-indexed shape. @@ -3240,6 +3245,7 @@ def __init__( self, _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, _value: Union["FieldSort", Dict[str, Any], "DefaultType"] = DEFAULT, + /, *, _score: Union["ScoreSort", Dict[str, Any], DefaultType] = DEFAULT, _doc: Union["ScoreSort", Dict[str, Any], DefaultType] = DEFAULT, @@ -4030,24 +4036,25 @@ def __init__( class TextEmbedding(AttrDict[Any]): """ - :arg model_id: (required) :arg model_text: (required) + :arg model_id: Model ID is required for all dense_vector fields but + may be inferred for semantic_text fields """ - model_id: Union[str, DefaultType] model_text: Union[str, DefaultType] + model_id: Union[str, DefaultType] def __init__( self, *, - model_id: Union[str, DefaultType] = DEFAULT, model_text: Union[str, DefaultType] = DEFAULT, + model_id: Union[str, DefaultType] = DEFAULT, **kwargs: Any, ): - if model_id is not DEFAULT: - kwargs["model_id"] = model_id if model_text is not DEFAULT: kwargs["model_text"] = model_text + if model_id is not DEFAULT: + kwargs["model_id"] = model_id super().__init__(kwargs) @@ -4569,7 +4576,7 @@ class ArrayPercentilesItem(AttrDict[Any]): :arg value_as_string: """ - key: str + key: float value: Union[float, None] value_as_string: str @@ -4680,6 +4687,82 @@ class CardinalityAggregate(AttrDict[Any]): meta: Mapping[str, Any] +class CartesianBoundsAggregate(AttrDict[Any]): + """ + :arg bounds: + :arg meta: + """ + + bounds: "TopLeftBottomRightGeoBounds" + meta: Mapping[str, Any] + + +class CartesianCentroidAggregate(AttrDict[Any]): + """ + :arg count: (required) + :arg location: + :arg meta: + """ + + count: int + location: "CartesianPoint" + meta: Mapping[str, Any] + + +class CartesianPoint(AttrDict[Any]): + """ + :arg x: (required) + :arg y: (required) + """ + + x: float + y: float + + +class ChangePointAggregate(AttrDict[Any]): + """ + :arg type: (required) + :arg bucket: + :arg meta: + """ + + type: "ChangeType" + bucket: "ChangePointBucket" + meta: Mapping[str, Any] + + +class ChangePointBucket(AttrDict[Any]): + """ + :arg key: (required) + :arg doc_count: (required) + """ + + key: Union[int, float, str, bool, None] + doc_count: int + + +class ChangeType(AttrDict[Any]): + """ + :arg dip: + :arg distribution_change: + :arg indeterminable: + :arg non_stationary: + :arg spike: + :arg stationary: + :arg step_change: + :arg trend_change: + """ + + dip: "Dip" + distribution_change: "DistributionChange" + indeterminable: "Indeterminable" + non_stationary: "NonStationary" + spike: "Spike" + stationary: "Stationary" + step_change: "StepChange" + trend_change: "TrendChange" + + class ChildrenAggregate(AttrDict[Any]): """ :arg doc_count: (required) @@ -4957,6 +5040,26 @@ class DfsStatisticsProfile(AttrDict[Any]): children: Sequence["DfsStatisticsProfile"] +class Dip(AttrDict[Any]): + """ + :arg p_value: (required) + :arg change_point: (required) + """ + + p_value: float + change_point: int + + +class DistributionChange(AttrDict[Any]): + """ + :arg p_value: (required) + :arg change_point: (required) + """ + + p_value: float + change_point: int + + class DoubleTermsAggregate(AttrDict[Any]): """ Result of a `terms` aggregation when the field is some kind of decimal @@ -5415,7 +5518,9 @@ class HdrPercentileRanksAggregate(AttrDict[Any]): :arg meta: """ - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] + values: Union[ + Mapping[str, Union[str, float, None]], Sequence["ArrayPercentilesItem"] + ] meta: Mapping[str, Any] @@ -5425,7 +5530,9 @@ class HdrPercentilesAggregate(AttrDict[Any]): :arg meta: """ - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] + values: Union[ + Mapping[str, Union[str, float, None]], Sequence["ArrayPercentilesItem"] + ] meta: Mapping[str, Any] @@ -5514,6 +5621,14 @@ class HitsMetadata(AttrDict[Any]): max_score: Union[float, None] +class Indeterminable(AttrDict[Any]): + """ + :arg reason: (required) + """ + + reason: str + + class InferenceAggregate(AttrDict[Any]): """ :arg value: @@ -5916,6 +6031,18 @@ class NestedIdentity(AttrDict[Any]): _nested: "NestedIdentity" +class NonStationary(AttrDict[Any]): + """ + :arg p_value: (required) + :arg r_value: (required) + :arg trend: (required) + """ + + p_value: float + r_value: float + trend: str + + class ParentAggregate(AttrDict[Any]): """ :arg doc_count: (required) @@ -5932,7 +6059,9 @@ class PercentilesBucketAggregate(AttrDict[Any]): :arg meta: """ - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] + values: Union[ + Mapping[str, Union[str, float, None]], Sequence["ArrayPercentilesItem"] + ] meta: Mapping[str, Any] @@ -6133,17 +6262,19 @@ class SearchProfile(AttrDict[Any]): class ShardFailure(AttrDict[Any]): """ :arg reason: (required) - :arg shard: (required) :arg index: :arg node: + :arg shard: :arg status: + :arg primary: """ reason: "ErrorCause" - shard: int index: str node: str + shard: int status: str + primary: bool class ShardProfile(AttrDict[Any]): @@ -6269,6 +6400,16 @@ class SimpleValueAggregate(AttrDict[Any]): meta: Mapping[str, Any] +class Spike(AttrDict[Any]): + """ + :arg p_value: (required) + :arg change_point: (required) + """ + + p_value: float + change_point: int + + class StandardDeviationBounds(AttrDict[Any]): """ :arg upper: (required) @@ -6305,6 +6446,10 @@ class StandardDeviationBoundsAsString(AttrDict[Any]): lower_sampling: str +class Stationary(AttrDict[Any]): + pass + + class StatsAggregate(AttrDict[Any]): """ Statistics aggregation result. `min`, `max` and `avg` are missing if @@ -6360,6 +6505,16 @@ class StatsBucketAggregate(AttrDict[Any]): meta: Mapping[str, Any] +class StepChange(AttrDict[Any]): + """ + :arg p_value: (required) + :arg change_point: (required) + """ + + p_value: float + change_point: int + + class StringRareTermsAggregate(AttrDict[Any]): """ Result of the `rare_terms` aggregation when the field is a string. @@ -6467,7 +6622,9 @@ class TDigestPercentileRanksAggregate(AttrDict[Any]): :arg meta: """ - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] + values: Union[ + Mapping[str, Union[str, float, None]], Sequence["ArrayPercentilesItem"] + ] meta: Mapping[str, Any] @@ -6477,7 +6634,9 @@ class TDigestPercentilesAggregate(AttrDict[Any]): :arg meta: """ - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] + values: Union[ + Mapping[str, Union[str, float, None]], Sequence["ArrayPercentilesItem"] + ] meta: Mapping[str, Any] @@ -6587,6 +6746,18 @@ class TotalHits(AttrDict[Any]): value: int +class TrendChange(AttrDict[Any]): + """ + :arg p_value: (required) + :arg r_value: (required) + :arg change_point: (required) + """ + + p_value: float + r_value: float + change_point: int + + class UnmappedRareTermsAggregate(AttrDict[Any]): """ Result of a `rare_terms` aggregation when the field is unmapped. diff --git a/elasticsearch/dsl/utils.py b/elasticsearch/dsl/utils.py index 127a48cc2..dd5311b7c 100644 --- a/elasticsearch/dsl/utils.py +++ b/elasticsearch/dsl/utils.py @@ -44,8 +44,7 @@ if TYPE_CHECKING: from elastic_transport import ObjectApiResponse - from elasticsearch import AsyncElasticsearch, Elasticsearch - + from .. import AsyncElasticsearch, Elasticsearch from .document_base import DocumentOptions from .field import Field from .index_base import IndexBase @@ -603,7 +602,7 @@ def to_dict(self, skip_empty: bool = True) -> Dict[str, Any]: # if this is a mapped field, f = self.__get_field(k) if f and f._coerce: - v = f.serialize(v) + v = f.serialize(v, skip_empty=skip_empty) # if someone assigned AttrList, unwrap it if isinstance(v, AttrList): diff --git a/elasticsearch/esql/__init__.py b/elasticsearch/esql/__init__.py index d872c329a..4a843ad59 100644 --- a/elasticsearch/esql/__init__.py +++ b/elasticsearch/esql/__init__.py @@ -15,4 +15,5 @@ # specific language governing permissions and limitations # under the License. -from .esql import ESQL, and_, not_, or_ # noqa: F401 +from ..dsl import E # noqa: F401 +from .esql import ESQL, ESQLBase, and_, not_, or_ # noqa: F401 diff --git a/elasticsearch/esql/esql.py b/elasticsearch/esql/esql.py index 07ccdf839..367ec971d 100644 --- a/elasticsearch/esql/esql.py +++ b/elasticsearch/esql/esql.py @@ -16,6 +16,7 @@ # under the License. import json +import re from abc import ABC, abstractmethod from typing import Any, Dict, Optional, Tuple, Type, Union @@ -111,6 +112,29 @@ def render(self) -> str: def _render_internal(self) -> str: pass + @staticmethod + def _format_index(index: IndexType) -> str: + return index._index._name if hasattr(index, "_index") else str(index) + + @staticmethod + def _format_id(id: FieldType, allow_patterns: bool = False) -> str: + s = str(id) # in case it is an InstrumentedField + if allow_patterns and "*" in s: + return s # patterns cannot be escaped + if re.fullmatch(r"[a-zA-Z_@][a-zA-Z0-9_\.]*", s): + return s + # this identifier needs to be escaped + s = s.replace("`", "``") + return f"`{s}`" + + @staticmethod + def _format_expr(expr: ExpressionType) -> str: + return ( + json.dumps(expr) + if not isinstance(expr, (str, InstrumentedExpression)) + else str(expr) + ) + def _is_forked(self) -> bool: if self.__class__.__name__ == "Fork": return True @@ -427,7 +451,7 @@ def sample(self, probability: float) -> "Sample": """ return Sample(self, probability) - def sort(self, *columns: FieldType) -> "Sort": + def sort(self, *columns: ExpressionType) -> "Sort": """The ``SORT`` processing command sorts a table on one or more columns. :param columns: The columns to sort on. @@ -570,15 +594,12 @@ def metadata(self, *fields: FieldType) -> "From": return self def _render_internal(self) -> str: - indices = [ - index if isinstance(index, str) else index._index._name - for index in self._indices - ] + indices = [self._format_index(index) for index in self._indices] s = f'{self.__class__.__name__.upper()} {", ".join(indices)}' if self._metadata_fields: s = ( s - + f' METADATA {", ".join([str(field) for field in self._metadata_fields])}' + + f' METADATA {", ".join([self._format_id(field) for field in self._metadata_fields])}' ) return s @@ -594,7 +615,11 @@ class Row(ESQLBase): def __init__(self, **params: ExpressionType): super().__init__() self._params = { - k: json.dumps(v) if not isinstance(v, InstrumentedExpression) else v + self._format_id(k): ( + json.dumps(v) + if not isinstance(v, InstrumentedExpression) + else self._format_expr(v) + ) for k, v in params.items() } @@ -615,7 +640,7 @@ def __init__(self, item: str): self._item = item def _render_internal(self) -> str: - return f"SHOW {self._item}" + return f"SHOW {self._format_id(self._item)}" class Branch(ESQLBase): @@ -667,11 +692,11 @@ def as_(self, type_name: str, pvalue_name: str) -> "ChangePoint": return self def _render_internal(self) -> str: - key = "" if not self._key else f" ON {self._key}" + key = "" if not self._key else f" ON {self._format_id(self._key)}" names = ( "" if not self._type_name and not self._pvalue_name - else f' AS {self._type_name or "type"}, {self._pvalue_name or "pvalue"}' + else f' AS {self._format_id(self._type_name or "type")}, {self._format_id(self._pvalue_name or "pvalue")}' ) return f"CHANGE_POINT {self._value}{key}{names}" @@ -709,12 +734,13 @@ def with_(self, inference_id: str) -> "Completion": def _render_internal(self) -> str: if self._inference_id is None: raise ValueError("The completion command requires an inference ID") + with_ = {"inference_id": self._inference_id} if self._named_prompt: column = list(self._named_prompt.keys())[0] prompt = list(self._named_prompt.values())[0] - return f"COMPLETION {column} = {prompt} WITH {self._inference_id}" + return f"COMPLETION {self._format_id(column)} = {self._format_id(prompt)} WITH {json.dumps(with_)}" else: - return f"COMPLETION {self._prompt[0]} WITH {self._inference_id}" + return f"COMPLETION {self._format_id(self._prompt[0])} WITH {json.dumps(with_)}" class Dissect(ESQLBase): @@ -742,9 +768,13 @@ def append_separator(self, separator: str) -> "Dissect": def _render_internal(self) -> str: sep = ( - "" if self._separator is None else f' APPEND_SEPARATOR="{self._separator}"' + "" + if self._separator is None + else f" APPEND_SEPARATOR={json.dumps(self._separator)}" + ) + return ( + f"DISSECT {self._format_id(self._input)} {json.dumps(self._pattern)}{sep}" ) - return f"DISSECT {self._input} {json.dumps(self._pattern)}{sep}" class Drop(ESQLBase): @@ -760,7 +790,7 @@ def __init__(self, parent: ESQLBase, *columns: FieldType): self._columns = columns def _render_internal(self) -> str: - return f'DROP {", ".join([str(col) for col in self._columns])}' + return f'DROP {", ".join([self._format_id(col, allow_patterns=True) for col in self._columns])}' class Enrich(ESQLBase): @@ -814,12 +844,18 @@ def with_(self, *fields: FieldType, **named_fields: FieldType) -> "Enrich": return self def _render_internal(self) -> str: - on = "" if self._match_field is None else f" ON {self._match_field}" + on = ( + "" + if self._match_field is None + else f" ON {self._format_id(self._match_field)}" + ) with_ = "" if self._named_fields: - with_ = f' WITH {", ".join([f"{name} = {field}" for name, field in self._named_fields.items()])}' + with_ = f' WITH {", ".join([f"{self._format_id(name)} = {self._format_id(field)}" for name, field in self._named_fields.items()])}' elif self._fields is not None: - with_ = f' WITH {", ".join([str(field) for field in self._fields])}' + with_ = ( + f' WITH {", ".join([self._format_id(field) for field in self._fields])}' + ) return f"ENRICH {self._policy}{on}{with_}" @@ -832,7 +868,10 @@ class Eval(ESQLBase): """ def __init__( - self, parent: ESQLBase, *columns: FieldType, **named_columns: FieldType + self, + parent: ESQLBase, + *columns: ExpressionType, + **named_columns: ExpressionType, ): if columns and named_columns: raise ValueError( @@ -844,10 +883,13 @@ def __init__( def _render_internal(self) -> str: if isinstance(self._columns, dict): cols = ", ".join( - [f"{name} = {value}" for name, value in self._columns.items()] + [ + f"{self._format_id(name)} = {self._format_expr(value)}" + for name, value in self._columns.items() + ] ) else: - cols = ", ".join([f"{col}" for col in self._columns]) + cols = ", ".join([f"{self._format_expr(col)}" for col in self._columns]) return f"EVAL {cols}" @@ -900,7 +942,7 @@ def __init__(self, parent: ESQLBase, input: FieldType, pattern: str): self._pattern = pattern def _render_internal(self) -> str: - return f"GROK {self._input} {json.dumps(self._pattern)}" + return f"GROK {self._format_id(self._input)} {json.dumps(self._pattern)}" class Keep(ESQLBase): @@ -916,7 +958,7 @@ def __init__(self, parent: ESQLBase, *columns: FieldType): self._columns = columns def _render_internal(self) -> str: - return f'KEEP {", ".join([f"{col}" for col in self._columns])}' + return f'KEEP {", ".join([f"{self._format_id(col, allow_patterns=True)}" for col in self._columns])}' class Limit(ESQLBase): @@ -932,7 +974,7 @@ def __init__(self, parent: ESQLBase, max_number_of_rows: int): self._max_number_of_rows = max_number_of_rows def _render_internal(self) -> str: - return f"LIMIT {self._max_number_of_rows}" + return f"LIMIT {json.dumps(self._max_number_of_rows)}" class LookupJoin(ESQLBase): @@ -967,7 +1009,9 @@ def _render_internal(self) -> str: if isinstance(self._lookup_index, str) else self._lookup_index._index._name ) - return f"LOOKUP JOIN {index} ON {self._field}" + return ( + f"LOOKUP JOIN {self._format_index(index)} ON {self._format_id(self._field)}" + ) class MvExpand(ESQLBase): @@ -983,7 +1027,7 @@ def __init__(self, parent: ESQLBase, column: FieldType): self._column = column def _render_internal(self) -> str: - return f"MV_EXPAND {self._column}" + return f"MV_EXPAND {self._format_id(self._column)}" class Rename(ESQLBase): @@ -999,7 +1043,7 @@ def __init__(self, parent: ESQLBase, **columns: FieldType): self._columns = columns def _render_internal(self) -> str: - return f'RENAME {", ".join([f"{old_name} AS {new_name}" for old_name, new_name in self._columns.items()])}' + return f'RENAME {", ".join([f"{self._format_id(old_name)} AS {self._format_id(new_name)}" for old_name, new_name in self._columns.items()])}' class Sample(ESQLBase): @@ -1015,7 +1059,7 @@ def __init__(self, parent: ESQLBase, probability: float): self._probability = probability def _render_internal(self) -> str: - return f"SAMPLE {self._probability}" + return f"SAMPLE {json.dumps(self._probability)}" class Sort(ESQLBase): @@ -1026,12 +1070,16 @@ class Sort(ESQLBase): in a single expression. """ - def __init__(self, parent: ESQLBase, *columns: FieldType): + def __init__(self, parent: ESQLBase, *columns: ExpressionType): super().__init__(parent) self._columns = columns def _render_internal(self) -> str: - return f'SORT {", ".join([f"{col}" for col in self._columns])}' + sorts = [ + " ".join([self._format_id(term) for term in str(col).split(" ")]) + for col in self._columns + ] + return f'SORT {", ".join([f"{sort}" for sort in sorts])}' class Stats(ESQLBase): @@ -1062,14 +1110,17 @@ def by(self, *grouping_expressions: ExpressionType) -> "Stats": def _render_internal(self) -> str: if isinstance(self._expressions, dict): - exprs = [f"{key} = {value}" for key, value in self._expressions.items()] + exprs = [ + f"{self._format_id(key)} = {self._format_expr(value)}" + for key, value in self._expressions.items() + ] else: - exprs = [f"{expr}" for expr in self._expressions] + exprs = [f"{self._format_expr(expr)}" for expr in self._expressions] expression_separator = ",\n " by = ( "" if self._grouping_expressions is None - else f'\n BY {", ".join([f"{expr}" for expr in self._grouping_expressions])}' + else f'\n BY {", ".join([f"{self._format_expr(expr)}" for expr in self._grouping_expressions])}' ) return f'STATS {expression_separator.join([f"{expr}" for expr in exprs])}{by}' @@ -1087,7 +1138,7 @@ def __init__(self, parent: ESQLBase, *expressions: ExpressionType): self._expressions = expressions def _render_internal(self) -> str: - return f'WHERE {" AND ".join([f"{expr}" for expr in self._expressions])}' + return f'WHERE {" AND ".join([f"{self._format_expr(expr)}" for expr in self._expressions])}' def and_(*expressions: InstrumentedExpression) -> "InstrumentedExpression": diff --git a/elasticsearch/esql/functions.py b/elasticsearch/esql/functions.py index 515e3ddfc..96e9111aa 100644 --- a/elasticsearch/esql/functions.py +++ b/elasticsearch/esql/functions.py @@ -18,12 +18,16 @@ import json from typing import Any -from elasticsearch.dsl.document_base import InstrumentedExpression -from elasticsearch.esql.esql import ExpressionType +from ..dsl.document_base import InstrumentedExpression +from ..esql.esql import ESQLBase, ExpressionType def _render(v: Any) -> str: - return json.dumps(v) if not isinstance(v, InstrumentedExpression) else str(v) + return ( + json.dumps(v) + if not isinstance(v, InstrumentedExpression) + else ESQLBase._format_expr(v) + ) def abs(number: ExpressionType) -> InstrumentedExpression: @@ -69,7 +73,9 @@ def atan2( :param y_coordinate: y coordinate. If `null`, the function returns `null`. :param x_coordinate: x coordinate. If `null`, the function returns `null`. """ - return InstrumentedExpression(f"ATAN2({y_coordinate}, {x_coordinate})") + return InstrumentedExpression( + f"ATAN2({_render(y_coordinate)}, {_render(x_coordinate)})" + ) def avg(number: ExpressionType) -> InstrumentedExpression: @@ -114,7 +120,7 @@ def bucket( :param to: End of the range. Can be a number, a date or a date expressed as a string. """ return InstrumentedExpression( - f"BUCKET({_render(field)}, {_render(buckets)}, {from_}, {_render(to)})" + f"BUCKET({_render(field)}, {_render(buckets)}, {_render(from_)}, {_render(to)})" ) @@ -169,7 +175,7 @@ def cidr_match(ip: ExpressionType, block_x: ExpressionType) -> InstrumentedExpre :param ip: IP address of type `ip` (both IPv4 and IPv6 are supported). :param block_x: CIDR block to test the IP against. """ - return InstrumentedExpression(f"CIDR_MATCH({_render(ip)}, {block_x})") + return InstrumentedExpression(f"CIDR_MATCH({_render(ip)}, {_render(block_x)})") def coalesce(first: ExpressionType, rest: ExpressionType) -> InstrumentedExpression: @@ -264,7 +270,7 @@ def date_diff( :param end_timestamp: A string representing an end timestamp """ return InstrumentedExpression( - f"DATE_DIFF({_render(unit)}, {start_timestamp}, {end_timestamp})" + f"DATE_DIFF({_render(unit)}, {_render(start_timestamp)}, {_render(end_timestamp)})" ) @@ -285,7 +291,9 @@ def date_extract( the function returns `null`. :param date: Date expression. If `null`, the function returns `null`. """ - return InstrumentedExpression(f"DATE_EXTRACT({date_part}, {_render(date)})") + return InstrumentedExpression( + f"DATE_EXTRACT({_render(date_part)}, {_render(date)})" + ) def date_format( @@ -301,7 +309,7 @@ def date_format( """ if date_format is not None: return InstrumentedExpression( - f"DATE_FORMAT({json.dumps(date_format)}, {_render(date)})" + f"DATE_FORMAT({_render(date_format)}, {_render(date)})" ) else: return InstrumentedExpression(f"DATE_FORMAT({_render(date)})") @@ -317,7 +325,9 @@ def date_parse( :param date_string: Date expression as a string. If `null` or an empty string, the function returns `null`. """ - return InstrumentedExpression(f"DATE_PARSE({date_pattern}, {date_string})") + return InstrumentedExpression( + f"DATE_PARSE({_render(date_pattern)}, {_render(date_string)})" + ) def date_trunc( @@ -639,7 +649,7 @@ def min_over_time(field: ExpressionType) -> InstrumentedExpression: def multi_match( - query: ExpressionType, fields: ExpressionType, options: ExpressionType = None + query: ExpressionType, *fields: ExpressionType, options: ExpressionType = None ) -> InstrumentedExpression: """Use `MULTI_MATCH` to perform a multi-match query on the specified field. The multi_match query builds on the match query to allow multi-field queries. @@ -651,11 +661,11 @@ def multi_match( """ if options is not None: return InstrumentedExpression( - f"MULTI_MATCH({_render(query)}, {_render(fields)}, {_render(options)})" + f'MULTI_MATCH({_render(query)}, {", ".join([_render(c) for c in fields])}, {_render(options)})' ) else: return InstrumentedExpression( - f"MULTI_MATCH({_render(query)}, {_render(fields)})" + f'MULTI_MATCH({_render(query)}, {", ".join([_render(c) for c in fields])})' ) @@ -929,7 +939,7 @@ def replace( :param new_string: Replacement string. """ return InstrumentedExpression( - f"REPLACE({_render(string)}, {_render(regex)}, {new_string})" + f"REPLACE({_render(string)}, {_render(regex)}, {_render(new_string)})" ) @@ -1004,7 +1014,7 @@ def scalb(d: ExpressionType, scale_factor: ExpressionType) -> InstrumentedExpres :param scale_factor: Numeric expression for the scale factor. If `null`, the function returns `null`. """ - return InstrumentedExpression(f"SCALB({_render(d)}, {scale_factor})") + return InstrumentedExpression(f"SCALB({_render(d)}, {_render(scale_factor)})") def sha1(input: ExpressionType) -> InstrumentedExpression: @@ -1116,7 +1126,7 @@ def st_contains( first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. """ - return InstrumentedExpression(f"ST_CONTAINS({geom_a}, {geom_b})") + return InstrumentedExpression(f"ST_CONTAINS({_render(geom_a)}, {_render(geom_b)})") def st_disjoint( @@ -1135,7 +1145,7 @@ def st_disjoint( first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. """ - return InstrumentedExpression(f"ST_DISJOINT({geom_a}, {geom_b})") + return InstrumentedExpression(f"ST_DISJOINT({_render(geom_a)}, {_render(geom_b)})") def st_distance( @@ -1153,7 +1163,7 @@ def st_distance( also have the same coordinate system as the first. This means it is not possible to combine `geo_point` and `cartesian_point` parameters. """ - return InstrumentedExpression(f"ST_DISTANCE({geom_a}, {geom_b})") + return InstrumentedExpression(f"ST_DISTANCE({_render(geom_a)}, {_render(geom_b)})") def st_envelope(geometry: ExpressionType) -> InstrumentedExpression: @@ -1208,7 +1218,7 @@ def st_geohash_to_long(grid_id: ExpressionType) -> InstrumentedExpression: :param grid_id: Input geohash grid-id. The input can be a single- or multi-valued column or an expression. """ - return InstrumentedExpression(f"ST_GEOHASH_TO_LONG({grid_id})") + return InstrumentedExpression(f"ST_GEOHASH_TO_LONG({_render(grid_id)})") def st_geohash_to_string(grid_id: ExpressionType) -> InstrumentedExpression: @@ -1218,7 +1228,7 @@ def st_geohash_to_string(grid_id: ExpressionType) -> InstrumentedExpression: :param grid_id: Input geohash grid-id. The input can be a single- or multi-valued column or an expression. """ - return InstrumentedExpression(f"ST_GEOHASH_TO_STRING({grid_id})") + return InstrumentedExpression(f"ST_GEOHASH_TO_STRING({_render(grid_id)})") def st_geohex( @@ -1254,7 +1264,7 @@ def st_geohex_to_long(grid_id: ExpressionType) -> InstrumentedExpression: :param grid_id: Input geohex grid-id. The input can be a single- or multi-valued column or an expression. """ - return InstrumentedExpression(f"ST_GEOHEX_TO_LONG({grid_id})") + return InstrumentedExpression(f"ST_GEOHEX_TO_LONG({_render(grid_id)})") def st_geohex_to_string(grid_id: ExpressionType) -> InstrumentedExpression: @@ -1264,7 +1274,7 @@ def st_geohex_to_string(grid_id: ExpressionType) -> InstrumentedExpression: :param grid_id: Input Geohex grid-id. The input can be a single- or multi-valued column or an expression. """ - return InstrumentedExpression(f"ST_GEOHEX_TO_STRING({grid_id})") + return InstrumentedExpression(f"ST_GEOHEX_TO_STRING({_render(grid_id)})") def st_geotile( @@ -1300,7 +1310,7 @@ def st_geotile_to_long(grid_id: ExpressionType) -> InstrumentedExpression: :param grid_id: Input geotile grid-id. The input can be a single- or multi-valued column or an expression. """ - return InstrumentedExpression(f"ST_GEOTILE_TO_LONG({grid_id})") + return InstrumentedExpression(f"ST_GEOTILE_TO_LONG({_render(grid_id)})") def st_geotile_to_string(grid_id: ExpressionType) -> InstrumentedExpression: @@ -1310,7 +1320,7 @@ def st_geotile_to_string(grid_id: ExpressionType) -> InstrumentedExpression: :param grid_id: Input geotile grid-id. The input can be a single- or multi-valued column or an expression. """ - return InstrumentedExpression(f"ST_GEOTILE_TO_STRING({grid_id})") + return InstrumentedExpression(f"ST_GEOTILE_TO_STRING({_render(grid_id)})") def st_intersects( @@ -1330,7 +1340,9 @@ def st_intersects( first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. """ - return InstrumentedExpression(f"ST_INTERSECTS({geom_a}, {geom_b})") + return InstrumentedExpression( + f"ST_INTERSECTS({_render(geom_a)}, {_render(geom_b)})" + ) def st_within(geom_a: ExpressionType, geom_b: ExpressionType) -> InstrumentedExpression: @@ -1346,7 +1358,7 @@ def st_within(geom_a: ExpressionType, geom_b: ExpressionType) -> InstrumentedExp first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. """ - return InstrumentedExpression(f"ST_WITHIN({geom_a}, {geom_b})") + return InstrumentedExpression(f"ST_WITHIN({_render(geom_a)}, {_render(geom_b)})") def st_x(point: ExpressionType) -> InstrumentedExpression: diff --git a/elasticsearch/helpers/__init__.py b/elasticsearch/helpers/__init__.py index 67676932b..6f8f24c21 100644 --- a/elasticsearch/helpers/__init__.py +++ b/elasticsearch/helpers/__init__.py @@ -19,12 +19,21 @@ from .._utils import fixup_module_metadata from .actions import _chunk_actions # noqa: F401 from .actions import _process_bulk_chunk # noqa: F401 -from .actions import bulk, expand_action, parallel_bulk, reindex, scan, streaming_bulk +from .actions import ( + BULK_FLUSH, + bulk, + expand_action, + parallel_bulk, + reindex, + scan, + streaming_bulk, +) from .errors import BulkIndexError, ScanError __all__ = [ "BulkIndexError", "ScanError", + "BULK_FLUSH", "expand_action", "streaming_bulk", "bulk", diff --git a/elasticsearch/helpers/actions.py b/elasticsearch/helpers/actions.py index d1a43a8dc..79197a1e4 100644 --- a/elasticsearch/helpers/actions.py +++ b/elasticsearch/helpers/actions.py @@ -16,9 +16,10 @@ # under the License. import logging +import queue import time +from enum import Enum from operator import methodcaller -from queue import Queue from typing import ( Any, Callable, @@ -37,13 +38,21 @@ from elastic_transport import OpenTelemetrySpan from .. import Elasticsearch -from ..compat import to_bytes +from ..compat import safe_thread, to_bytes from ..exceptions import ApiError, NotFoundError, TransportError from ..serializer import Serializer from .errors import BulkIndexError, ScanError logger = logging.getLogger("elasticsearch.helpers") + +class BulkMeta(Enum): + flush = 1 + done = 2 + + +BULK_FLUSH = BulkMeta.flush + _TYPE_BULK_ACTION = Union[bytes, str, Dict[str, Any]] _TYPE_BULK_ACTION_HEADER = Dict[str, Any] _TYPE_BULK_ACTION_BODY = Union[None, bytes, Dict[str, Any]] @@ -51,6 +60,13 @@ _TYPE_BULK_ACTION_HEADER, _TYPE_BULK_ACTION_BODY ] +_TYPE_BULK_ACTION_WITH_META = Union[bytes, str, Dict[str, Any], BulkMeta] +_TYPE_BULK_ACTION_HEADER_WITH_META = Union[Dict[str, Any], BulkMeta] +_TYPE_BULK_ACTION_HEADER_WITH_META_AND_BODY = Union[ + Tuple[_TYPE_BULK_ACTION_HEADER, _TYPE_BULK_ACTION_BODY], + Tuple[BulkMeta, Any], +] + def expand_action(data: _TYPE_BULK_ACTION) -> _TYPE_BULK_ACTION_HEADER_AND_BODY: """ @@ -139,7 +155,9 @@ def __init__( ] = [] def feed( - self, action: _TYPE_BULK_ACTION_HEADER, data: _TYPE_BULK_ACTION_BODY + self, + action: _TYPE_BULK_ACTION_HEADER_WITH_META, + data: _TYPE_BULK_ACTION_BODY, ) -> Optional[ Tuple[ List[ @@ -152,23 +170,25 @@ def feed( ] ]: ret = None - raw_action = action - raw_data = data - action_bytes = to_bytes(self.serializer.dumps(action), "utf-8") - # +1 to account for the trailing new line character - cur_size = len(action_bytes) + 1 - - data_bytes: Optional[bytes] - if data is not None: - data_bytes = to_bytes(self.serializer.dumps(data), "utf-8") - cur_size += len(data_bytes) + 1 - else: - data_bytes = None + action_bytes = b"" + data_bytes: Optional[bytes] = None + cur_size = 0 + if not isinstance(action, BulkMeta): + action_bytes = to_bytes(self.serializer.dumps(action), "utf-8") + # +1 to account for the trailing new line character + cur_size = len(action_bytes) + 1 + + if data is not None: + data_bytes = to_bytes(self.serializer.dumps(data), "utf-8") + cur_size += len(data_bytes) + 1 + else: + data_bytes = None # full chunk, send it and start a new one if self.bulk_actions and ( self.size + cur_size > self.max_chunk_bytes or self.action_count == self.chunk_size + or (action == BulkMeta.flush and self.bulk_actions) ): ret = (self.bulk_data, self.bulk_actions) self.bulk_actions = [] @@ -176,15 +196,16 @@ def feed( self.size = 0 self.action_count = 0 - self.bulk_actions.append(action_bytes) - if data_bytes is not None: - self.bulk_actions.append(data_bytes) - self.bulk_data.append((raw_action, raw_data)) - else: - self.bulk_data.append((raw_action,)) + if not isinstance(action, BulkMeta): + self.bulk_actions.append(action_bytes) + if data_bytes is not None: + self.bulk_actions.append(data_bytes) + self.bulk_data.append((action, data)) + else: + self.bulk_data.append((action,)) - self.size += cur_size - self.action_count += 1 + self.size += cur_size + self.action_count += 1 return ret def flush( @@ -209,9 +230,10 @@ def flush( def _chunk_actions( - actions: Iterable[_TYPE_BULK_ACTION_HEADER_AND_BODY], + actions: Iterable[_TYPE_BULK_ACTION_HEADER_WITH_META_AND_BODY], chunk_size: int, max_chunk_bytes: int, + flush_after_seconds: Optional[float], serializer: Serializer, ) -> Iterable[ Tuple[ @@ -231,10 +253,41 @@ def _chunk_actions( chunker = _ActionChunker( chunk_size=chunk_size, max_chunk_bytes=max_chunk_bytes, serializer=serializer ) - for action, data in actions: - ret = chunker.feed(action, data) - if ret: - yield ret + + if not flush_after_seconds: + for action, data in actions: + ret = chunker.feed(action, data) + if ret: + yield ret + else: + item_queue: queue.Queue[_TYPE_BULK_ACTION_HEADER_WITH_META_AND_BODY] = ( + queue.Queue() + ) + + def get_items() -> None: + try: + for item in actions: + item_queue.put(item) + finally: + # make sure we signal the end even if there is an exception + item_queue.put((BulkMeta.done, None)) + + with safe_thread(get_items): + timeout: Optional[float] = flush_after_seconds + while True: + try: + action, data = item_queue.get(timeout=timeout) + timeout = flush_after_seconds + except queue.Empty: + action, data = BulkMeta.flush, None + timeout = None + + if action is BulkMeta.done: + break + ret = chunker.feed(action, data) + if ret: + yield ret + ret = chunker.flush() if ret: yield ret @@ -361,9 +414,10 @@ def _process_bulk_chunk( def streaming_bulk( client: Elasticsearch, - actions: Iterable[_TYPE_BULK_ACTION], + actions: Iterable[_TYPE_BULK_ACTION_WITH_META], chunk_size: int = 500, max_chunk_bytes: int = 100 * 1024 * 1024, + flush_after_seconds: Optional[float] = None, raise_on_error: bool = True, expand_action_callback: Callable[ [_TYPE_BULK_ACTION], _TYPE_BULK_ACTION_HEADER_AND_BODY @@ -397,6 +451,9 @@ def streaming_bulk( :arg actions: iterable containing the actions to be executed :arg chunk_size: number of docs in one chunk sent to es (default: 500) :arg max_chunk_bytes: the maximum size of the request in bytes (default: 100MB) + :arg flush_after_seconds: time in seconds after which a chunk is written even + if hasn't reached `chunk_size` or `max_chunk_bytes`. Set to 0 to not use a + timeout-based flush. (default: 0) :arg raise_on_error: raise ``BulkIndexError`` containing errors (as `.errors`) from the execution of the last chunk when some occur. By default we raise. :arg raise_on_exception: if ``False`` then don't propagate exceptions from @@ -425,6 +482,13 @@ def streaming_bulk( serializer = client.transport.serializers.get_serializer("application/json") + def expand_action_with_meta( + data: _TYPE_BULK_ACTION_WITH_META, + ) -> _TYPE_BULK_ACTION_HEADER_WITH_META_AND_BODY: + if isinstance(data, BulkMeta): + return data, None + return expand_action_callback(data) + bulk_data: List[ Union[ Tuple[_TYPE_BULK_ACTION_HEADER], @@ -433,9 +497,10 @@ def streaming_bulk( ] bulk_actions: List[bytes] for bulk_data, bulk_actions in _chunk_actions( - map(expand_action_callback, actions), + map(expand_action_with_meta, actions), chunk_size, max_chunk_bytes, + flush_after_seconds, serializer, ): for attempt in range(max_retries + 1): @@ -557,6 +622,7 @@ def parallel_bulk( thread_count: int = 4, chunk_size: int = 500, max_chunk_bytes: int = 100 * 1024 * 1024, + flush_after_seconds: Optional[float] = None, queue_size: int = 4, expand_action_callback: Callable[ [_TYPE_BULK_ACTION], _TYPE_BULK_ACTION_HEADER_AND_BODY @@ -573,6 +639,9 @@ def parallel_bulk( :arg thread_count: size of the threadpool to use for the bulk requests :arg chunk_size: number of docs in one chunk sent to es (default: 500) :arg max_chunk_bytes: the maximum size of the request in bytes (default: 100MB) + :arg flush_after_seconds: time in seconds after which a chunk is written even + if hasn't reached `chunk_size` or `max_chunk_bytes`. Set to 0 to not use a + timeout-based flush. (default: 0) :arg raise_on_error: raise ``BulkIndexError`` containing errors (as `.errors`) from the execution of the last chunk when some occur. By default we raise. :arg raise_on_exception: if ``False`` then don't propagate exceptions from @@ -596,7 +665,7 @@ def _setup_queues(self) -> None: super()._setup_queues() # type: ignore[misc] # The queue must be at least the size of the number of threads to # prevent hanging when inserting sentinel values during teardown. - self._inqueue: Queue[ + self._inqueue: queue.Queue[ Tuple[ List[ Union[ @@ -605,7 +674,7 @@ def _setup_queues(self) -> None: ], List[bytes], ] - ] = Queue(max(queue_size, thread_count)) + ] = queue.Queue(max(queue_size, thread_count)) self._quick_put = self._inqueue.put with client._otel.helpers_span("helpers.parallel_bulk") as otel_span: @@ -625,7 +694,11 @@ def _setup_queues(self) -> None: ) ), _chunk_actions( - expanded_actions, chunk_size, max_chunk_bytes, serializer + expanded_actions, + chunk_size, + max_chunk_bytes, + flush_after_seconds, + serializer, ), ): yield from result diff --git a/elasticsearch/helpers/vectorstore/__init__.py b/elasticsearch/helpers/vectorstore/__init__.py index 30a4c3d6e..d7874ffe2 100644 --- a/elasticsearch/helpers/vectorstore/__init__.py +++ b/elasticsearch/helpers/vectorstore/__init__.py @@ -15,31 +15,31 @@ # specific language governing permissions and limitations # under the License. -from elasticsearch.helpers.vectorstore._async.embedding_service import ( +from ...helpers.vectorstore._async.embedding_service import ( AsyncElasticsearchEmbeddings, AsyncEmbeddingService, ) -from elasticsearch.helpers.vectorstore._async.strategies import ( +from ...helpers.vectorstore._async.strategies import ( AsyncBM25Strategy, AsyncDenseVectorScriptScoreStrategy, AsyncDenseVectorStrategy, AsyncRetrievalStrategy, AsyncSparseVectorStrategy, ) -from elasticsearch.helpers.vectorstore._async.vectorstore import AsyncVectorStore -from elasticsearch.helpers.vectorstore._sync.embedding_service import ( +from ...helpers.vectorstore._async.vectorstore import AsyncVectorStore +from ...helpers.vectorstore._sync.embedding_service import ( ElasticsearchEmbeddings, EmbeddingService, ) -from elasticsearch.helpers.vectorstore._sync.strategies import ( +from ...helpers.vectorstore._sync.strategies import ( BM25Strategy, DenseVectorScriptScoreStrategy, DenseVectorStrategy, RetrievalStrategy, SparseVectorStrategy, ) -from elasticsearch.helpers.vectorstore._sync.vectorstore import VectorStore -from elasticsearch.helpers.vectorstore._utils import DistanceMetric +from ...helpers.vectorstore._sync.vectorstore import VectorStore +from ...helpers.vectorstore._utils import DistanceMetric __all__ = [ "AsyncBM25Strategy", diff --git a/elasticsearch/helpers/vectorstore/_async/_utils.py b/elasticsearch/helpers/vectorstore/_async/_utils.py index 67b6b6a27..210ef25c7 100644 --- a/elasticsearch/helpers/vectorstore/_async/_utils.py +++ b/elasticsearch/helpers/vectorstore/_async/_utils.py @@ -15,7 +15,7 @@ # specific language governing permissions and limitations # under the License. -from elasticsearch import AsyncElasticsearch, BadRequestError, NotFoundError +from .... import AsyncElasticsearch, BadRequestError, NotFoundError async def model_must_be_deployed(client: AsyncElasticsearch, model_id: str) -> None: diff --git a/elasticsearch/helpers/vectorstore/_async/embedding_service.py b/elasticsearch/helpers/vectorstore/_async/embedding_service.py index 20005b665..3b779dc26 100644 --- a/elasticsearch/helpers/vectorstore/_async/embedding_service.py +++ b/elasticsearch/helpers/vectorstore/_async/embedding_service.py @@ -18,8 +18,8 @@ from abc import ABC, abstractmethod from typing import List -from elasticsearch import AsyncElasticsearch -from elasticsearch._version import __versionstr__ as lib_version +from .... import AsyncElasticsearch +from ...._version import __versionstr__ as lib_version class AsyncEmbeddingService(ABC): diff --git a/elasticsearch/helpers/vectorstore/_async/strategies.py b/elasticsearch/helpers/vectorstore/_async/strategies.py index 2a52bcb4b..327a53e12 100644 --- a/elasticsearch/helpers/vectorstore/_async/strategies.py +++ b/elasticsearch/helpers/vectorstore/_async/strategies.py @@ -18,9 +18,9 @@ from abc import ABC, abstractmethod from typing import Any, Dict, List, Optional, Tuple, Union, cast -from elasticsearch import AsyncElasticsearch -from elasticsearch.helpers.vectorstore._async._utils import model_must_be_deployed -from elasticsearch.helpers.vectorstore._utils import DistanceMetric +from .... import AsyncElasticsearch +from ....helpers.vectorstore._async._utils import model_must_be_deployed +from ....helpers.vectorstore._utils import DistanceMetric class AsyncRetrievalStrategy(ABC): diff --git a/elasticsearch/helpers/vectorstore/_async/vectorstore.py b/elasticsearch/helpers/vectorstore/_async/vectorstore.py index 3b8c1e9e9..71a2274a0 100644 --- a/elasticsearch/helpers/vectorstore/_async/vectorstore.py +++ b/elasticsearch/helpers/vectorstore/_async/vectorstore.py @@ -19,14 +19,14 @@ import uuid from typing import Any, Callable, Dict, List, Optional -from elasticsearch import AsyncElasticsearch -from elasticsearch._version import __versionstr__ as lib_version -from elasticsearch.helpers import BulkIndexError, async_bulk -from elasticsearch.helpers.vectorstore import ( +from .... import AsyncElasticsearch +from ...._version import __versionstr__ as lib_version +from ....helpers import BulkIndexError, async_bulk +from ....helpers.vectorstore import ( AsyncEmbeddingService, AsyncRetrievalStrategy, ) -from elasticsearch.helpers.vectorstore._utils import maximal_marginal_relevance +from ....helpers.vectorstore._utils import maximal_marginal_relevance logger = logging.getLogger(__name__) diff --git a/elasticsearch/helpers/vectorstore/_sync/_utils.py b/elasticsearch/helpers/vectorstore/_sync/_utils.py index 496aec970..b6e1b66f5 100644 --- a/elasticsearch/helpers/vectorstore/_sync/_utils.py +++ b/elasticsearch/helpers/vectorstore/_sync/_utils.py @@ -15,7 +15,7 @@ # specific language governing permissions and limitations # under the License. -from elasticsearch import BadRequestError, Elasticsearch, NotFoundError +from .... import BadRequestError, Elasticsearch, NotFoundError def model_must_be_deployed(client: Elasticsearch, model_id: str) -> None: diff --git a/elasticsearch/helpers/vectorstore/_sync/embedding_service.py b/elasticsearch/helpers/vectorstore/_sync/embedding_service.py index 5b0163d98..b597cdd71 100644 --- a/elasticsearch/helpers/vectorstore/_sync/embedding_service.py +++ b/elasticsearch/helpers/vectorstore/_sync/embedding_service.py @@ -18,8 +18,8 @@ from abc import ABC, abstractmethod from typing import List -from elasticsearch import Elasticsearch -from elasticsearch._version import __versionstr__ as lib_version +from .... import Elasticsearch +from ...._version import __versionstr__ as lib_version class EmbeddingService(ABC): diff --git a/elasticsearch/helpers/vectorstore/_sync/strategies.py b/elasticsearch/helpers/vectorstore/_sync/strategies.py index af89edf8d..0cb86a30f 100644 --- a/elasticsearch/helpers/vectorstore/_sync/strategies.py +++ b/elasticsearch/helpers/vectorstore/_sync/strategies.py @@ -18,9 +18,9 @@ from abc import ABC, abstractmethod from typing import Any, Dict, List, Optional, Tuple, Union, cast -from elasticsearch import Elasticsearch -from elasticsearch.helpers.vectorstore._sync._utils import model_must_be_deployed -from elasticsearch.helpers.vectorstore._utils import DistanceMetric +from .... import Elasticsearch +from ....helpers.vectorstore._sync._utils import model_must_be_deployed +from ....helpers.vectorstore._utils import DistanceMetric class RetrievalStrategy(ABC): diff --git a/elasticsearch/helpers/vectorstore/_sync/vectorstore.py b/elasticsearch/helpers/vectorstore/_sync/vectorstore.py index 6a6a5ee2a..bbb159bb6 100644 --- a/elasticsearch/helpers/vectorstore/_sync/vectorstore.py +++ b/elasticsearch/helpers/vectorstore/_sync/vectorstore.py @@ -19,14 +19,14 @@ import uuid from typing import Any, Callable, Dict, List, Optional -from elasticsearch import Elasticsearch -from elasticsearch._version import __versionstr__ as lib_version -from elasticsearch.helpers import BulkIndexError, bulk -from elasticsearch.helpers.vectorstore import ( +from .... import Elasticsearch +from ...._version import __versionstr__ as lib_version +from ....helpers import BulkIndexError, bulk +from ....helpers.vectorstore import ( EmbeddingService, RetrievalStrategy, ) -from elasticsearch.helpers.vectorstore._utils import maximal_marginal_relevance +from ....helpers.vectorstore._utils import maximal_marginal_relevance logger = logging.getLogger(__name__) diff --git a/examples/dsl/async/esql_employees.py b/examples/dsl/async/esql_employees.py new file mode 100644 index 000000000..986c84235 --- /dev/null +++ b/examples/dsl/async/esql_employees.py @@ -0,0 +1,170 @@ +# Licensed to Elasticsearch B.V. under one or more contributor +# license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright +# ownership. Elasticsearch B.V. licenses this file to you under +# the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +""" +# ES|QL query builder example + +Requirements: + +$ pip install "elasticsearch[async]" faker + +To run the example: + +$ python esql_employees.py "name to search" + +The index will be created automatically with a list of 1000 randomly generated +employees if it does not exist. Add `--recreate-index` or `-r` to the command +to regenerate it. + +Examples: + +$ python esql_employees "Mark" # employees named Mark (first or last names) +$ python esql_employees "Sarah" --limit 10 # up to 10 employees named Sarah +$ python esql_employees "Sam" --sort height # sort results by height +$ python esql_employees "Sam" --sort name # sort results by last name +""" + +import argparse +import asyncio +import os +import random + +from faker import Faker + +from elasticsearch.dsl import AsyncDocument, InnerDoc, M, async_connections +from elasticsearch.esql import ESQLBase +from elasticsearch.esql.functions import concat, multi_match + +fake = Faker() + + +class Address(InnerDoc): + address: M[str] + city: M[str] + zip_code: M[str] + + +class Employee(AsyncDocument): + emp_no: M[int] + first_name: M[str] + last_name: M[str] + height: M[float] + still_hired: M[bool] + address: M[Address] + + class Index: + name = "employees" + + @property + def name(self) -> str: + return f"{self.first_name} {self.last_name}" + + def __repr__(self) -> str: + return f"" + + +async def create(num_employees: int = 1000) -> None: + print("Creating a new employee index...") + if await Employee._index.exists(): + await Employee._index.delete() + await Employee.init() + + for i in range(num_employees): + address = Address( + address=fake.address(), city=fake.city(), zip_code=fake.zipcode() + ) + emp = Employee( + emp_no=10000 + i, + first_name=fake.first_name(), + last_name=fake.last_name(), + height=int((random.random() * 0.8 + 1.5) * 1000) / 1000, + still_hired=random.random() >= 0.5, + address=address, + ) + await emp.save() + await Employee._index.refresh() + + +async def search(query: str, limit: int, sort: str) -> None: + q: ESQLBase = ( + Employee.esql_from() + .where(multi_match(query, Employee.first_name, Employee.last_name)) + .eval(full_name=concat(Employee.first_name, " ", Employee.last_name)) + ) + if sort == "height": + q = q.sort(Employee.height.desc()) + elif sort == "name": + q = q.sort(Employee.last_name.asc()) + q = q.limit(limit) + async for result in Employee.esql_execute(q, return_additional=True): + assert type(result) == tuple + employee = result[0] + full_name = result[1]["full_name"] + print( + f"{full_name:<20}", + f"{'Hired' if employee.still_hired else 'Not hired':<10}", + f"{employee.height:5.2f}m", + f"{employee.address.city:<20}", + ) + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description="Employee ES|QL example") + parser.add_argument( + "--recreate-index", + "-r", + action="http://github.com/store_true", + help="Recreate and populate the index", + ) + parser.add_argument( + "--limit", + action="http://github.com/store", + type=int, + default=100, + help="Maximum number or employees to return (default: 100)", + ) + parser.add_argument( + "--sort", + action="http://github.com/store", + type=str, + default=None, + help='Sort by "name" (ascending) or by "height" (descending) (default: no sorting)', + ) + parser.add_argument( + "query", action="http://github.com/store", help="The name or partial name to search for" + ) + return parser.parse_args() + + +async def main() -> None: + args = parse_args() + + # initiate the default connection to elasticsearch + async_connections.create_connection(hosts=[os.environ["ELASTICSEARCH_URL"]]) + + if args.recreate_index or not await Employee._index.exists(): + await create() + await Employee.init() + + await search(args.query, args.limit, args.sort) + + # close the connection + await async_connections.get_connection().close() + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/examples/dsl/esql_employees.py b/examples/dsl/esql_employees.py new file mode 100644 index 000000000..364a2c2d5 --- /dev/null +++ b/examples/dsl/esql_employees.py @@ -0,0 +1,169 @@ +# Licensed to Elasticsearch B.V. under one or more contributor +# license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright +# ownership. Elasticsearch B.V. licenses this file to you under +# the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +""" +# ES|QL query builder example + +Requirements: + +$ pip install elasticsearch faker + +To run the example: + +$ python esql_employees.py "name to search" + +The index will be created automatically with a list of 1000 randomly generated +employees if it does not exist. Add `--recreate-index` or `-r` to the command +to regenerate it. + +Examples: + +$ python esql_employees "Mark" # employees named Mark (first or last names) +$ python esql_employees "Sarah" --limit 10 # up to 10 employees named Sarah +$ python esql_employees "Sam" --sort height # sort results by height +$ python esql_employees "Sam" --sort name # sort results by last name +""" + +import argparse +import os +import random + +from faker import Faker + +from elasticsearch.dsl import Document, InnerDoc, M, connections +from elasticsearch.esql import ESQLBase +from elasticsearch.esql.functions import concat, multi_match + +fake = Faker() + + +class Address(InnerDoc): + address: M[str] + city: M[str] + zip_code: M[str] + + +class Employee(Document): + emp_no: M[int] + first_name: M[str] + last_name: M[str] + height: M[float] + still_hired: M[bool] + address: M[Address] + + class Index: + name = "employees" + + @property + def name(self) -> str: + return f"{self.first_name} {self.last_name}" + + def __repr__(self) -> str: + return f"" + + +def create(num_employees: int = 1000) -> None: + print("Creating a new employee index...") + if Employee._index.exists(): + Employee._index.delete() + Employee.init() + + for i in range(num_employees): + address = Address( + address=fake.address(), city=fake.city(), zip_code=fake.zipcode() + ) + emp = Employee( + emp_no=10000 + i, + first_name=fake.first_name(), + last_name=fake.last_name(), + height=int((random.random() * 0.8 + 1.5) * 1000) / 1000, + still_hired=random.random() >= 0.5, + address=address, + ) + emp.save() + Employee._index.refresh() + + +def search(query: str, limit: int, sort: str) -> None: + q: ESQLBase = ( + Employee.esql_from() + .where(multi_match(query, Employee.first_name, Employee.last_name)) + .eval(full_name=concat(Employee.first_name, " ", Employee.last_name)) + ) + if sort == "height": + q = q.sort(Employee.height.desc()) + elif sort == "name": + q = q.sort(Employee.last_name.asc()) + q = q.limit(limit) + for result in Employee.esql_execute(q, return_additional=True): + assert type(result) == tuple + employee = result[0] + full_name = result[1]["full_name"] + print( + f"{full_name:<20}", + f"{'Hired' if employee.still_hired else 'Not hired':<10}", + f"{employee.height:5.2f}m", + f"{employee.address.city:<20}", + ) + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description="Employee ES|QL example") + parser.add_argument( + "--recreate-index", + "-r", + action="http://github.com/store_true", + help="Recreate and populate the index", + ) + parser.add_argument( + "--limit", + action="http://github.com/store", + type=int, + default=100, + help="Maximum number or employees to return (default: 100)", + ) + parser.add_argument( + "--sort", + action="http://github.com/store", + type=str, + default=None, + help='Sort by "name" (ascending) or by "height" (descending) (default: no sorting)', + ) + parser.add_argument( + "query", action="http://github.com/store", help="The name or partial name to search for" + ) + return parser.parse_args() + + +def main() -> None: + args = parse_args() + + # initiate the default connection to elasticsearch + connections.create_connection(hosts=[os.environ["ELASTICSEARCH_URL"]]) + + if args.recreate_index or not Employee._index.exists(): + create() + Employee.init() + + search(args.query, args.limit, args.sort) + + # close the connection + connections.get_connection().close() + + +if __name__ == "__main__": + main() diff --git a/examples/dsl/semantic_text.py b/examples/dsl/semantic_text.py index 8d552a2aa..6f4bb8f7d 100644 --- a/examples/dsl/semantic_text.py +++ b/examples/dsl/semantic_text.py @@ -21,7 +21,7 @@ Requirements: -$ pip install "elasticsearch" tqdm +$ pip install elasticsearch tqdm Before running this example, an ELSER inference endpoint must be created in the Elasticsearch cluster. This can be done manually from Kibana, or with the diff --git a/examples/dsl/sparse_vectors.py b/examples/dsl/sparse_vectors.py index a92e82026..c328769eb 100644 --- a/examples/dsl/sparse_vectors.py +++ b/examples/dsl/sparse_vectors.py @@ -20,7 +20,7 @@ Requirements: -$ pip install nltk tqdm "elasticsearch" +$ pip install nltk tqdm elasticsearch Before running this example, the ELSER v2 model must be downloaded and deployed to the Elasticsearch cluster, and an ingest pipeline must be defined. This can diff --git a/examples/dsl/vectors.py b/examples/dsl/vectors.py index 3afd76991..b4c700b71 100644 --- a/examples/dsl/vectors.py +++ b/examples/dsl/vectors.py @@ -20,7 +20,7 @@ Requirements: -$ pip install nltk sentence_transformers tqdm "elasticsearch" +$ pip install nltk sentence_transformers tqdm elasticsearch To run the example: diff --git a/noxfile.py b/noxfile.py index d5a6099e7..833a2ee1e 100644 --- a/noxfile.py +++ b/noxfile.py @@ -44,14 +44,14 @@ def pytest_argv(): ] -@nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13"]) +@nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]) def test(session): session.install("-e", ".[dev]", env=INSTALL_ENV, silent=False) session.run(*pytest_argv(), *session.posargs) -@nox.session(python=["3.9", "3.13"]) +@nox.session(python=["3.10", "3.14"]) def test_otel(session): session.install( ".[dev]", @@ -60,7 +60,7 @@ def test_otel(session): silent=False, ) - argv = pytest_argv() + ["-m", "otel"] + argv = pytest_argv() + ["-m", "otel"] + session.posargs session.run(*argv, env={"TEST_WITH_OTEL": "1"}) diff --git a/pyproject.toml b/pyproject.toml index 6c81fc2b3..19307fe84 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -73,12 +73,10 @@ dev = [ "orjson", "numpy", "simsimd", - "pyarrow", + "pyarrow; python_version<'3.14'", "pandas", "mapbox-vector-tile", "jinja2", - "nltk", - "sentence_transformers", "tqdm", "mypy", "pyright", @@ -99,7 +97,7 @@ Homepage = "https://github.com/elastic/elasticsearch-py" [tool.hatch.version] path = "elasticsearch/_version.py" -pattern = "__versionstr__ = \"(?P[^']+)\"" +pattern = "__versionstr__ = \"(?P[^']+?)\"" [tool.hatch.build.targets.sdist] include = [ diff --git a/test_elasticsearch/test_async/test_server/conftest.py b/test_elasticsearch/test_async/test_server/conftest.py index 623646e7d..90acae91a 100644 --- a/test_elasticsearch/test_async/test_server/conftest.py +++ b/test_elasticsearch/test_async/test_server/conftest.py @@ -43,7 +43,7 @@ async def async_client_factory(elasticsearch_url): await client.close() -@pytest.fixture(scope="function") +@pytest_asyncio.fixture(scope="function") def async_client(async_client_factory): try: yield async_client_factory diff --git a/test_elasticsearch/test_async/test_server/test_helpers.py b/test_elasticsearch/test_async/test_server/test_helpers.py index a235784be..219b81b83 100644 --- a/test_elasticsearch/test_async/test_server/test_helpers.py +++ b/test_elasticsearch/test_async/test_server/test_helpers.py @@ -17,6 +17,7 @@ import asyncio import logging +import time from datetime import datetime, timedelta, timezone from unittest.mock import MagicMock, call, patch @@ -123,6 +124,45 @@ def sync_gen(): "_source" ] + async def test_explicit_flushes(self, async_client): + async def async_gen(): + yield {"answer": 2, "_id": 0} + yield {"answer": 1, "_id": 1} + yield helpers.BULK_FLUSH + await asyncio.sleep(0.5) + yield {"answer": 2, "_id": 2} + + timestamps = [] + async for ok, item in helpers.async_streaming_bulk( + async_client, async_gen(), index="test-index", refresh=True + ): + timestamps.append(time.time()) + assert ok + + # make sure there is a pause between the writing of the 2nd and 3rd items + assert timestamps[2] - timestamps[1] > (timestamps[1] - timestamps[0]) * 2 + + async def test_timeout_flushes(self, async_client): + async def async_gen(): + yield {"answer": 2, "_id": 0} + yield {"answer": 1, "_id": 1} + await asyncio.sleep(0.5) + yield {"answer": 2, "_id": 2} + + timestamps = [] + async for ok, item in helpers.async_streaming_bulk( + async_client, + async_gen(), + index="test-index", + refresh=True, + flush_after_seconds=0.05, + ): + assert ok + timestamps.append(time.time()) + + # make sure there is a pause between the writing of the 2nd and 3rd items + assert timestamps[2] - timestamps[1] > (timestamps[1] - timestamps[0]) * 2 + async def test_all_errors_from_chunk_are_raised_on_failure(self, async_client): await async_client.indices.create( index="i", diff --git a/test_elasticsearch/test_client/test_utils.py b/test_elasticsearch/test_client/test_utils.py index e4713ff1c..714c727aa 100644 --- a/test_elasticsearch/test_client/test_utils.py +++ b/test_elasticsearch/test_client/test_utils.py @@ -20,7 +20,12 @@ import pytest -from elasticsearch._sync.client.utils import Stability, _quote, _stability_warning +from elasticsearch._sync.client.utils import ( + Stability, + Visibility, + _availability_warning, + _quote, +) from elasticsearch.exceptions import GeneralAvailabilityWarning @@ -43,10 +48,10 @@ def test_handles_unicode2(): assert "%E4%B8%AD*%E6%96%87," == _quote(string) -class TestStabilityWarning: +class TestAvailabilityWarning: def test_default(self): - @_stability_warning(stability=Stability.STABLE) + @_availability_warning(stability=Stability.STABLE) def func_default(*args, **kwargs): pass @@ -56,7 +61,7 @@ def func_default(*args, **kwargs): def test_beta(self, recwarn): - @_stability_warning(stability=Stability.BETA) + @_availability_warning(stability=Stability.BETA) def func_beta(*args, **kwargs): pass @@ -68,7 +73,7 @@ def func_beta(*args, **kwargs): def test_experimental(self, recwarn): - @_stability_warning(stability=Stability.EXPERIMENTAL) + @_availability_warning(stability=Stability.EXPERIMENTAL) def func_experimental(*args, **kwargs): pass @@ -77,3 +82,29 @@ def func_experimental(*args, **kwargs): match="This API is in technical preview and may be changed or removed in a future release.", ): func_experimental() + + def test_private(self, recwarn): + + @_availability_warning( + stability=Stability.STABLE, visibility=Visibility.PRIVATE + ) + def func_private(*args, **kwargs): + pass + + with pytest.warns( + GeneralAvailabilityWarning, + match="This API is private.", + ): + func_private() + + def test_private_and_beta(self, recwarn): + + @_availability_warning(stability=Stability.BETA, visibility=Visibility.PRIVATE) + def func_private_and_beta(*args, **kwargs): + pass + + with pytest.warns( + GeneralAvailabilityWarning, + match="This API is private.", + ): + func_private_and_beta() diff --git a/test_elasticsearch/test_dsl/_async/test_esql.py b/test_elasticsearch/test_dsl/_async/test_esql.py deleted file mode 100644 index 7aacb833c..000000000 --- a/test_elasticsearch/test_dsl/_async/test_esql.py +++ /dev/null @@ -1,93 +0,0 @@ -# Licensed to Elasticsearch B.V. under one or more contributor -# license agreements. See the NOTICE file distributed with -# this work for additional information regarding copyright -# ownership. Elasticsearch B.V. licenses this file to you under -# the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - -import pytest - -from elasticsearch.dsl import AsyncDocument, M -from elasticsearch.esql import ESQL, functions - - -class Employee(AsyncDocument): - emp_no: M[int] - first_name: M[str] - last_name: M[str] - height: M[float] - still_hired: M[bool] - - class Index: - name = "employees" - - -async def load_db(): - data = [ - [10000, "Joseph", "Wall", 2.2, True], - [10001, "Stephanie", "Ward", 1.749, True], - [10002, "David", "Keller", 1.872, True], - [10003, "Roger", "Hinton", 1.694, False], - [10004, "Joshua", "Garcia", 1.661, False], - [10005, "Matthew", "Richards", 1.633, False], - [10006, "Maria", "Luna", 1.893, True], - [10007, "Angela", "Navarro", 1.604, False], - [10008, "Maria", "Cannon", 2.079, False], - [10009, "Joseph", "Sutton", 2.025, True], - ] - if await Employee._index.exists(): - await Employee._index.delete() - await Employee.init() - - for e in data: - employee = Employee( - emp_no=e[0], first_name=e[1], last_name=e[2], height=e[3], still_hired=e[4] - ) - await employee.save() - await Employee._index.refresh() - - -@pytest.mark.asyncio -async def test_esql(async_client): - await load_db() - - # get the full names of the employees - query = ( - ESQL.from_(Employee) - .eval(name=functions.concat(Employee.first_name, " ", Employee.last_name)) - .keep("name") - .sort("name") - .limit(10) - ) - r = await async_client.esql.query(query=str(query)) - assert r.body["values"] == [ - ["Angela Navarro"], - ["David Keller"], - ["Joseph Sutton"], - ["Joseph Wall"], - ["Joshua Garcia"], - ["Maria Cannon"], - ["Maria Luna"], - ["Matthew Richards"], - ["Roger Hinton"], - ["Stephanie Ward"], - ] - - # get the average height of all hired employees - query = ESQL.from_(Employee).stats( - avg_height=functions.round(functions.avg(Employee.height), 2).where( - Employee.still_hired == True # noqa: E712 - ) - ) - r = await async_client.esql.query(query=str(query)) - assert r.body["values"] == [[1.95]] diff --git a/test_elasticsearch/test_dsl/_sync/test_esql.py b/test_elasticsearch/test_dsl/_sync/test_esql.py deleted file mode 100644 index 1c4084fc7..000000000 --- a/test_elasticsearch/test_dsl/_sync/test_esql.py +++ /dev/null @@ -1,93 +0,0 @@ -# Licensed to Elasticsearch B.V. under one or more contributor -# license agreements. See the NOTICE file distributed with -# this work for additional information regarding copyright -# ownership. Elasticsearch B.V. licenses this file to you under -# the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - -import pytest - -from elasticsearch.dsl import Document, M -from elasticsearch.esql import ESQL, functions - - -class Employee(Document): - emp_no: M[int] - first_name: M[str] - last_name: M[str] - height: M[float] - still_hired: M[bool] - - class Index: - name = "employees" - - -def load_db(): - data = [ - [10000, "Joseph", "Wall", 2.2, True], - [10001, "Stephanie", "Ward", 1.749, True], - [10002, "David", "Keller", 1.872, True], - [10003, "Roger", "Hinton", 1.694, False], - [10004, "Joshua", "Garcia", 1.661, False], - [10005, "Matthew", "Richards", 1.633, False], - [10006, "Maria", "Luna", 1.893, True], - [10007, "Angela", "Navarro", 1.604, False], - [10008, "Maria", "Cannon", 2.079, False], - [10009, "Joseph", "Sutton", 2.025, True], - ] - if Employee._index.exists(): - Employee._index.delete() - Employee.init() - - for e in data: - employee = Employee( - emp_no=e[0], first_name=e[1], last_name=e[2], height=e[3], still_hired=e[4] - ) - employee.save() - Employee._index.refresh() - - -@pytest.mark.sync -def test_esql(client): - load_db() - - # get the full names of the employees - query = ( - ESQL.from_(Employee) - .eval(name=functions.concat(Employee.first_name, " ", Employee.last_name)) - .keep("name") - .sort("name") - .limit(10) - ) - r = client.esql.query(query=str(query)) - assert r.body["values"] == [ - ["Angela Navarro"], - ["David Keller"], - ["Joseph Sutton"], - ["Joseph Wall"], - ["Joshua Garcia"], - ["Maria Cannon"], - ["Maria Luna"], - ["Matthew Richards"], - ["Roger Hinton"], - ["Stephanie Ward"], - ] - - # get the average height of all hired employees - query = ESQL.from_(Employee).stats( - avg_height=functions.round(functions.avg(Employee.height), 2).where( - Employee.still_hired == True # noqa: E712 - ) - ) - r = client.esql.query(query=str(query)) - assert r.body["values"] == [[1.95]] diff --git a/test_elasticsearch/test_dsl/test_field.py b/test_elasticsearch/test_dsl/test_field.py index 423936ae3..181de6256 100644 --- a/test_elasticsearch/test_dsl/test_field.py +++ b/test_elasticsearch/test_dsl/test_field.py @@ -23,7 +23,15 @@ import pytest from dateutil import tz -from elasticsearch.dsl import InnerDoc, Range, ValidationException, field +from elasticsearch import dsl +from elasticsearch.dsl import ( + AttrDict, + AttrList, + InnerDoc, + Range, + ValidationException, + field, +) def test_date_range_deserialization() -> None: @@ -232,3 +240,46 @@ class Inner(InnerDoc): with pytest.raises(ValidationException): field.Object(doc_class=Inner, dynamic=False) + + +def test_dynamic_object() -> None: + f = field.Object(dynamic=True) + assert f.deserialize({"a": "b"}).to_dict() == {"a": "b"} + assert f.deserialize(AttrDict({"a": "b"})).to_dict() == {"a": "b"} + assert f.serialize({"a": "b"}) == {"a": "b"} + assert f.serialize(AttrDict({"a": "b"})) == {"a": "b"} + + +def test_dynamic_nested() -> None: + f = field.Nested(dynamic=True) + assert f.deserialize([{"a": "b"}, {"c": "d"}]) == [{"a": "b"}, {"c": "d"}] + assert f.deserialize([AttrDict({"a": "b"}), {"c": "d"}]) == [ + {"a": "b"}, + {"c": "d"}, + ] + assert f.deserialize(AttrList([AttrDict({"a": "b"}), {"c": "d"}])) == [ + {"a": "b"}, + {"c": "d"}, + ] + assert f.serialize([{"a": "b"}, {"c": "d"}]) == [{"a": "b"}, {"c": "d"}] + assert f.serialize([AttrDict({"a": "b"}), {"c": "d"}]) == [{"a": "b"}, {"c": "d"}] + assert f.serialize(AttrList([AttrDict({"a": "b"}), {"c": "d"}])) == [ + {"a": "b"}, + {"c": "d"}, + ] + + +def test_all_fields_exported() -> None: + """Make sure that all the generated field classes are exported at the top-level""" + fields = [ + f + for f in dir(field) + if isinstance(getattr(field, f), type) + and issubclass(getattr(field, f), field.Field) + ] + all = dir(dsl) + not_found = [] + for f in fields: + if f not in all: + not_found.append(f) + assert not_found == [] diff --git a/test_elasticsearch/test_dsl/test_integration/_async/test_document.py b/test_elasticsearch/test_dsl/test_integration/_async/test_document.py index 99f475cf1..36f055583 100644 --- a/test_elasticsearch/test_dsl/test_integration/_async/test_document.py +++ b/test_elasticsearch/test_dsl/test_integration/_async/test_document.py @@ -33,6 +33,7 @@ from elasticsearch.dsl import ( AsyncDocument, AsyncSearch, + AttrDict, Binary, Boolean, Date, @@ -627,22 +628,50 @@ async def test_can_save_to_different_index( @pytest.mark.asyncio +@pytest.mark.parametrize("validate", (True, False)) async def test_save_without_skip_empty_will_include_empty_fields( async_write_client: AsyncElasticsearch, + validate: bool, ) -> None: - test_repo = Repository(field_1=[], field_2=None, field_3={}, meta={"id": 42}) - assert await test_repo.save(index="test-document", skip_empty=False) + test_repo = Repository( + field_1=[], field_2=None, field_3={}, owner={"name": None}, meta={"id": 42} + ) + assert await test_repo.save( + index="test-document", skip_empty=False, validate=validate + ) assert_doc_equals( { "found": True, "_index": "test-document", "_id": "42", - "_source": {"field_1": [], "field_2": None, "field_3": {}}, + "_source": { + "field_1": [], + "field_2": None, + "field_3": {}, + "owner": {"name": None}, + }, }, await async_write_client.get(index="test-document", id=42), ) + test_repo = Repository(owner=AttrDict({"name": None}), meta={"id": 43}) + assert await test_repo.save( + index="test-document", skip_empty=False, validate=validate + ) + + assert_doc_equals( + { + "found": True, + "_index": "test-document", + "_id": "43", + "_source": { + "owner": {"name": None}, + }, + }, + await async_write_client.get(index="test-document", id=43), + ) + @pytest.mark.asyncio async def test_delete(async_write_client: AsyncElasticsearch) -> None: diff --git a/test_elasticsearch/test_dsl/test_integration/_async/test_esql.py b/test_elasticsearch/test_dsl/test_integration/_async/test_esql.py new file mode 100644 index 000000000..ae99873f8 --- /dev/null +++ b/test_elasticsearch/test_dsl/test_integration/_async/test_esql.py @@ -0,0 +1,254 @@ +# Licensed to Elasticsearch B.V. under one or more contributor +# license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright +# ownership. Elasticsearch B.V. licenses this file to you under +# the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +import pytest + +from elasticsearch.dsl import AsyncDocument, InnerDoc, M +from elasticsearch.esql import ESQL, E, functions + + +class Address(InnerDoc): + address: M[str] + city: M[str] + + +class Employee(AsyncDocument): + emp_no: M[int] + first_name: M[str] + last_name: M[str] + height: M[float] + still_hired: M[bool] + address: M[Address] + + class Index: + name = "employees" + + +async def load_db(): + data = [ + [ + 10000, + "Joseph", + "Wall", + 2.2, + True, + Address(address="8875 Long Shoals Suite 441", city="Marcville, TX"), + ], + [ + 10001, + "Stephanie", + "Ward", + 1.749, + True, + Address(address="90162 Carter Harbor Suite 099", city="Davisborough, DE"), + ], + [ + 10002, + "David", + "Keller", + 1.872, + True, + Address(address="6697 Patrick Union Suite 797", city="Fuentesmouth, SD"), + ], + [ + 10003, + "Roger", + "Hinton", + 1.694, + False, + Address(address="809 Kelly Mountains", city="South Megan, DE"), + ], + [ + 10004, + "Joshua", + "Garcia", + 1.661, + False, + Address(address="718 Angela Forks", city="Port Erinland, MA"), + ], + [ + 10005, + "Matthew", + "Richards", + 1.633, + False, + Address(address="2869 Brown Mountains", city="New Debra, NH"), + ], + [ + 10006, + "Maria", + "Luna", + 1.893, + True, + Address(address="5861 Morgan Springs", city="Lake Daniel, WI"), + ], + [ + 10007, + "Angela", + "Navarro", + 1.604, + False, + Address(address="2848 Allen Station", city="Saint Joseph, OR"), + ], + [ + 10008, + "Maria", + "Cannon", + 2.079, + False, + Address(address="322 NW Johnston", city="Bakerburgh, MP"), + ], + [ + 10009, + "Joseph", + "Sutton", + 2.025, + True, + Address(address="77 Cardinal E", city="Lakestown, IL"), + ], + ] + if await Employee._index.exists(): + await Employee._index.delete() + await Employee.init() + + for e in data: + employee = Employee( + emp_no=e[0], + first_name=e[1], + last_name=e[2], + height=e[3], + still_hired=e[4], + address=e[5], + ) + await employee.save() + await Employee._index.refresh() + + +@pytest.mark.asyncio +async def test_esql(async_client): + await load_db() + + # get the full names of the employees + query = ( + ESQL.from_(Employee) + .eval(full_name=functions.concat(Employee.first_name, " ", Employee.last_name)) + .keep("full_name") + .sort("full_name") + .limit(10) + ) + r = await async_client.esql.query(query=str(query)) + assert r.body["values"] == [ + ["Angela Navarro"], + ["David Keller"], + ["Joseph Sutton"], + ["Joseph Wall"], + ["Joshua Garcia"], + ["Maria Cannon"], + ["Maria Luna"], + ["Matthew Richards"], + ["Roger Hinton"], + ["Stephanie Ward"], + ] + + # get the average height of all hired employees + query = ESQL.from_(Employee).stats( + avg_height=functions.round(functions.avg(Employee.height), 2).where( + Employee.still_hired == True # noqa: E712 + ) + ) + r = await async_client.esql.query(query=str(query)) + assert r.body["values"] == [[1.95]] + + # find employees by name using a parameter + query = ( + ESQL.from_(Employee) + .where(Employee.first_name == E("?")) + .keep(Employee.last_name) + .sort(Employee.last_name.desc()) + ) + r = await async_client.esql.query(query=str(query), params=["Maria"]) + assert r.body["values"] == [["Luna"], ["Cannon"]] + + +@pytest.mark.asyncio +async def test_esql_dsl(async_client): + await load_db() + + # get employees with first name "Maria" + query = ( + Employee.esql_from() + .where(Employee.first_name == "Maria") + .sort("last_name") + .limit(10) + ) + marias = [] + async for emp in Employee.esql_execute(query): + marias.append(emp) + assert len(marias) == 2 + assert marias[0].last_name == "Cannon" + assert marias[0].address.address == "322 NW Johnston" + assert marias[0].address.city == "Bakerburgh, MP" + assert marias[1].last_name == "Luna" + assert marias[1].address.address == "5861 Morgan Springs" + assert marias[1].address.city == "Lake Daniel, WI" + + # run a query with a missing field + query = ( + Employee.esql_from() + .where(Employee.first_name == "Maria") + .drop(Employee.address.city) + .sort("last_name") + .limit(10) + ) + with pytest.raises(ValueError): + await Employee.esql_execute(query).__anext__() + marias = [] + async for emp in Employee.esql_execute(query, ignore_missing_fields=True): + marias.append(emp) + assert marias[0].last_name == "Cannon" + assert marias[0].address.address == "322 NW Johnston" + assert marias[0].address.city is None + assert marias[1].last_name == "Luna" + assert marias[1].address.address == "5861 Morgan Springs" + assert marias[1].address.city is None + + # run a query with additional calculated fields + query = ( + Employee.esql_from() + .where(Employee.first_name == "Maria") + .eval( + full_name=functions.concat(Employee.first_name, " ", Employee.last_name), + height_cm=functions.to_integer(Employee.height * 100), + ) + .sort("last_name") + .limit(10) + ) + assert isinstance(await Employee.esql_execute(query).__anext__(), Employee) + assert isinstance( + await Employee.esql_execute(query, return_additional=True).__anext__(), tuple + ) + marias = [] + async for emp, extra in Employee.esql_execute(query, return_additional=True): + marias.append([emp, extra]) + assert marias[0][0].last_name == "Cannon" + assert marias[0][0].address.address == "322 NW Johnston" + assert marias[0][0].address.city == "Bakerburgh, MP" + assert marias[0][1] == {"full_name": "Maria Cannon", "height_cm": 208} + assert marias[1][0].last_name == "Luna" + assert marias[1][0].address.address == "5861 Morgan Springs" + assert marias[1][0].address.city == "Lake Daniel, WI" + assert marias[1][1] == {"full_name": "Maria Luna", "height_cm": 189} diff --git a/test_elasticsearch/test_dsl/test_integration/_sync/test_document.py b/test_elasticsearch/test_dsl/test_integration/_sync/test_document.py index 05dd05fd9..62857cd9a 100644 --- a/test_elasticsearch/test_dsl/test_integration/_sync/test_document.py +++ b/test_elasticsearch/test_dsl/test_integration/_sync/test_document.py @@ -31,6 +31,7 @@ from elasticsearch import ConflictError, Elasticsearch, NotFoundError from elasticsearch.dsl import ( + AttrDict, Binary, Boolean, Date, @@ -621,22 +622,46 @@ def test_can_save_to_different_index( @pytest.mark.sync +@pytest.mark.parametrize("validate", (True, False)) def test_save_without_skip_empty_will_include_empty_fields( write_client: Elasticsearch, + validate: bool, ) -> None: - test_repo = Repository(field_1=[], field_2=None, field_3={}, meta={"id": 42}) - assert test_repo.save(index="test-document", skip_empty=False) + test_repo = Repository( + field_1=[], field_2=None, field_3={}, owner={"name": None}, meta={"id": 42} + ) + assert test_repo.save(index="test-document", skip_empty=False, validate=validate) assert_doc_equals( { "found": True, "_index": "test-document", "_id": "42", - "_source": {"field_1": [], "field_2": None, "field_3": {}}, + "_source": { + "field_1": [], + "field_2": None, + "field_3": {}, + "owner": {"name": None}, + }, }, write_client.get(index="test-document", id=42), ) + test_repo = Repository(owner=AttrDict({"name": None}), meta={"id": 43}) + assert test_repo.save(index="test-document", skip_empty=False, validate=validate) + + assert_doc_equals( + { + "found": True, + "_index": "test-document", + "_id": "43", + "_source": { + "owner": {"name": None}, + }, + }, + write_client.get(index="test-document", id=43), + ) + @pytest.mark.sync def test_delete(write_client: Elasticsearch) -> None: diff --git a/test_elasticsearch/test_dsl/test_integration/_sync/test_esql.py b/test_elasticsearch/test_dsl/test_integration/_sync/test_esql.py new file mode 100644 index 000000000..d02484013 --- /dev/null +++ b/test_elasticsearch/test_dsl/test_integration/_sync/test_esql.py @@ -0,0 +1,254 @@ +# Licensed to Elasticsearch B.V. under one or more contributor +# license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright +# ownership. Elasticsearch B.V. licenses this file to you under +# the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +import pytest + +from elasticsearch.dsl import Document, InnerDoc, M +from elasticsearch.esql import ESQL, E, functions + + +class Address(InnerDoc): + address: M[str] + city: M[str] + + +class Employee(Document): + emp_no: M[int] + first_name: M[str] + last_name: M[str] + height: M[float] + still_hired: M[bool] + address: M[Address] + + class Index: + name = "employees" + + +def load_db(): + data = [ + [ + 10000, + "Joseph", + "Wall", + 2.2, + True, + Address(address="8875 Long Shoals Suite 441", city="Marcville, TX"), + ], + [ + 10001, + "Stephanie", + "Ward", + 1.749, + True, + Address(address="90162 Carter Harbor Suite 099", city="Davisborough, DE"), + ], + [ + 10002, + "David", + "Keller", + 1.872, + True, + Address(address="6697 Patrick Union Suite 797", city="Fuentesmouth, SD"), + ], + [ + 10003, + "Roger", + "Hinton", + 1.694, + False, + Address(address="809 Kelly Mountains", city="South Megan, DE"), + ], + [ + 10004, + "Joshua", + "Garcia", + 1.661, + False, + Address(address="718 Angela Forks", city="Port Erinland, MA"), + ], + [ + 10005, + "Matthew", + "Richards", + 1.633, + False, + Address(address="2869 Brown Mountains", city="New Debra, NH"), + ], + [ + 10006, + "Maria", + "Luna", + 1.893, + True, + Address(address="5861 Morgan Springs", city="Lake Daniel, WI"), + ], + [ + 10007, + "Angela", + "Navarro", + 1.604, + False, + Address(address="2848 Allen Station", city="Saint Joseph, OR"), + ], + [ + 10008, + "Maria", + "Cannon", + 2.079, + False, + Address(address="322 NW Johnston", city="Bakerburgh, MP"), + ], + [ + 10009, + "Joseph", + "Sutton", + 2.025, + True, + Address(address="77 Cardinal E", city="Lakestown, IL"), + ], + ] + if Employee._index.exists(): + Employee._index.delete() + Employee.init() + + for e in data: + employee = Employee( + emp_no=e[0], + first_name=e[1], + last_name=e[2], + height=e[3], + still_hired=e[4], + address=e[5], + ) + employee.save() + Employee._index.refresh() + + +@pytest.mark.sync +def test_esql(client): + load_db() + + # get the full names of the employees + query = ( + ESQL.from_(Employee) + .eval(full_name=functions.concat(Employee.first_name, " ", Employee.last_name)) + .keep("full_name") + .sort("full_name") + .limit(10) + ) + r = client.esql.query(query=str(query)) + assert r.body["values"] == [ + ["Angela Navarro"], + ["David Keller"], + ["Joseph Sutton"], + ["Joseph Wall"], + ["Joshua Garcia"], + ["Maria Cannon"], + ["Maria Luna"], + ["Matthew Richards"], + ["Roger Hinton"], + ["Stephanie Ward"], + ] + + # get the average height of all hired employees + query = ESQL.from_(Employee).stats( + avg_height=functions.round(functions.avg(Employee.height), 2).where( + Employee.still_hired == True # noqa: E712 + ) + ) + r = client.esql.query(query=str(query)) + assert r.body["values"] == [[1.95]] + + # find employees by name using a parameter + query = ( + ESQL.from_(Employee) + .where(Employee.first_name == E("?")) + .keep(Employee.last_name) + .sort(Employee.last_name.desc()) + ) + r = client.esql.query(query=str(query), params=["Maria"]) + assert r.body["values"] == [["Luna"], ["Cannon"]] + + +@pytest.mark.sync +def test_esql_dsl(client): + load_db() + + # get employees with first name "Maria" + query = ( + Employee.esql_from() + .where(Employee.first_name == "Maria") + .sort("last_name") + .limit(10) + ) + marias = [] + for emp in Employee.esql_execute(query): + marias.append(emp) + assert len(marias) == 2 + assert marias[0].last_name == "Cannon" + assert marias[0].address.address == "322 NW Johnston" + assert marias[0].address.city == "Bakerburgh, MP" + assert marias[1].last_name == "Luna" + assert marias[1].address.address == "5861 Morgan Springs" + assert marias[1].address.city == "Lake Daniel, WI" + + # run a query with a missing field + query = ( + Employee.esql_from() + .where(Employee.first_name == "Maria") + .drop(Employee.address.city) + .sort("last_name") + .limit(10) + ) + with pytest.raises(ValueError): + Employee.esql_execute(query).__next__() + marias = [] + for emp in Employee.esql_execute(query, ignore_missing_fields=True): + marias.append(emp) + assert marias[0].last_name == "Cannon" + assert marias[0].address.address == "322 NW Johnston" + assert marias[0].address.city is None + assert marias[1].last_name == "Luna" + assert marias[1].address.address == "5861 Morgan Springs" + assert marias[1].address.city is None + + # run a query with additional calculated fields + query = ( + Employee.esql_from() + .where(Employee.first_name == "Maria") + .eval( + full_name=functions.concat(Employee.first_name, " ", Employee.last_name), + height_cm=functions.to_integer(Employee.height * 100), + ) + .sort("last_name") + .limit(10) + ) + assert isinstance(Employee.esql_execute(query).__next__(), Employee) + assert isinstance( + Employee.esql_execute(query, return_additional=True).__next__(), tuple + ) + marias = [] + for emp, extra in Employee.esql_execute(query, return_additional=True): + marias.append([emp, extra]) + assert marias[0][0].last_name == "Cannon" + assert marias[0][0].address.address == "322 NW Johnston" + assert marias[0][0].address.city == "Bakerburgh, MP" + assert marias[0][1] == {"full_name": "Maria Cannon", "height_cm": 208} + assert marias[1][0].last_name == "Luna" + assert marias[1][0].address.address == "5861 Morgan Springs" + assert marias[1][0].address.city == "Lake Daniel, WI" + assert marias[1][1] == {"full_name": "Maria Luna", "height_cm": 189} diff --git a/test_elasticsearch/test_dsl/test_integration/test_examples/_async/test_vectors.py b/test_elasticsearch/test_dsl/test_integration/test_examples/_async/test_vectors.py index dc45ceb52..3af9a877f 100644 --- a/test_elasticsearch/test_dsl/test_integration/test_examples/_async/test_vectors.py +++ b/test_elasticsearch/test_dsl/test_integration/test_examples/_async/test_vectors.py @@ -15,27 +15,27 @@ # specific language governing permissions and limitations # under the License. +import sys from hashlib import md5 from typing import Any, List, Tuple from unittest import SkipTest +from unittest.mock import Mock, patch import pytest from elasticsearch import AsyncElasticsearch -from ..async_examples import vectors - @pytest.mark.asyncio async def test_vector_search( - async_write_client: AsyncElasticsearch, es_version: Tuple[int, ...], mocker: Any + async_write_client: AsyncElasticsearch, es_version: Tuple[int, ...] ) -> None: # this test only runs on Elasticsearch >= 8.11 because the example uses # a dense vector without specifying an explicit size if es_version < (8, 11): raise SkipTest("This test requires Elasticsearch 8.11 or newer") - class MockModel: + class MockSentenceTransformer: def __init__(self, model: Any): pass @@ -44,9 +44,22 @@ def encode(self, text: str) -> List[float]: total = sum(vector) return [float(v) / total for v in vector] - mocker.patch.object(vectors, "SentenceTransformer", new=MockModel) + def mock_nltk_tokenize(content: str): + return content.split("\n") + + # mock sentence_transformers and nltk, because they are quite big and + # irrelevant for testing the example logic + with patch.dict( + sys.modules, + { + "sentence_transformers": Mock(SentenceTransformer=MockSentenceTransformer), + "nltk": Mock(sent_tokenize=mock_nltk_tokenize), + }, + ): + # import the example after the dependencies are mocked + from ..async_examples import vectors - await vectors.create() - await vectors.WorkplaceDoc._index.refresh() - results = await (await vectors.search("Welcome to our team!")).execute() - assert results[0].name == "New Employee Onboarding Guide" + await vectors.create() + await vectors.WorkplaceDoc._index.refresh() + results = await (await vectors.search("Welcome to our team!")).execute() + assert results[0].name == "Intellectual Property Policy" diff --git a/test_elasticsearch/test_dsl/test_integration/test_examples/_sync/test_vectors.py b/test_elasticsearch/test_dsl/test_integration/test_examples/_sync/test_vectors.py index 4b14c89a0..e8e61b5a0 100644 --- a/test_elasticsearch/test_dsl/test_integration/test_examples/_sync/test_vectors.py +++ b/test_elasticsearch/test_dsl/test_integration/test_examples/_sync/test_vectors.py @@ -15,27 +15,27 @@ # specific language governing permissions and limitations # under the License. +import sys from hashlib import md5 from typing import Any, List, Tuple from unittest import SkipTest +from unittest.mock import Mock, patch import pytest from elasticsearch import Elasticsearch -from ..examples import vectors - @pytest.mark.sync def test_vector_search( - write_client: Elasticsearch, es_version: Tuple[int, ...], mocker: Any + write_client: Elasticsearch, es_version: Tuple[int, ...] ) -> None: # this test only runs on Elasticsearch >= 8.11 because the example uses # a dense vector without specifying an explicit size if es_version < (8, 11): raise SkipTest("This test requires Elasticsearch 8.11 or newer") - class MockModel: + class MockSentenceTransformer: def __init__(self, model: Any): pass @@ -44,9 +44,22 @@ def encode(self, text: str) -> List[float]: total = sum(vector) return [float(v) / total for v in vector] - mocker.patch.object(vectors, "SentenceTransformer", new=MockModel) + def mock_nltk_tokenize(content: str): + return content.split("\n") + + # mock sentence_transformers and nltk, because they are quite big and + # irrelevant for testing the example logic + with patch.dict( + sys.modules, + { + "sentence_transformers": Mock(SentenceTransformer=MockSentenceTransformer), + "nltk": Mock(sent_tokenize=mock_nltk_tokenize), + }, + ): + # import the example after the dependencies are mocked + from ..examples import vectors - vectors.create() - vectors.WorkplaceDoc._index.refresh() - results = (vectors.search("Welcome to our team!")).execute() - assert results[0].name == "New Employee Onboarding Guide" + vectors.create() + vectors.WorkplaceDoc._index.refresh() + results = (vectors.search("Welcome to our team!")).execute() + assert results[0].name == "Intellectual Property Policy" diff --git a/test_elasticsearch/test_esql.py b/test_elasticsearch/test_esql.py index 70c9ec679..35b026fb5 100644 --- a/test_elasticsearch/test_esql.py +++ b/test_elasticsearch/test_esql.py @@ -84,7 +84,7 @@ def test_completion(): assert ( query.render() == """ROW question = "What is Elasticsearch?" -| COMPLETION question WITH test_completion_model +| COMPLETION question WITH {"inference_id": "test_completion_model"} | KEEP question, completion""" ) @@ -97,7 +97,7 @@ def test_completion(): assert ( query.render() == """ROW question = "What is Elasticsearch?" -| COMPLETION answer = question WITH test_completion_model +| COMPLETION answer = question WITH {"inference_id": "test_completion_model"} | KEEP question, answer""" ) @@ -128,7 +128,7 @@ def test_completion(): "Synopsis: ", synopsis, "\\n", "Actors: ", MV_CONCAT(actors, ", "), "\\n", ) -| COMPLETION summary = prompt WITH test_completion_model +| COMPLETION summary = prompt WITH {"inference_id": "test_completion_model"} | KEEP title, summary, rating""" ) @@ -160,7 +160,7 @@ def test_completion(): | SORT rating DESC | LIMIT 10 | EVAL prompt = CONCAT("Summarize this movie using the following information: \\n", "Title: ", title, "\\n", "Synopsis: ", synopsis, "\\n", "Actors: ", MV_CONCAT(actors, ", "), "\\n") -| COMPLETION summary = prompt WITH test_completion_model +| COMPLETION summary = prompt WITH {"inference_id": "test_completion_model"} | KEEP title, summary, rating""" ) @@ -713,3 +713,11 @@ def test_match_operator(): == """FROM books | WHERE author:"Faulkner\"""" ) + + +def test_parameters(): + query = ESQL.from_("employees").where("name == ?") + assert query.render() == "FROM employees\n| WHERE name == ?" + + query = ESQL.from_("employees").where(E("name") == E("?")) + assert query.render() == "FROM employees\n| WHERE name == ?" diff --git a/test_elasticsearch/test_helpers.py b/test_elasticsearch/test_helpers.py index e30635f44..398cb6cc3 100644 --- a/test_elasticsearch/test_helpers.py +++ b/test_elasticsearch/test_helpers.py @@ -18,6 +18,7 @@ import pickle import threading import time +from typing import Optional from unittest import mock import pytest @@ -156,21 +157,34 @@ def test__source_metadata_or_source(self): {"_source": {"key2": "val2"}, "key": "val", "_op_type": "update"} ) == ({"update": {}}, {"key2": "val2"}) - def test_chunks_are_chopped_by_byte_size(self): + @pytest.mark.parametrize("flush_seconds", [None, 10]) + def test_chunks_are_chopped_by_byte_size(self, flush_seconds: Optional[float]): assert 100 == len( - list(helpers._chunk_actions(self.actions, 100000, 1, JSONSerializer())) + list( + helpers._chunk_actions( + self.actions, 100000, 1, flush_seconds, JSONSerializer() + ) + ) ) - def test_chunks_are_chopped_by_chunk_size(self): + @pytest.mark.parametrize("flush_seconds", [None, 10]) + def test_chunks_are_chopped_by_chunk_size(self, flush_seconds: Optional[float]): assert 10 == len( - list(helpers._chunk_actions(self.actions, 10, 99999999, JSONSerializer())) + list( + helpers._chunk_actions( + self.actions, 10, 99999999, flush_seconds, JSONSerializer() + ) + ) ) - def test_chunks_are_chopped_by_byte_size_properly(self): + @pytest.mark.parametrize("flush_seconds", [None, 10]) + def test_chunks_are_chopped_by_byte_size_properly( + self, flush_seconds: Optional[float] + ): max_byte_size = 170 chunks = list( helpers._chunk_actions( - self.actions, 100000, max_byte_size, JSONSerializer() + self.actions, 100000, max_byte_size, flush_seconds, JSONSerializer() ) ) assert 25 == len(chunks) @@ -178,6 +192,30 @@ def test_chunks_are_chopped_by_byte_size_properly(self): chunk = b"".join(chunk_actions) assert len(chunk) <= max_byte_size + @pytest.mark.parametrize("flush_seconds", [None, 10]) + def test_chunks_are_chopped_by_flush(self, flush_seconds: Optional[float]): + flush = (helpers.BULK_FLUSH, None) + actions = ( + self.actions[:3] + + [flush] * 2 # two consecutive flushes after 3 items + + self.actions[3:4] + + [flush] # flush after one more item + + self.actions[4:] + + [flush] # flush at the end + ) + chunks = list( + helpers._chunk_actions( + actions, 100, 99999999, flush_seconds, JSONSerializer() + ) + ) + assert 3 == len(chunks) + assert len(chunks[0][0]) == 3 + assert len(chunks[0][1]) == 6 + assert len(chunks[1][0]) == 1 + assert len(chunks[1][1]) == 2 + assert len(chunks[2][0]) == 96 + assert len(chunks[2][1]) == 192 + class TestExpandActions: @pytest.mark.parametrize("action", ["whatever", b"whatever"]) diff --git a/test_elasticsearch/test_server/test_helpers.py b/test_elasticsearch/test_server/test_helpers.py index 74b9f0ef8..f175c6e0b 100644 --- a/test_elasticsearch/test_server/test_helpers.py +++ b/test_elasticsearch/test_server/test_helpers.py @@ -16,6 +16,7 @@ # under the License. import json +import time from datetime import datetime, timedelta from unittest.mock import call, patch @@ -75,6 +76,47 @@ def test_bulk_all_documents_get_inserted(sync_client): assert {"answer": 42} == sync_client.get(index="test-index", id=42)["_source"] +def test_explicit_flushes(sync_client): + def sync_gen(): + yield {"answer": 0, "_id": 0} + yield {"answer": 1, "_id": 1} + yield helpers.BULK_FLUSH + time.sleep(0.5) + yield {"answer": 2, "_id": 2} + + timestamps = [] + for ok, item in helpers.streaming_bulk( + sync_client, sync_gen(), index="test-index", refresh=True + ): + assert ok + timestamps.append(time.time()) + + # make sure there is a pause between the writing of the 2nd and 3rd items + assert timestamps[2] - timestamps[1] > (timestamps[1] - timestamps[0]) * 2 + + +def test_timeout_flushes(sync_client): + def sync_gen(): + yield {"answer": 0, "_id": 0} + yield {"answer": 1, "_id": 1} + time.sleep(0.5) + yield {"answer": 2, "_id": 2} + + timestamps = [] + for ok, item in helpers.streaming_bulk( + sync_client, + sync_gen(), + index="test-index", + refresh=True, + flush_after_seconds=0.05, + ): + assert ok + timestamps.append(time.time()) + + # make sure there is a pause between the writing of the 2nd and 3rd items + assert timestamps[2] - timestamps[1] > (timestamps[1] - timestamps[0]) * 2 + + def test_bulk_all_errors_from_chunk_are_raised_on_failure(sync_client): sync_client.indices.create( index="i", diff --git a/test_elasticsearch/test_server/test_otel.py b/test_elasticsearch/test_server/test_otel.py index e0b0cc776..6673e5537 100644 --- a/test_elasticsearch/test_server/test_otel.py +++ b/test_elasticsearch/test_server/test_otel.py @@ -53,6 +53,17 @@ def test_otel_end_to_end(sync_client): assert expected_attributes.items() <= spans[0].attributes.items() +# Since ping is manually implemented, we have a dedicated test for it +def test_otel_ping(sync_client): + tracer, memory_exporter = setup_tracing() + sync_client._otel.tracer = tracer + + sync_client.ping() + spans = memory_exporter.get_finished_spans() + assert len(spans) == 1 + assert spans[0].name == "ping" + + @pytest.mark.parametrize( "bulk_helper_name", ["bulk", "streaming_bulk", "parallel_bulk"] ) diff --git a/test_elasticsearch/test_server/test_rest_api_spec.py b/test_elasticsearch/test_server/test_rest_api_spec.py index a84f0822a..bf566d503 100644 --- a/test_elasticsearch/test_server/test_rest_api_spec.py +++ b/test_elasticsearch/test_server/test_rest_api_spec.py @@ -24,6 +24,7 @@ import json import os import re +import subprocess import warnings import zipfile from typing import Tuple, Union @@ -34,6 +35,7 @@ from elasticsearch import ApiError, ElasticsearchWarning, RequestError from elasticsearch._sync.client.utils import _base64_auth_header +from elasticsearch._version import __versionstr__ from elasticsearch.compat import string_types # some params had to be changed in python, keep track of them so we can rename @@ -78,6 +80,7 @@ "cluster/voting_config_exclusions", "entsearch/10_basic", "indices/clone", + "indices/data_stream_mappings[0]", "indices/resolve_cluster", "indices/settings", "indices/split", @@ -406,16 +409,21 @@ def _resolve(self, value): return value def _lookup(self, path): - # fetch the possibly nested value from last_response - value = self.last_response if path == "$body": - return value + return self.last_response + if path.startswith("$"): + value = None + else: + value = self.last_response path = path.replace(r"\.", "\1") for step in path.split("."): if not step: continue # We check body again to handle E.g. '$body.$backing_index.data_stream' - if step.startswith("$body"): + if step == "$body": + assert value is None + # fetch the possibly nested value from last_response + value = self.last_response continue step = step.replace("\1", ".") step = self._resolve(step) @@ -427,11 +435,15 @@ def _lookup(self, path): step = int(step) assert isinstance(value, list) assert len(value) > step + value = value[step] elif step == "_arbitrary_key_": return list(value.keys())[0] - else: + elif isinstance(step, string_types) and isinstance(value, dict): assert step in value - value = value[step] + value = value[step] + else: + assert value is None + value = step return value def _feature_enabled(self, name): @@ -494,14 +506,31 @@ def remove_implicit_resolver(cls, tag_to_remove): # Try loading the REST API test specs from the Elastic Artifacts API try: # Construct the HTTP and Elasticsearch client - http = urllib3.PoolManager(retries=10) - - yaml_tests_url = ( - "https://api.github.com/repos/elastic/elasticsearch-clients-tests/zipball/main" - ) + http = urllib3.PoolManager(retries=urllib3.Retry(total=10)) + + branch_candidates = [] + if "ES_YAML_TESTS_BRANCH" in os.environ and os.environ["ES_YAML_TESTS_BRANCH"]: + branch_candidates.append(os.environ["ES_YAML_TESTS_BRANCH"]) + git_branch = subprocess.getoutput("git branch --show-current") + if git_branch and git_branch not in branch_candidates: + branch_candidates.append(git_branch) + package_version = __versionstr__.rsplit(".", 1)[0] + if package_version and package_version not in branch_candidates: + branch_candidates.append(package_version) + if "main" not in branch_candidates: + branch_candidates.append("main") + + response = None + branch = "main" + for branch in branch_candidates: + yaml_tests_url = f"https://api.github.com/repos/elastic/elasticsearch-clients-tests/zipball/%7Bbranch%7D" + response = http.request("GET", yaml_tests_url) + if response.status != 404: + break + assert response is not None # Download the zip and start reading YAML from the files in memory - package_zip = zipfile.ZipFile(io.BytesIO(http.request("GET", yaml_tests_url).data)) + package_zip = zipfile.ZipFile(io.BytesIO(response.data)) for yaml_file in package_zip.namelist(): if not re.match(r"^.*\/tests\/.*\.ya?ml$", yaml_file): @@ -559,7 +588,9 @@ def remove_implicit_resolver(cls, tag_to_remove): elif pytest_test_name in SKIPPED_TESTS or pytest_param_id in SKIPPED_TESTS: pytest_param["skip"] = True - YAML_TEST_SPECS.append(pytest.param(pytest_param, id=pytest_param_id)) + YAML_TEST_SPECS.append( + pytest.param(pytest_param, id=f"[{branch}]{pytest_param_id}") + ) except Exception as e: warnings.warn(f"Could not load REST API tests: {str(e)}") diff --git a/test_elasticsearch/test_transport.py b/test_elasticsearch/test_transport.py index 237f21ac1..b64d9d332 100644 --- a/test_elasticsearch/test_transport.py +++ b/test_elasticsearch/test_transport.py @@ -43,7 +43,7 @@ class DummyNode(BaseNode): def __init__(self, config: NodeConfig): self.resp_status = config._extras.pop("status", 200) - self.resp_error = config._extras.pop("exception", None) + self.resp_error = config._extras.pop("exception_factory", None) self.resp_data = config._extras.pop("data", b"{}") self.resp_headers = config._extras.pop( "headers", {"X-elastic-product": "Elasticsearch"} @@ -55,7 +55,7 @@ def __init__(self, config: NodeConfig): def perform_request(self, *args, **kwargs): self.calls.append((args, kwargs)) if self.resp_error: - raise self.resp_error + raise self.resp_error() return NodeApiResponse( ApiResponseMeta( status=self.resp_status, @@ -310,7 +310,9 @@ def test_request_will_fail_after_x_retries(self): "http", "localhost", 9200, - _extras={"exception": ConnectionError("abandon ship!")}, + _extras={ + "exception_factory": lambda: ConnectionError("abandon ship!") + }, ) ], node_class=DummyNode, @@ -335,13 +337,17 @@ def test_failed_connection_will_be_marked_as_dead(self): "http", "localhost", 9200, - _extras={"exception": ConnectionError("abandon ship!")}, + _extras={ + "exception_factory": lambda: ConnectionError("abandon ship!") + }, ), NodeConfig( "http", "localhost", 9201, - _extras={"exception": ConnectionError("abandon ship!")}, + _extras={ + "exception_factory": lambda: ConnectionError("abandon ship!") + }, ), ], node_class=DummyNode, diff --git a/test_elasticsearch/utils.py b/test_elasticsearch/utils.py index 021deb76e..4455462d2 100644 --- a/test_elasticsearch/utils.py +++ b/test_elasticsearch/utils.py @@ -179,7 +179,7 @@ def wipe_data_streams(client): def wipe_indices(client): indices = client.cat.indices().strip().splitlines() if len(indices) > 0: - index_names = [i.split(" ")[2] for i in indices] + index_names = [i.split()[2] for i in indices] client.options(ignore_status=404).indices.delete( index=",".join(index_names), expand_wildcards="all", @@ -191,3 +191,4 @@ def wait_for_cluster_state_updates_to_finish(client, timeout=30): while time.time() < end_time: if not client.cluster.pending_tasks().get("tasks", ()): break + time.sleep(0.1) diff --git a/utils/build-dists.py b/utils/build-dists.py index d67d6053a..fd1b477e0 100644 --- a/utils/build-dists.py +++ b/utils/build-dists.py @@ -121,6 +121,7 @@ def test_dist(dist): "--install-types", "--non-interactive", "--ignore-missing-imports", + "--implicit-reexport", os.path.join(base_dir, "test_elasticsearch/test_types/async_types.py"), ) @@ -145,6 +146,7 @@ def test_dist(dist): "--install-types", "--non-interactive", "--ignore-missing-imports", + "--implicit-reexport", os.path.join(base_dir, "test_elasticsearch/test_types/sync_types.py"), ) else: @@ -156,6 +158,7 @@ def test_dist(dist): "--install-types", "--non-interactive", "--ignore-missing-imports", + "--implicit-reexport", os.path.join( base_dir, "test_elasticsearch/test_types/aliased_types.py" ), diff --git a/utils/run-unasync-dsl.py b/utils/run-unasync-dsl.py index 59c0b05bc..b74c748fa 100644 --- a/utils/run-unasync-dsl.py +++ b/utils/run-unasync-dsl.py @@ -121,7 +121,7 @@ def main(check=False): [ "sed", "-i.bak", - "s/elasticsearch\\[async\\]/elasticsearch/", + 's/"elasticsearch\\[async\\]"/elasticsearch/', f"{output_dir}{file}", ] ) diff --git a/utils/templates/aggs.py.tpl b/utils/templates/aggs.py.tpl index 68d46e63d..31e27bf5f 100644 --- a/utils/templates/aggs.py.tpl +++ b/utils/templates/aggs.py.tpl @@ -255,6 +255,9 @@ class {{ k.name }}({{ k.parent if k.parent else parent }}[_R]): {{ arg.name }}: {{ arg.type }} = DEFAULT, {% endif %} {% endfor %} + {% if k.args and k.args[0].positional %} + /, + {% endif %} {% if k.args and not k.args[-1].positional %} *, {% endif %} diff --git a/utils/templates/field.py.tpl b/utils/templates/field.py.tpl index 8a4c73f33..43df1b5f0 100644 --- a/utils/templates/field.py.tpl +++ b/utils/templates/field.py.tpl @@ -119,9 +119,16 @@ class Field(DslBase): def __getitem__(self, subfield: str) -> "Field": return cast(Field, self._params.get("fields", {})[subfield]) - def _serialize(self, data: Any) -> Any: + def _serialize(self, data: Any, skip_empty: bool) -> Any: return data + def _safe_serialize(self, data: Any, skip_empty: bool) -> Any: + try: + return self._serialize(data, skip_empty) + except TypeError: + # older method signature, without skip_empty + return self._serialize(data) # type: ignore[call-arg] + def _deserialize(self, data: Any) -> Any: return data @@ -133,10 +140,10 @@ class Field(DslBase): return AttrList([]) return self._empty() - def serialize(self, data: Any) -> Any: + def serialize(self, data: Any, skip_empty: bool = True) -> Any: if isinstance(data, (list, AttrList, tuple)): - return list(map(self._serialize, cast(Iterable[Any], data))) - return self._serialize(data) + return list(map(self._safe_serialize, cast(Iterable[Any], data), [skip_empty] * len(data))) + return self._safe_serialize(data, skip_empty) def deserialize(self, data: Any) -> Any: if isinstance(data, (list, AttrList, tuple)): @@ -186,7 +193,7 @@ class RangeField(Field): data = {k: self._core_field.deserialize(v) for k, v in data.items()} # type: ignore[union-attr] return Range(data) - def _serialize(self, data: Any) -> Optional[Dict[str, Any]]: + def _serialize(self, data: Any, skip_empty: bool) -> Optional[Dict[str, Any]]: if data is None: return None if not isinstance(data, collections.abc.Mapping): @@ -318,7 +325,7 @@ class {{ k.name }}({{ k.parent }}): return self._wrap(data) def _serialize( - self, data: Optional[Union[Dict[str, Any], "InnerDoc"]] + self, data: Optional[Union[Dict[str, Any], "InnerDoc"]], skip_empty: bool ) -> Optional[Dict[str, Any]]: if data is None: return None @@ -327,7 +334,11 @@ class {{ k.name }}({{ k.parent }}): if isinstance(data, collections.abc.Mapping): return data - return data.to_dict() + try: + return data.to_dict(skip_empty=skip_empty) + except TypeError: + # this would only happen if an AttrDict was given instead of an InnerDoc + return data.to_dict() def clean(self, data: Any) -> Any: data = super().clean(data) @@ -433,7 +444,7 @@ class {{ k.name }}({{ k.parent }}): # the ipaddress library for pypy only accepts unicode. return ipaddress.ip_address(unicode(data)) - def _serialize(self, data: Any) -> Optional[str]: + def _serialize(self, data: Any, skip_empty: bool) -> Optional[str]: if data is None: return None return str(data) @@ -448,7 +459,7 @@ class {{ k.name }}({{ k.parent }}): def _deserialize(self, data: Any) -> bytes: return base64.b64decode(data) - def _serialize(self, data: Any) -> Optional[str]: + def _serialize(self, data: Any, skip_empty: bool) -> Optional[str]: if data is None: return None return base64.b64encode(data).decode() @@ -458,7 +469,7 @@ class {{ k.name }}({{ k.parent }}): def _deserialize(self, data: Any) -> "Query": return Q(data) # type: ignore[no-any-return] - def _serialize(self, data: Any) -> Optional[Dict[str, Any]]: + def _serialize(self, data: Any, skip_empty: bool) -> Optional[Dict[str, Any]]: if data is None: return None return data.to_dict() # type: ignore[no-any-return] diff --git a/utils/templates/query.py.tpl b/utils/templates/query.py.tpl index 6816f2d07..2ca767487 100644 --- a/utils/templates/query.py.tpl +++ b/utils/templates/query.py.tpl @@ -185,6 +185,9 @@ class {{ k.name }}({{ parent }}): {{ arg.name }}: {{ arg.type }} = DEFAULT, {% endif %} {% endfor %} + {% if k.args and k.args[0].positional %} + /, + {% endif %} {% if k.args and not k.args[-1].positional %} *, {% endif %} diff --git a/utils/templates/types.py.tpl b/utils/templates/types.py.tpl index 4ee80d5cb..1cd1e9496 100644 --- a/utils/templates/types.py.tpl +++ b/utils/templates/types.py.tpl @@ -60,6 +60,9 @@ class {{ k.name }}({{ k.parent if k.parent else "AttrDict[Any]" }}): {{ arg.name }}: {{ arg.type }} = DEFAULT, {% endif %} {% endfor %} + {% if k.args and k.args[0].positional %} + /, + {% endif %} {% if k.args and not k.args[-1].positional %} *, {% endif %}