From 660425779c932763661b8703473535074ed43fe9 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Tue, 21 Jan 2025 11:44:57 +0400 Subject: [PATCH] Auto-generated code for main --- elasticsearch/_async/client/__init__.py | 843 +++++++++++++++++++----- elasticsearch/_async/client/cat.py | 86 +-- elasticsearch/_async/client/indices.py | 83 --- elasticsearch/_async/client/security.py | 585 ++++++++++------ elasticsearch/_sync/client/__init__.py | 843 +++++++++++++++++++----- elasticsearch/_sync/client/cat.py | 86 +-- elasticsearch/_sync/client/indices.py | 83 --- elasticsearch/_sync/client/security.py | 585 ++++++++++------ elasticsearch/dsl/types.py | 4 +- 9 files changed, 2204 insertions(+), 994 deletions(-) diff --git a/elasticsearch/_async/client/__init__.py b/elasticsearch/_async/client/__init__.py index d4524deda..91f6ed91f 100644 --- a/elasticsearch/_async/client/__init__.py +++ b/elasticsearch/_async/client/__init__.py @@ -1117,38 +1117,119 @@ async def create( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Index a document. Adds a JSON document to the specified data stream or index - and makes it searchable. If the target is an index and the document already exists, - the request updates the document and increments its version. + Create a new document in the index. You can index a new JSON document with the + `//_doc/` or `//_create/<_id>` APIs Using `_create` guarantees + that the document is indexed only if it does not already exist. It returns a + 409 response when a document with a same ID already exists in the index. To update + an existing document, you must use the `//_doc/` API. If the Elasticsearch + security features are enabled, you must have the following index privileges for + the target data stream, index, or index alias: * To add a document using the + `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, + you must have the `create_doc`, `create`, `index`, or `write` index privilege. + * To automatically create a data stream or index with this API request, you must + have the `auto_configure`, `create_index`, or `manage` index privilege. Automatic + data stream creation requires a matching index template with data stream enabled. + **Automatically create data streams and indices** If the request's target doesn't + exist and matches an index template with a `data_stream` definition, the index + operation automatically creates the data stream. If the target doesn't exist + and doesn't match a data stream template, the operation automatically creates + the index and applies any matching index templates. NOTE: Elasticsearch includes + several built-in index templates. To avoid naming collisions with these templates, + refer to index pattern documentation. If no mapping exists, the index operation + creates a dynamic mapping. By default, new fields and objects are automatically + added to the mapping if needed. Automatic index creation is controlled by the + `action.auto_create_index` setting. If it is `true`, any index can be created + automatically. You can modify this setting to explicitly allow or block automatic + creation of indices that match specified patterns or set it to `false` to turn + off automatic index creation entirely. Specify a comma-separated list of patterns + you want to allow or prefix each pattern with `+` or `-` to indicate whether + it should be allowed or blocked. When a list is specified, the default behaviour + is to disallow. NOTE: The `action.auto_create_index` setting affects the automatic + creation of indices only. It does not affect the creation of data streams. **Routing** + By default, shard placement — or routing — is controlled by using a hash of the + document's ID value. For more explicit control, the value fed into the hash function + used by the router can be directly specified on a per-operation basis using the + `routing` parameter. When setting up explicit mapping, you can also use the `_routing` + field to direct the index operation to extract the routing value from the document + itself. This does come at the (very minimal) cost of an additional document parsing + pass. If the `_routing` mapping is defined and set to be required, the index + operation will fail if no routing value is provided or extracted. NOTE: Data + streams do not support custom routing unless they were created with the `allow_custom_routing` + setting enabled in the template. **Distributed** The index operation is directed + to the primary shard based on its route and performed on the actual node containing + this shard. After the primary shard completes the operation, if needed, the update + is distributed to applicable replicas. **Active shards** To improve the resiliency + of writes to the system, indexing operations can be configured to wait for a + certain number of active shard copies before proceeding with the operation. If + the requisite number of active shard copies are not available, then the write + operation must wait and retry, until either the requisite shard copies have started + or a timeout occurs. By default, write operations only wait for the primary shards + to be active before proceeding (that is to say `wait_for_active_shards` is `1`). + This default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. + To alter this behavior per operation, use the `wait_for_active_shards request` + parameter. Valid values are all or any positive integer up to the total number + of configured copies per shard in the index (which is `number_of_replicas`+1). + Specifying a negative value or a number greater than the number of shard copies + will throw an error. For example, suppose you have a cluster of three nodes, + A, B, and C and you create an index index with the number of replicas set to + 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt + an indexing operation, by default the operation will only ensure the primary + copy of each shard is available before proceeding. This means that even if B + and C went down and A hosted the primary shard copies, the indexing operation + would still proceed with only one copy of the data. If `wait_for_active_shards` + is set on the request to `3` (and all three nodes are up), the indexing operation + will require 3 active shard copies before proceeding. This requirement should + be met because there are 3 active nodes in the cluster, each one holding a copy + of the shard. However, if you set `wait_for_active_shards` to `all` (or to `4`, + which is the same in this situation), the indexing operation will not proceed + as you do not have all 4 copies of each shard active in the index. The operation + will timeout unless a new node is brought up in the cluster to host the fourth + copy of the shard. It is important to note that this setting greatly reduces + the chances of the write operation not writing to the requisite number of shard + copies, but it does not completely eliminate the possibility, because this check + occurs before the write operation starts. After the write operation is underway, + it is still possible for replication to fail on any number of shard copies but + still succeed on the primary. The `_shards` section of the API response reveals + the number of shard copies on which replication succeeded and failed. ``_ - :param index: Name of the data stream or index to target. If the target doesn’t + :param index: The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. If - the target doesn’t exist and doesn’t match a data stream template, this request + the target doesn't exist and doesn’t match a data stream template, this request creates the index. - :param id: Unique identifier for the document. + :param id: A unique identifier for the document. To automatically generate a + document ID, use the `POST //_doc/` request format. :param document: - :param pipeline: ID of the pipeline to use to preprocess incoming documents. - If the index has a default ingest pipeline specified, then setting the value - to `_none` disables the default ingest pipeline for this request. If a final - pipeline is configured it will always run, regardless of the value of this + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. + If the index has a default ingest pipeline specified, setting the value to + `_none` turns off the default ingest pipeline for this request. If a final + pipeline is configured, it will always run regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period the request waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. + :param routing: A custom value that is used to route operations to a specific + shard. + :param timeout: The period the request waits for the following operations: automatic + index creation, dynamic mapping updates, waiting for active shards. Elasticsearch + waits for at least the specified timeout period before failing. The actual + wait time could be longer, particularly when multiple waits occur. This parameter + is useful for situations where the primary shard assigned to perform the + operation might not be available when the operation runs. Some reasons for + this might be that the primary shard is currently recovering from a gateway + or undergoing relocation. By default, the operation will wait on the primary + shard to become available for at least 1 minute before failing and responding + with an error. The actual wait time could be longer, particularly when multiple + waits occur. + :param version: The explicit version number for concurrency control. It must + be a non-negative long number. + :param version_type: The version type. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. You can set it to `all` or any positive + integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1223,29 +1304,57 @@ async def delete( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a document. Removes a JSON document from the specified index. + Delete a document. Remove a JSON document from the specified index. NOTE: You + cannot send deletion requests directly to a data stream. To delete a document + in a data stream, you must target the backing index containing the document. + **Optimistic concurrency control** Delete operations can be made conditional + and only be performed if the last modification to the document was assigned the + sequence number and primary term specified by the `if_seq_no` and `if_primary_term` + parameters. If a mismatch is detected, the operation will result in a `VersionConflictException` + and a status code of `409`. **Versioning** Each document indexed is versioned. + When deleting a document, the version can be specified to make sure the relevant + document you are trying to delete is actually being deleted and it has not changed + in the meantime. Every write operation run on a document, deletes included, causes + its version to be incremented. The version number of a deleted document remains + available for a short time after deletion to allow for control of concurrent + operations. The length of time for which a deleted document's version remains + available is determined by the `index.gc_deletes` index setting. **Routing** + If routing is used during indexing, the routing value also needs to be specified + to delete a document. If the `_routing` mapping is set to `required` and no routing + value is specified, the delete API throws a `RoutingMissingException` and rejects + the request. For example: ``` DELETE /my-index-000001/_doc/1?routing=shard-1 + ``` This request deletes the document with ID 1, but it is routed based on the + user. The document is not deleted if the correct routing is not specified. **Distributed** + The delete operation gets hashed into a specific shard ID. It then gets redirected + into the primary shard within that ID group and replicated (if needed) to shard + replicas within that ID group. ``_ - :param index: Name of the target index. - :param id: Unique identifier for the document. + :param index: The name of the target index. + :param id: A unique identifier for the document. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period to wait for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. + :param routing: A custom value used to route operations to a specific shard. + :param timeout: The period to wait for active shards. This parameter is useful + for situations where the primary shard assigned to perform the delete operation + might not be available when the delete operation runs. Some reasons for this + might be that the primary shard is currently recovering from a store or undergoing + relocation. By default, the delete operation will wait on the primary shard + to become available for up to 1 minute before failing and responding with + an error. + :param version: An explicit version number for concurrency control. It must match + the current version of the document for the request to succeed. + :param version_type: The version type. + :param wait_for_active_shards: The minimum number of shard copies that must be + active before proceeding with the operation. You can set it to `all` or any + positive integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1640,32 +1749,54 @@ async def exists( ] = None, ) -> HeadApiResponse: """ - Check a document. Checks if a specified document exists. + Check a document. Verify that a document exists. For example, check to see if + a document with the `_id` 0 exists: ``` HEAD my-index-000001/_doc/0 ``` If the + document exists, the API returns a status code of `200 - OK`. If the document + doesn’t exist, the API returns `404 - Not Found`. **Versioning support** You + can use the `version` parameter to check the document only if its current version + is equal to the specified one. Internally, Elasticsearch has marked the old document + as deleted and added an entirely new document. The old version of the document + doesn't disappear immediately, although you won't be able to access it. Elasticsearch + cleans up deleted documents in the background as you continue to index more data. ``_ - :param index: Comma-separated list of data streams, indices, and aliases. Supports - wildcards (`*`). - :param id: Identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param index: A comma-separated list of data streams, indices, and aliases. It + supports wildcards (`*`). + :param id: A unique document identifier. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. If it is + set to `_local`, the operation will prefer to be run on a local allocated + shard when possible. If it is set to a custom value, the value is used to + guarantee that the same shards will be used for the same custom value. This + can help with "jumping values" when hitting different shards in different + refresh states. A sample value can be something like the web session ID or + the user name. :param realtime: If `true`, the request is real-time as opposed to near-real-time. - :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. - :param routing: Target the specified primary shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. - :param source_excludes: A comma-separated list of source fields to exclude in - the response. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :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_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` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to false. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` parameter defaults to + `false`. :param version: Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1741,29 +1872,32 @@ async def exists_source( ] = None, ) -> HeadApiResponse: """ - Check for a document source. Checks if a document's `_source` is stored. + Check for a document source. Check whether a document source exists in an index. + For example: ``` HEAD my-index-000001/_source/1 ``` A document's source is not + available if it is disabled in the mapping. ``_ - :param index: Comma-separated list of data streams, indices, and aliases. Supports - wildcards (`*`). - :param id: Identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param realtime: If true, the request is real-time as opposed to near-real-time. - :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. - :param routing: Target the specified primary shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. + :param index: A comma-separated list of data streams, indices, and aliases. It + supports wildcards (`*`). + :param id: A unique identifier for the document. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. + :param realtime: If `true`, the request is real-time as opposed to near-real-time. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :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_excludes: A comma-separated list of source fields to exclude in the response. :param source_includes: A comma-separated list of source fields to include in the response. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2081,36 +2215,78 @@ async def get( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a document by its ID. Retrieves the document with the specified ID from an - index. + Get a document by its ID. Get a document and its source or stored fields from + an index. By default, this API is realtime and is not affected by the refresh + rate of the index (when data will become visible for search). In the case where + stored fields are requested with the `stored_fields` parameter and the document + has been updated but is not yet refreshed, the API will have to parse and analyze + the source to extract the stored fields. To turn off realtime behavior, set the + `realtime` parameter to false. **Source filtering** By default, the API returns + the contents of the `_source` field unless you have used the `stored_fields` + parameter or the `_source` field is turned off. You can turn off `_source` retrieval + by using the `_source` parameter: ``` GET my-index-000001/_doc/0?_source=false + ``` If you only need one or two fields from the `_source`, use the `_source_includes` + or `_source_excludes` parameters to include or filter out particular fields. + This can be helpful with large documents where partial retrieval can save on + network overhead Both parameters take a comma separated list of fields or wildcard + expressions. For example: ``` GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities + ``` If you only want to specify includes, you can use a shorter notation: ``` + GET my-index-000001/_doc/0?_source=*.id ``` **Routing** If routing is used during + indexing, the routing value also needs to be specified to retrieve a document. + For example: ``` GET my-index-000001/_doc/2?routing=user1 ``` This request gets + the document with ID 2, but it is routed based on the user. The document is not + fetched if the correct routing is not specified. **Distributed** The GET operation + is hashed into a specific shard ID. It is then redirected to one of the replicas + within that shard ID and returns the result. The replicas are the primary shard + and its replicas within that shard ID group. This means that the more replicas + you have, the better your GET scaling will be. **Versioning support** You can + use the `version` parameter to retrieve the document only if its current version + is equal to the specified one. Internally, Elasticsearch has marked the old document + as deleted and added an entirely new document. The old version of the document + doesn't disappear immediately, although you won't be able to access it. Elasticsearch + cleans up deleted documents in the background as you continue to index more data. ``_ - :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. - :param force_synthetic_source: Should this request force synthetic _source? Use - this to test if the mapping supports synthetic _source and to get a sense - of the worst case performance. Fetches with this enabled will be slower the - enabling synthetic source natively in the index. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param index: The name of the index that contains the document. + :param id: A unique document identifier. + :param force_synthetic_source: Indicates whether the request forces synthetic + `_source`. Use this paramater to test if the mapping supports synthetic `_source` + and to get a sense of the worst case performance. Fetches with this parameter + enabled will be slower than enabling synthetic source natively in the index. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. If it is + set to `_local`, the operation will prefer to be run on a local allocated + shard when possible. If it is set to a custom value, the value is used to + guarantee that the same shards will be used for the same custom value. This + can help with "jumping values" when hitting different shards in different + refresh states. A sample value can be something like the web session ID or + the user name. :param realtime: If `true`, the request is real-time as opposed to near-real-time. - :param refresh: If true, Elasticsearch refreshes the affected shards to make - this operation visible to search. If false, do nothing with refreshes. - :param routing: Target the specified primary shard. - :param source: True or false to return the _source field or not, or a list of - fields to return. - :param source_excludes: A comma-separated list of source fields to exclude in - the response. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :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_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` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to false. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: internal, external, external_gte. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` parameter defaults to + `false`. Only leaf fields can be retrieved with the `stored_field` option. + Object fields can't be returned;​if specified, the request fails. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2303,29 +2479,34 @@ async def get_source( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a document's source. Returns the source of a document. + Get a document's source. Get the source of a document. For example: ``` GET my-index-000001/_source/1 + ``` You can use the source filtering parameters to control which parts of the + `_source` are returned: ``` GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities + ``` ``_ - :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param realtime: Boolean) If true, the request is real-time as opposed to near-real-time. - :param refresh: If true, Elasticsearch refreshes the affected shards to make - this operation visible to search. If false, do nothing with refreshes. - :param routing: Target the specified primary shard. - :param source: True or false to return the _source field or not, or a list of - fields to return. + :param index: The name of the index that contains the document. + :param id: A unique document identifier. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. + :param realtime: If `true`, the request is real-time as opposed to near-real-time. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :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_excludes: A comma-separated list of source fields to exclude in the response. :param source_includes: A comma-separated list of source fields to include in the response. - :param stored_fields: - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: internal, external, external_gte. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2480,44 +2661,170 @@ async def index( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Index a document. Adds a JSON document to the specified data stream or index - and makes it searchable. If the target is an index and the document already exists, - the request updates the document and increments its version. + Create or update a document in an index. Add a JSON document to the specified + data stream or index and make it searchable. If the target is an index and the + document already exists, the request updates the document and increments its + version. NOTE: You cannot use this API to send update requests for existing documents + in a data stream. If the Elasticsearch security features are enabled, you must + have the following index privileges for the target data stream, index, or index + alias: * To add or overwrite a document using the `PUT //_doc/<_id>` + request format, you must have the `create`, `index`, or `write` index privilege. + * To add a document using the `POST //_doc/` request format, you must + have the `create_doc`, `create`, `index`, or `write` index privilege. * To automatically + create a data stream or index with this API request, you must have the `auto_configure`, + `create_index`, or `manage` index privilege. Automatic data stream creation requires + a matching index template with data stream enabled. NOTE: Replica shards might + not all be started when an indexing operation returns successfully. By default, + only the primary is required. Set `wait_for_active_shards` to change this default + behavior. **Automatically create data streams and indices** If the request's + target doesn't exist and matches an index template with a `data_stream` definition, + the index operation automatically creates the data stream. If the target doesn't + exist and doesn't match a data stream template, the operation automatically creates + the index and applies any matching index templates. NOTE: Elasticsearch includes + several built-in index templates. To avoid naming collisions with these templates, + refer to index pattern documentation. If no mapping exists, the index operation + creates a dynamic mapping. By default, new fields and objects are automatically + added to the mapping if needed. Automatic index creation is controlled by the + `action.auto_create_index` setting. If it is `true`, any index can be created + automatically. You can modify this setting to explicitly allow or block automatic + creation of indices that match specified patterns or set it to `false` to turn + off automatic index creation entirely. Specify a comma-separated list of patterns + you want to allow or prefix each pattern with `+` or `-` to indicate whether + it should be allowed or blocked. When a list is specified, the default behaviour + is to disallow. NOTE: The `action.auto_create_index` setting affects the automatic + creation of indices only. It does not affect the creation of data streams. **Optimistic + concurrency control** Index operations can be made conditional and only be performed + if the last modification to the document was assigned the sequence number and + primary term specified by the `if_seq_no` and `if_primary_term` parameters. If + a mismatch is detected, the operation will result in a `VersionConflictException` + and a status code of `409`. **Routing** By default, shard placement — or routing + — is controlled by using a hash of the document's ID value. For more explicit + control, the value fed into the hash function used by the router can be directly + specified on a per-operation basis using the `routing` parameter. When setting + up explicit mapping, you can also use the `_routing` field to direct the index + operation to extract the routing value from the document itself. This does come + at the (very minimal) cost of an additional document parsing pass. If the `_routing` + mapping is defined and set to be required, the index operation will fail if no + routing value is provided or extracted. NOTE: Data streams do not support custom + routing unless they were created with the `allow_custom_routing` setting enabled + in the template. **Distributed** The index operation is directed to the primary + shard based on its route and performed on the actual node containing this shard. + After the primary shard completes the operation, if needed, the update is distributed + to applicable replicas. **Active shards** To improve the resiliency of writes + to the system, indexing operations can be configured to wait for a certain number + of active shard copies before proceeding with the operation. If the requisite + number of active shard copies are not available, then the write operation must + wait and retry, until either the requisite shard copies have started or a timeout + occurs. By default, write operations only wait for the primary shards to be active + before proceeding (that is to say `wait_for_active_shards` is `1`). This default + can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. + To alter this behavior per operation, use the `wait_for_active_shards request` + parameter. Valid values are all or any positive integer up to the total number + of configured copies per shard in the index (which is `number_of_replicas`+1). + Specifying a negative value or a number greater than the number of shard copies + will throw an error. For example, suppose you have a cluster of three nodes, + A, B, and C and you create an index index with the number of replicas set to + 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt + an indexing operation, by default the operation will only ensure the primary + copy of each shard is available before proceeding. This means that even if B + and C went down and A hosted the primary shard copies, the indexing operation + would still proceed with only one copy of the data. If `wait_for_active_shards` + is set on the request to `3` (and all three nodes are up), the indexing operation + will require 3 active shard copies before proceeding. This requirement should + be met because there are 3 active nodes in the cluster, each one holding a copy + of the shard. However, if you set `wait_for_active_shards` to `all` (or to `4`, + which is the same in this situation), the indexing operation will not proceed + as you do not have all 4 copies of each shard active in the index. The operation + will timeout unless a new node is brought up in the cluster to host the fourth + copy of the shard. It is important to note that this setting greatly reduces + the chances of the write operation not writing to the requisite number of shard + copies, but it does not completely eliminate the possibility, because this check + occurs before the write operation starts. After the write operation is underway, + it is still possible for replication to fail on any number of shard copies but + still succeed on the primary. The `_shards` section of the API response reveals + the number of shard copies on which replication succeeded and failed. **No operation + (noop) updates** When updating a document by using this API, a new version of + the document is always created even if the document hasn't changed. If this isn't + acceptable use the `_update` API with `detect_noop` set to `true`. The `detect_noop` + option isn't available on this API because it doesn’t fetch the old source and + isn't able to compare it against the new source. There isn't a definitive rule + for when noop updates aren't acceptable. It's a combination of lots of factors + like how frequently your data source sends updates that are actually noops and + how many queries per second Elasticsearch runs on the shard receiving the updates. + **Versioning** Each indexed document is given a version number. By default, internal + versioning is used that starts at 1 and increments with each update, deletes + included. Optionally, the version number can be set to an external value (for + example, if maintained in a database). To enable this functionality, `version_type` + should be set to `external`. The value provided must be a numeric, long value + greater than or equal to 0, and less than around `9.2e+18`. NOTE: Versioning + is completely real time, and is not affected by the near real time aspects of + search operations. If no version is provided, the operation runs without any + version checks. When using the external version type, the system checks to see + if the version number passed to the index request is greater than the version + of the currently stored document. If true, the document will be indexed and the + new version number used. If the value provided is less than or equal to the stored + document's version number, a version conflict will occur and the index operation + will fail. For example: ``` PUT my-index-000001/_doc/1?version=2&version_type=external + { "user": { "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. ``_ - :param index: Name of the data stream or index to target. + :param index: The name of the data stream or index to target. If the target doesn't + exist and matches the name or wildcard (`*`) pattern of an index template + with a `data_stream` definition, this request creates the data stream. If + the target doesn't exist and doesn't match a data stream template, this request + creates the index. You can check for existing targets with the resolve index + API. :param document: - :param id: Unique identifier for the document. + :param id: A unique identifier for the document. To automatically generate a + document ID, use the `POST //_doc/` request format and omit this + parameter. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. - :param op_type: Set to create to only index the document if it does not already + :param op_type: Set to `create` to only index the document if it does not already exist (put if absent). If a document with the specified `_id` already exists, - the indexing operation will fail. Same as using the `/_create` endpoint. - Valid values: `index`, `create`. If document id is specified, it defaults - to `index`. Otherwise, it defaults to `create`. - :param pipeline: ID of the pipeline to use to preprocess incoming documents. + the indexing operation will fail. The behavior is the same as using the `/_create` + endpoint. If a document ID is specified, this paramater defaults to `index`. + Otherwise, it defaults to `create`. If the request targets a data stream, + an `op_type` of `create` is required. + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. :param require_alias: If `true`, the destination must be an index alias. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period the request waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param routing: A custom value that is used to route operations to a specific + shard. + :param timeout: The period the request waits for the following operations: automatic + index creation, dynamic mapping updates, waiting for active shards. This + parameter is useful for situations where the primary shard assigned to perform + the operation might not be available when the operation runs. Some reasons + for this might be that the primary shard is currently recovering from a gateway + or undergoing relocation. By default, the operation will wait on the primary + shard to become available for at least 1 minute before failing and responding + with an error. The actual wait time could be longer, particularly when multiple + waits occur. + :param version: An explicit version number for concurrency control. It must be + a non-negative long number. + :param version_type: The version type. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to all or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. You can set it to `all` or any positive + integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -3506,33 +3813,191 @@ async def reindex( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Reindex documents. Copies documents from a source to a destination. The source - can be any existing index, alias, or data stream. The destination must differ - from the source. For example, you cannot reindex a data stream into itself. + Reindex documents. Copy documents from a source to a destination. You can copy + all documents to the destination index or reindex a subset of the documents. + The source can be any existing index, alias, or data stream. The destination + must differ from the source. For example, you cannot reindex a data stream into + itself. IMPORTANT: Reindex requires `_source` to be enabled for all documents + in the source. The destination should be configured as wanted before calling + the reindex API. Reindex does not copy the settings from the source or its associated + template. Mappings, shard counts, and replicas, for example, must be configured + ahead of time. If the Elasticsearch security features are enabled, you must have + the following security privileges: * The `read` index privilege for the source + data stream, index, or alias. * The `write` index privilege for the destination + data stream, index, or index alias. * To automatically create a data stream or + index with a reindex API request, you must have the `auto_configure`, `create_index`, + or `manage` index privilege for the destination data stream, index, or alias. + * If reindexing from a remote cluster, the `source.remote.user` must have the + `monitor` cluster privilege and the `read` index privilege for the source data + stream, index, or alias. If reindexing from a remote cluster, you must explicitly + allow the remote host in the `reindex.remote.whitelist` setting. Automatic data + stream creation requires a matching index template with data stream enabled. + The `dest` element can be configured like the index API to control optimistic + concurrency control. Omitting `version_type` or setting it to `internal` causes + Elasticsearch to blindly dump documents into the destination, overwriting any + that happen to have the same ID. Setting `version_type` to `external` causes + Elasticsearch to preserve the `version` from the source, create any documents + that are missing, and update any documents that have an older version in the + destination than they do in the source. Setting `op_type` to `create` causes + the reindex API to create only missing documents in the destination. All existing + documents will cause a version conflict. IMPORTANT: Because data streams are + append-only, any reindex request to a destination data stream must have an `op_type` + of `create`. A reindex can only add new documents to a destination data stream. + It cannot update existing documents in a destination data stream. By default, + version conflicts abort the reindex process. To continue reindexing if there + are conflicts, set the `conflicts` request body property to `proceed`. In this + case, the response includes a count of the version conflicts that were encountered. + Note that the handling of other error types is unaffected by the `conflicts` + property. Additionally, if you opt to count version conflicts, the operation + could attempt to reindex more documents from the source than `max_docs` until + it has successfully indexed `max_docs` documents into the target or it has gone + through every document in the source query. NOTE: The reindex API makes no effort + to handle ID collisions. The last document written will "win" but the order isn't + usually predictable so it is not a good idea to rely on this behavior. Instead, + make sure that IDs are unique by using a script. **Running reindex asynchronously** + If the request contains `wait_for_completion=false`, Elasticsearch performs some + preflight checks, launches the request, and returns a task you can use to cancel + or get the status of the task. Elasticsearch creates a record of this task as + a document at `_tasks/`. **Reindex from multiple sources** If you have + many sources to reindex it is generally better to reindex them one at a time + rather than using a glob pattern to pick up multiple sources. That way you can + resume the process if there are any errors by removing the partially completed + source and starting over. It also makes parallelizing the process fairly simple: + split the list of sources to reindex and run each list in parallel. For example, + you can use a bash script like this: ``` for index in i1 i2 i3 i4 i5; do curl + -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{ "source": + { "index": "'$index'" }, "dest": { "index": "'$index'-reindexed" } }' done ``` + **Throttling** Set `requests_per_second` to any positive decimal number (`1.4`, + `6`, `1000`, for example) to throttle the rate at which reindex issues batches + of index operations. Requests are throttled by padding each batch with a wait + time. To turn off throttling, set `requests_per_second` to `-1`. The throttling + is done by waiting between batches so that the scroll that reindex uses internally + can be given a timeout that takes into account the padding. The padding time + is the difference between the batch size divided by the `requests_per_second` + and the time spent writing. By default the batch size is `1000`, so if `requests_per_second` + is set to `500`: ``` target_time = 1000 / 500 per second = 2 seconds wait_time + = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds ``` Since the + batch is issued as a single bulk request, large batch sizes cause Elasticsearch + to create many requests and then wait for a while before starting the next set. + This is "bursty" instead of "smooth". **Slicing** Reindex supports sliced scroll + to parallelize the reindexing process. This parallelization can improve efficiency + and provide a convenient way to break the request down into smaller parts. NOTE: + Reindexing from remote clusters does not support manual or automatic slicing. + You can slice a reindex request manually by providing a slice ID and total number + of slices to each request. You can also let reindex automatically parallelize + by using sliced scroll to slice on `_id`. The `slices` parameter specifies the + number of slices to use. Adding `slices` to the reindex request just automates + the manual process, creating sub-requests which means it has some quirks: * You + can see these requests in the tasks API. These sub-requests are "child" tasks + of the task for the request with slices. * Fetching the status of the task for + the request with `slices` only contains the status of completed slices. * These + sub-requests are individually addressable for things like cancellation and rethrottling. + * Rethrottling the request with `slices` will rethrottle the unfinished sub-request + proportionally. * Canceling the request with `slices` will cancel each sub-request. + * Due to the nature of `slices`, each sub-request won't get a perfectly even + portion of the documents. All documents will be addressed, but some slices may + be larger than others. Expect larger slices to have a more even distribution. + * Parameters like `requests_per_second` and `max_docs` on a request with `slices` + are distributed proportionally to each sub-request. Combine that with the previous + point about distribution being uneven and you should conclude that using `max_docs` + with `slices` might not result in exactly `max_docs` documents being reindexed. + * Each sub-request gets a slightly different snapshot of the source, though these + are all taken at approximately the same time. If slicing automatically, setting + `slices` to `auto` will choose a reasonable number for most indices. If slicing + manually or otherwise tuning automatic slicing, use the following guidelines. + Query performance is most efficient when the number of slices is equal to the + number of shards in the index. If that number is large (for example, `500`), + choose a lower number as too many slices will hurt performance. Setting slices + higher than the number of shards generally does not improve efficiency and adds + overhead. Indexing performance scales linearly across available resources with + the number of slices. Whether query or indexing performance dominates the runtime + depends on the documents being reindexed and cluster resources. **Modify documents + during reindexing** Like `_update_by_query`, reindex operations support a script + that modifies the document. Unlike `_update_by_query`, the script is allowed + to modify the document's metadata. Just as in `_update_by_query`, you can set + `ctx.op` to change the operation that is run on the destination. For example, + set `ctx.op` to `noop` if your script decides that the document doesn’t have + to be indexed in the destination. This "no operation" will be reported in the + `noop` counter in the response body. Set `ctx.op` to `delete` if your script + decides that the document must be deleted from the destination. The deletion + will be reported in the `deleted` counter in the response body. Setting `ctx.op` + to anything else will return an error, as will setting any other field in `ctx`. + Think of the possibilities! Just be careful; you are able to change: * `_id` + * `_index` * `_version` * `_routing` Setting `_version` to `null` or clearing + it from the `ctx` map is just like not sending the version in an indexing request. + It will cause the document to be overwritten in the destination regardless of + the version on the target or the version type you use in the reindex API. **Reindex + from remote** Reindex supports reindexing from a remote Elasticsearch cluster. + The `host` parameter must contain a scheme, host, port, and optional path. The + `username` and `password` parameters are optional and when they are present the + reindex operation will connect to the remote Elasticsearch node using basic authentication. + Be sure to use HTTPS when using basic authentication or the password will be + sent in plain text. There are a range of settings available to configure the + behavior of the HTTPS connection. When using Elastic Cloud, it is also possible + to authenticate against the remote cluster through the use of a valid API key. + Remote hosts must be explicitly allowed with the `reindex.remote.whitelist` setting. + It can be set to a comma delimited list of allowed remote host and port combinations. + Scheme is ignored; only the host and port are used. For example: ``` reindex.remote.whitelist: + [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*"] ``` The list of + allowed hosts must be configured on any nodes that will coordinate the reindex. + This feature should work with remote clusters of any version of Elasticsearch. + This should enable you to upgrade from any version of Elasticsearch to the current + version by reindexing from a cluster of the old version. WARNING: Elasticsearch + does not support forward compatibility across major versions. For example, you + cannot reindex from a 7.x cluster into a 6.x cluster. To enable queries sent + to older versions of Elasticsearch, the `query` parameter is sent directly to + the remote host without validation or modification. NOTE: Reindexing from remote + clusters does not support manual or automatic slicing. Reindexing from a remote + server uses an on-heap buffer that defaults to a maximum size of 100mb. If the + remote index includes very large documents you'll need to use a smaller batch + size. It is also possible to set the socket read timeout on the remote connection + with the `socket_timeout` field and the connection timeout with the `connect_timeout` + field. Both default to 30 seconds. **Configuring SSL parameters** Reindex from + remote supports configurable SSL settings. These must be specified in the `elasticsearch.yml` + file, with the exception of the secure settings, which you add in the Elasticsearch + keystore. It is not possible to configure SSL in the body of the reindex request. ``_ :param dest: The destination you are copying to. :param source: The source you are copying from. - :param conflicts: Set to proceed to continue reindexing even if there are conflicts. - :param max_docs: The maximum number of documents to reindex. + :param conflicts: Indicates whether to continue reindexing even when there are + conflicts. + :param max_docs: The maximum number of documents to reindex. By default, all + documents are reindexed. If it is a value less then or equal to `scroll_size`, + a scroll will not be used to retrieve the results for the operation. If `conflicts` + is set to `proceed`, the reindex operation could attempt to reindex more + documents from the source than `max_docs` until it has successfully indexed + `max_docs` documents into the target or it has gone through every document + in the source query. :param refresh: If `true`, the request refreshes affected shards to make this operation visible to search. :param requests_per_second: The throttle for this request in sub-requests per - second. Defaults to no throttle. + second. By default, there is no throttle. :param require_alias: If `true`, the destination must be an index alias. :param script: The script to run to update the document source or metadata when reindexing. - :param scroll: Specifies how long a consistent view of the index should be maintained - for scrolled search. + :param scroll: The period of time that a consistent view of the index should + be maintained for scrolled search. :param size: - :param slices: The number of slices this task should be divided into. Defaults - to 1 slice, meaning the task isn’t sliced into subtasks. - :param timeout: Period each indexing waits for automatic index creation, dynamic - mapping updates, and waiting for active shards. + :param slices: The number of slices this task should be divided into. It defaults + to one slice, which means the task isn't sliced into subtasks. Reindex supports + sliced scroll to parallelize the reindexing process. This parallelization + can improve efficiency and provide a convenient way to break the request + down into smaller parts. NOTE: Reindexing from remote clusters does not support + manual or automatic slicing. If set to `auto`, Elasticsearch chooses the + number of slices to use. This setting will use one slice per shard, up to + a certain limit. If there are multiple sources, it will choose the number + of slices based on the index or backing index with the smallest number of + shards. + :param timeout: The period each indexing waits for automatic index creation, + dynamic mapping updates, and waiting for active shards. By default, Elasticsearch + waits for at least one minute before failing. The actual wait time could + be longer, particularly when multiple waits occur. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. Set it to `all` or any positive integer + up to the total number of shards in the index (`number_of_replicas+1`). The + default value is one, which means it waits for each primary shard to be active. :param wait_for_completion: If `true`, the request blocks until the operation is complete. """ @@ -3605,13 +4070,17 @@ async def reindex_rethrottle( ) -> ObjectApiResponse[t.Any]: """ Throttle a reindex operation. Change the number of requests per second for a - particular reindex operation. + particular reindex operation. For example: ``` POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1 + ``` Rethrottling that speeds up the query takes effect immediately. Rethrottling + that slows down the query will take effect after completing the current batch. + This behavior prevents scroll timeouts. ``_ - :param task_id: Identifier for the task. + :param task_id: The task identifier, which can be found by using the tasks API. :param requests_per_second: The throttle for this request in sub-requests per - second. + second. It can be either `-1` to turn off throttling or any decimal number + like `1.7` or `12` to throttle to that level. """ if task_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'task_id'") @@ -5058,46 +5527,60 @@ async def update( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a document. Updates a document by running a script or passing a partial - document. + Update a document. Update a document by running a script or passing a partial + document. If the Elasticsearch security features are enabled, you must have the + `index` or `write` index privilege for the target index or index alias. The script + can update, delete, or skip modifying the document. The API also supports passing + a partial document, which is merged into the existing document. To fully replace + an existing document, use the index API. This operation: * Gets the document + (collocated with the shard) from the index. * Runs the specified script. * Indexes + the result. The document must still be reindexed, but using this API removes + some network roundtrips and reduces chances of version conflicts between the + GET and the index operation. The `_source` field must be enabled to use this + API. In addition to `_source`, you can access the following variables through + the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the + current timestamp). ``_ - :param index: The name of the index - :param id: Document ID - :param detect_noop: Set to false to disable setting 'result' in the response - to 'noop' if no change to the document occurred. - :param doc: A partial update to an existing document. - :param doc_as_upsert: Set to true to use the contents of 'doc' as the value of - 'upsert' + :param index: The name of the target index. By default, the index is created + automatically if it doesn't exist. + :param id: A unique identifier for the document to be updated. + :param detect_noop: If `true`, the `result` in the response is set to `noop` + (no operation) when there are no changes to the document. + :param doc: A partial update to an existing document. If both `doc` and `script` + are specified, `doc` is ignored. + :param doc_as_upsert: If `true`, use the contents of 'doc' as the value of 'upsert'. + NOTE: Using ingest pipelines with `doc_as_upsert` is not supported. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. :param lang: The script language. :param refresh: If 'true', Elasticsearch refreshes the affected shards to make - this operation visible to search, if 'wait_for' then wait for a refresh to - make this operation visible to search, if 'false' do nothing with refreshes. - :param require_alias: If true, the destination must be an index alias. - :param retry_on_conflict: Specify how many times should the operation be retried + this operation visible to search. If 'wait_for', it waits for a refresh to + make this operation visible to search. If 'false', it does nothing with refreshes. + :param require_alias: If `true`, the destination must be an index alias. + :param retry_on_conflict: The number of times the operation should be retried when a conflict occurs. - :param routing: Custom value used to route operations to a specific shard. - :param script: Script to execute to update the document. - :param scripted_upsert: Set to true to execute the script whether or not the - document exists. - :param source: Set to false to disable source retrieval. You can also specify - a comma-separated list of the fields you want to retrieve. - :param source_excludes: Specify the source fields you want to exclude. - :param source_includes: Specify the source fields you want to retrieve. - :param timeout: Period to wait for dynamic mapping updates and active shards. - This guarantees Elasticsearch waits for at least the timeout before failing. - The actual wait time could be longer, particularly when multiple waits occur. + :param routing: A custom value used to route operations to a specific shard. + :param script: The script to run to update the document. + :param scripted_upsert: If `true`, run the script whether or not the document + exists. + :param source: If `false`, turn off source retrieval. You can also specify a + comma-separated list of the fields you want to retrieve. + :param source_excludes: The source fields you want to exclude. + :param source_includes: The source fields you want to retrieve. + :param timeout: The period to wait for the following operations: dynamic mapping + updates and waiting for active shards. Elasticsearch waits for at least the + timeout period before failing. The actual wait time could be longer, particularly + when multiple waits occur. :param upsert: If the document does not already exist, the contents of 'upsert' - are inserted as a new document. If the document exists, the 'script' is executed. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operations. Set to 'all' or any positive integer - up to the total number of shards in the index (number_of_replicas+1). Defaults - to 1 meaning the primary shard. + are inserted as a new document. If the document exists, the 'script' is run. + :param wait_for_active_shards: The number of copies of each shard that must be + active before proceeding with the operation. Set to 'all' or any positive + integer up to the total number of shards in the index (`number_of_replicas`+1). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") diff --git a/elasticsearch/_async/client/cat.py b/elasticsearch/_async/client/cat.py index 54c1c2b0d..a288d8056 100644 --- a/elasticsearch/_async/client/cat.py +++ b/elasticsearch/_async/client/cat.py @@ -56,8 +56,8 @@ async def aliases( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get aliases. Retrieves the cluster’s index aliases, including filter and routing - information. The API does not return data stream aliases. CAT APIs are only intended + Get aliases. Get the cluster's index aliases, including filter and routing information. + This API does not return data stream aliases. IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API. @@ -66,14 +66,19 @@ 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 expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. + :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 help: When set to `true` will output available columns. This option can't be combined with any other query string option. - :param master_timeout: Period to wait for a connection to the master node. + :param master_timeout: The period to wait for a connection to the master node. + If the master node is not available before the timeout expires, the request + fails and returns an error. To indicated that the request should never timeout, + you can set it to `-1`. :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. @@ -141,13 +146,13 @@ async def allocation( ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ Get shard allocation information. Get a snapshot of the number of shards allocated - to each data node and their disk space. IMPORTANT: cat APIs are only intended + to each data node and their disk space. IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. ``_ - :param node_id: Comma-separated list of node identifiers or names used to limit + :param node_id: A comma-separated list of node identifiers or names used to limit the returned information. :param bytes: The unit used to display byte values. :param format: Specifies the format to return the columnar data in, can be set @@ -225,17 +230,17 @@ async def component_templates( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get component templates. Returns information about component templates in a cluster. + Get component templates. Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that - specify index mappings, settings, and aliases. CAT APIs are only intended for - human consumption using the command line or Kibana console. They are not intended - for use by applications. For application consumption, use the get component template - API. + specify index mappings, settings, and aliases. IMPORTANT: CAT APIs are only intended + for human consumption using the command line or Kibana console. They are not + intended for use by applications. For application consumption, use the get component + template API. ``_ - :param name: The name of the component template. Accepts wildcard expressions. - If omitted, all component templates are returned. + :param name: The name of the component template. It accepts wildcard expressions. + If it is omitted, all component templates are returned. :param 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. @@ -245,7 +250,7 @@ async def component_templates( the local cluster state. If `false` the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node. - :param master_timeout: Period to wait for a connection to the master node. + :param master_timeout: The period to wait for a connection to the master node. :param s: List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting `:asc` or `:desc` as a suffix to the column name. @@ -307,17 +312,17 @@ async def count( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get a document count. Provides quick access to a document count for a data stream, + Get a document count. Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, - not deleted documents which have not yet been removed by the merge process. CAT - APIs are only intended for human consumption using the command line or Kibana + not deleted documents which have not yet been removed by the merge process. IMPORTANT: + CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API. ``_ - :param index: Comma-separated list of data streams, indices, and aliases used - to limit the request. Supports wildcards (`*`). To target all data streams + :param index: A comma-separated list of data streams, indices, and aliases used + to limit the request. It supports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`. :param format: Specifies the format to return the columnar data in, can be set to `text`, `json`, `cbor`, `yaml`, or `smile`. @@ -462,7 +467,7 @@ async def health( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get the cluster health status. IMPORTANT: cat APIs are only intended for human + Get the cluster health status. IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the cluster health API. This API is often used to check malfunctioning clusters. To help you track cluster @@ -526,7 +531,7 @@ async def health( @_rewrite_parameters() async def help(self) -> TextApiResponse: """ - Get CAT help. Returns help for the CAT APIs. + Get CAT help. Get help for the CAT APIs. ``_ """ @@ -577,7 +582,7 @@ async def indices( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get index information. Returns high-level information about indices in a cluster, + Get index information. Get high-level information about indices in a cluster, including backing indices for data streams. Use this request to get the following information for each index in a cluster: - shard count - document count - deleted document count - primary store size - total store size of all shards, including @@ -853,9 +858,9 @@ async def ml_data_frame_analytics( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get data frame analytics jobs. Returns configuration and usage information about - data frame analytics jobs. CAT APIs are only intended for human consumption using - the Kibana console or command line. They are not intended for use by applications. + Get data frame analytics jobs. Get configuration and usage information about + data frame analytics jobs. IMPORTANT: CAT APIs are only intended for human consumption + using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get data frame analytics jobs statistics API. @@ -1015,12 +1020,13 @@ async def ml_datafeeds( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get datafeeds. Returns configuration and usage information about datafeeds. This + Get datafeeds. Get configuration and usage information about datafeeds. This API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` - cluster privileges to use this API. CAT APIs are only intended for human consumption - using the Kibana console or command line. They are not intended for use by applications. - For application consumption, use the get datafeed statistics API. + cluster privileges to use this API. IMPORTANT: CAT APIs are only intended for + human consumption using the Kibana console or command line. They are not intended + for use by applications. For application consumption, use the get datafeed statistics + API. ``_ @@ -1376,13 +1382,13 @@ async def ml_jobs( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get anomaly detection jobs. Returns configuration and usage information for anomaly + Get anomaly detection jobs. Get configuration and usage information for anomaly detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, - or `manage` cluster privileges to use this API. CAT APIs are only intended for - human consumption using the Kibana console or command line. They are not intended - for use by applications. For application consumption, use the get anomaly detection - job statistics API. + or `manage` cluster privileges to use this API. IMPORTANT: CAT APIs are only + intended for human consumption using the Kibana console or command line. They + are not intended for use by applications. For application consumption, use the + get anomaly detection job statistics API. ``_ @@ -1560,10 +1566,10 @@ async def ml_trained_models( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get trained models. Returns configuration and usage information about inference - trained models. CAT APIs are only intended for human consumption using the Kibana - console or command line. They are not intended for use by applications. For application - consumption, use the get trained models statistics API. + Get trained models. Get configuration and usage information about inference trained + models. IMPORTANT: CAT APIs are only intended for human consumption using the + Kibana console or command line. They are not intended for use by applications. + For application consumption, use the get trained models statistics API. ``_ @@ -2325,7 +2331,7 @@ async def snapshots( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get snapshot information Get information about the snapshots stored in one or + Get snapshot information. Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. diff --git a/elasticsearch/_async/client/indices.py b/elasticsearch/_async/client/indices.py index 2c279c4ce..ed5f9ecf3 100644 --- a/elasticsearch/_async/client/indices.py +++ b/elasticsearch/_async/client/indices.py @@ -4943,89 +4943,6 @@ async def stats( path_parts=__path_parts, ) - @_rewrite_parameters() - async def unfreeze( - self, - *, - index: str, - allow_no_indices: t.Optional[bool] = 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, - human: t.Optional[bool] = None, - ignore_unavailable: 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, - wait_for_active_shards: t.Optional[str] = None, - ) -> ObjectApiResponse[t.Any]: - """ - Unfreeze an index. When a frozen index is unfrozen, the index goes through the - normal recovery process and becomes writeable again. - - ``_ - - :param index: Identifier for the index. - :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. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. - :param ignore_unavailable: If `false`, the request returns an error if it targets - a missing or closed index. - :param master_timeout: Period to wait for a connection to the master node. If - no response is received before the timeout expires, the request fails and - returns an error. - :param timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). - """ - if index in SKIP_IN_PATH: - raise ValueError("Empty value passed for parameter 'index'") - __path_parts: t.Dict[str, str] = {"index": _quote(index)} - __path = f'/{__path_parts["index"]}/_unfreeze' - __query: t.Dict[str, t.Any] = {} - if allow_no_indices is not None: - __query["allow_no_indices"] = allow_no_indices - 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 human is not None: - __query["human"] = human - if ignore_unavailable is not None: - __query["ignore_unavailable"] = ignore_unavailable - 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 - if wait_for_active_shards is not None: - __query["wait_for_active_shards"] = wait_for_active_shards - __headers = {"accept": "application/json"} - return await self.perform_request( # type: ignore[return-value] - "POST", - __path, - params=__query, - headers=__headers, - endpoint_id="indices.unfreeze", - path_parts=__path_parts, - ) - @_rewrite_parameters( body_fields=("actions",), ) diff --git a/elasticsearch/_async/client/security.py b/elasticsearch/_async/client/security.py index 7d4478abe..9d6b90093 100644 --- a/elasticsearch/_async/client/security.py +++ b/elasticsearch/_async/client/security.py @@ -481,7 +481,8 @@ async def clear_cached_privileges( ``_ - :param application: A comma-separated list of application names + :param application: A comma-separated list of applications. To clear all applications, + use an asterism (`*`). It does not support other wildcard patterns. """ if application in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'application'") @@ -519,12 +520,19 @@ async def clear_cached_realms( ) -> ObjectApiResponse[t.Any]: """ Clear the user cache. Evict users from the user cache. You can completely clear - the cache or evict specific users. + the cache or evict specific users. User credentials are cached in memory on each + node to avoid connecting to a remote authentication service or hitting the disk + for every incoming request. There are realm settings that you can use to configure + the user cache. For more information, refer to the documentation about controlling + the user cache. ``_ - :param realms: Comma-separated list of realms to clear - :param usernames: Comma-separated list of usernames to clear from the cache + :param realms: A comma-separated list of realms. To clear all realms, use an + asterisk (`*`). It does not support other wildcard patterns. + :param usernames: A comma-separated list of the users to clear from the cache. + If you do not specify this parameter, the API evicts all users from the user + cache. """ if realms in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'realms'") @@ -566,7 +574,9 @@ async def clear_cached_roles( ``_ - :param name: Role name + :param name: A comma-separated list of roles to evict from the role cache. To + evict all roles, use an asterisk (`*`). It does not support other wildcard + patterns. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -605,13 +615,20 @@ async def clear_cached_service_tokens( ) -> ObjectApiResponse[t.Any]: """ Clear service account token caches. Evict a subset of all entries from the service - account token caches. + account token caches. Two separate caches exist for service account tokens: one + cache for tokens backed by the `service_tokens` file, and another for tokens + backed by the `.security` index. This API clears matching entries from both caches. + The cache for service account tokens backed by the `.security` index is cleared + automatically on state changes of the security index. The cache for tokens backed + by the `service_tokens` file is cleared automatically on file changes. ``_ - :param namespace: An identifier for the namespace - :param service: An identifier for the service name - :param name: A comma-separated list of service token names + :param namespace: The namespace, which is a top-level grouping of service accounts. + :param service: The name of the service, which must be unique within its namespace. + :param name: A comma-separated list of token names to evict from the service + account token caches. Use a wildcard (`*`) to evict all tokens that belong + to a service account. It does not support other wildcard patterns. """ if namespace in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'namespace'") @@ -665,30 +682,40 @@ async def create_api_key( ) -> ObjectApiResponse[t.Any]: """ Create an API key. Create an API key for access without requiring basic authentication. - A successful request returns a JSON structure that contains the API key, its - unique id, and its name. If applicable, it also returns expiration information - for the API key in milliseconds. NOTE: By default, API keys never expire. You - can specify expiration information when you create the API keys. + IMPORTANT: If the credential that is used to authenticate this request is an + API key, the derived API key cannot have any privileges. If you specify privileges, + the API returns an error. A successful request returns a JSON structure that + contains the API key, its unique id, and its name. If applicable, it also returns + expiration information for the API key in milliseconds. NOTE: By default, API + keys never expire. You can specify expiration information when you create the + API keys. The API keys are created by the Elasticsearch API key service, which + is automatically enabled. To configure or turn off the API key service, refer + to API key service setting documentation. ``_ - :param expiration: Expiration time for the API key. By default, API keys never - expire. + :param expiration: The expiration time for the API key. By default, API keys + never expire. :param metadata: Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with `_` are reserved for system usage. - :param name: Specifies the name for this API key. + :param name: A name for the API key. :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. - :param role_descriptors: An array of role descriptors for this API key. This - parameter is optional. When it is not specified or is an empty array, then - the API key will have a point in time snapshot of permissions of the authenticated - user. If you supply role descriptors then the resultant permissions would - be an intersection of API keys permissions and authenticated user’s permissions - thereby limiting the access scope for API keys. The structure of role descriptor - is the same as the request for create role API. For more details, see create - or update roles API. + :param role_descriptors: An array of role descriptors for this API key. When + it is not specified or it is an empty array, the API key will have a point + in time snapshot of permissions of the authenticated user. If you supply + role descriptors, the resultant permissions are an intersection of API keys + permissions and the authenticated user's permissions thereby limiting the + access scope for API keys. The structure of role descriptor is the same as + the request for the create role API. For more details, refer to the create + or update roles API. NOTE: Due to the way in which this permission intersection + is calculated, it is not possible to create an API key that is a child of + another API key, unless the derived key is created without any privileges. + In this case, you must explicitly specify a role descriptor with no privileges. + The derived API key can be used for authentication; it will not have authority + to call Elasticsearch APIs. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/api_key" @@ -825,13 +852,21 @@ async def create_service_token( ) -> ObjectApiResponse[t.Any]: """ Create a service account token. Create a service accounts token for access without - requiring basic authentication. + requiring basic authentication. NOTE: Service account tokens never expire. You + must actively delete them if they are no longer needed. ``_ - :param namespace: An identifier for the namespace - :param service: An identifier for the service name - :param name: An identifier for the token name + :param namespace: The name of the namespace, which is a top-level grouping of + service accounts. + :param service: The name of the service. + :param name: The name for the service account token. If omitted, a random name + will be generated. Token names must be at least one and no more than 256 + characters. They can contain alphanumeric characters (a-z, A-Z, 0-9), dashes + (`-`), and underscores (`_`), but cannot begin with an underscore. NOTE: + 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 make this operation visible to search, if `false` then do nothing with refreshes. @@ -963,12 +998,16 @@ async def delete_privileges( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete application privileges. + Delete application privileges. To use this API, you must have one of the following + privileges: * The `manage_security` cluster privilege (or a greater privilege + such as `all`). * The "Manage Application Privileges" global privilege for the + application being referenced in the request. ``_ - :param application: Application name - :param name: Privilege name + :param application: The name of the application. Application privileges are always + associated with exactly one application. + :param name: The name of the privilege. :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. @@ -1019,11 +1058,14 @@ async def delete_role( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete roles. Delete roles in the native realm. + Delete roles. Delete roles in the native realm. The role management APIs are + generally the preferred way to manage roles, rather than using file-based role + management. The delete roles API cannot remove roles that are defined in roles + files. ``_ - :param name: Role name + :param name: The name of the role. :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. @@ -1067,11 +1109,16 @@ async def delete_role_mapping( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete role mappings. + Delete role mappings. Role mappings define which roles are assigned to each user. + The role mapping APIs are generally the preferred way to manage role mappings + rather than using role mapping files. The delete role mappings API cannot remove + role mappings that are defined in role mapping files. ``_ - :param name: Role-mapping name + :param name: The distinct name that identifies the role mapping. The name is + used solely as an identifier to facilitate interaction via the API; it does + not affect the behavior of the mapping in any way. :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. @@ -1122,9 +1169,9 @@ async def delete_service_token( ``_ - :param namespace: An identifier for the namespace - :param service: An identifier for the service name - :param name: An identifier for the token name + :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 make this operation visible to search, if `false` then do nothing with refreshes. @@ -1180,7 +1227,7 @@ async def delete_user( ``_ - :param username: username + :param username: An identifier for the user. :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. @@ -1224,11 +1271,12 @@ async def disable_user( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Disable users. Disable users in the native realm. + Disable users. Disable users in the native realm. By default, when you create + users, they are enabled. You can use this API to revoke a user's access to Elasticsearch. ``_ - :param username: The username of the user to disable + :param username: An identifier for the user. :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. @@ -1328,11 +1376,12 @@ async def enable_user( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Enable users. Enable users in the native realm. + Enable users. Enable users in the native realm. By default, when you create users, + they are enabled. ``_ - :param username: The username of the user to enable + :param username: An identifier for the user. :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. @@ -1428,7 +1477,10 @@ async def enroll_kibana( ) -> ObjectApiResponse[t.Any]: """ Enroll Kibana. Enable a Kibana instance to configure itself for communication - with a secured Elasticsearch cluster. + with a secured Elasticsearch cluster. NOTE: This API is currently intended for + internal use only by Kibana. Kibana uses this API internally to configure itself + for communications with an Elasticsearch cluster that already has security features + enabled. ``_ """ @@ -1464,7 +1516,11 @@ async def enroll_node( ) -> ObjectApiResponse[t.Any]: """ Enroll a node. Enroll a new node to allow it to join an existing cluster with - security features enabled. + security features enabled. The response contains all the necessary information + for the joining node to bootstrap discovery and security related settings so + that it can successfully join the cluster. The response contains key and certificate + material that allows the caller to generate valid signed certificates for the + HTTP layer of all nodes in the cluster. ``_ """ @@ -1623,12 +1679,18 @@ async def get_privileges( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get application privileges. + Get application privileges. To use this API, you must have one of the following + privileges: * The `read_security` cluster privilege (or a greater privilege such + as `manage_security` or `all`). * The "Manage Application Privileges" global + privilege for the application being referenced in the request. ``_ - :param application: Application name - :param name: Privilege name + :param application: The name of the application. Application privileges are always + associated with exactly one application. If you do not specify this parameter, + the API returns information about all privileges for all applications. + :param name: The name of the privilege. If you do not specify this parameter, + the API returns information about all privileges for the requested application. """ __path_parts: t.Dict[str, str] if application not in SKIP_IN_PATH and name not in SKIP_IN_PATH: @@ -1670,7 +1732,9 @@ async def get_role( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get roles. Get roles in the native realm. + Get roles. Get roles in the native realm. The role management APIs are generally + the preferred way to manage roles, rather than using file-based role management. + The get roles API cannot retrieve roles that are defined in roles files. ``_ @@ -1767,14 +1831,15 @@ async def get_service_accounts( ) -> ObjectApiResponse[t.Any]: """ Get service accounts. Get a list of service accounts that match the provided - path parameters. + path parameters. NOTE: Currently, only the `elastic/fleet-server` service account + is available. ``_ - :param namespace: Name of the namespace. Omit this parameter to retrieve information - about all service accounts. If you omit this parameter, you must also omit - the `service` parameter. - :param service: Name of the service name. Omit this parameter to retrieve information + :param namespace: The name of the namespace. Omit this parameter to retrieve + information about all service accounts. If you omit this parameter, you must + also omit the `service` parameter. + :param service: The service name. Omit this parameter to retrieve information about all service accounts that belong to the specified `namespace`. """ __path_parts: t.Dict[str, str] @@ -1818,12 +1883,19 @@ async def get_service_credentials( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get service account credentials. + Get service account credentials. To use this API, you must have at least the + `read_security` cluster privilege (or a greater privilege such as `manage_service_account` + or `manage_security`). The response includes service account tokens that were + created with the create service account tokens API as well as file-backed tokens + from all nodes of the cluster. NOTE: For tokens backed by the `service_tokens` + file, the API collects them from all nodes of the cluster. Tokens with the same + name from different nodes are assumed to be the same token and are only counted + once towards the total number of service tokens. ``_ - :param namespace: Name of the namespace. - :param service: Name of the service name. + :param namespace: The name of the namespace. + :param service: The service name. """ if namespace in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'namespace'") @@ -1865,7 +1937,9 @@ async def get_settings( ) -> ObjectApiResponse[t.Any]: """ Get security index settings. Get the user-configurable settings for the security - internal index (`.security` and associated indices). + internal index (`.security` and associated indices). Only a subset of the index + settings — those that are user-configurable—will be shown. This includes: * `index.auto_expand_replicas` + * `index.number_of_replicas` ``_ @@ -1930,15 +2004,39 @@ async def get_token( ) -> ObjectApiResponse[t.Any]: """ Get a token. Create a bearer token for access without requiring basic authentication. + The tokens are created by the Elasticsearch Token Service, which is automatically + enabled when you configure TLS on the HTTP interface. Alternatively, you can + explicitly enable the `xpack.security.authc.token.enabled` setting. When you + are running in production mode, a bootstrap check prevents you from enabling + the token service unless you also enable TLS on the HTTP interface. The get token + API takes the same parameters as a typical OAuth 2.0 token API except for the + use of a JSON request body. A successful get token API call returns a JSON structure + that contains the access token, the amount of time (seconds) that the token expires + in, the type, and the scope if available. The tokens returned by the get token + API have a finite period of time for which they are valid and after that time + period, they can no longer be used. That time period is defined by the `xpack.security.authc.token.timeout` + setting. If you want to invalidate a token immediately, you can do so by using + the invalidate token API. ``_ - :param grant_type: - :param kerberos_ticket: - :param password: - :param refresh_token: - :param scope: - :param username: + :param grant_type: The type of grant. Supported grant types are: `password`, + `_kerberos`, `client_credentials`, and `refresh_token`. + :param kerberos_ticket: The base64 encoded kerberos ticket. If you specify the + `_kerberos` grant type, this parameter is required. This parameter is not + valid with any other supported grant type. + :param password: The user's password. If you specify the `password` grant type, + this parameter is required. This parameter is not valid with any other supported + grant type. + :param refresh_token: The string that was returned when you created the token, + which enables you to extend its life. If you specify the `refresh_token` + grant type, this parameter is required. This parameter is not valid with + any other supported grant type. + :param scope: The scope of the token. Currently tokens are only issued for a + scope of FULL regardless of the value sent with the request. + :param username: The username that identifies the user. If you specify the `password` + grant type, this parameter is required. This parameter is not valid with + any other supported grant type. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/oauth2/token" @@ -1995,8 +2093,8 @@ async def get_user( :param username: An identifier for the user. You can specify multiple usernames as a comma-separated list. If you omit this parameter, the API retrieves information about all users. - :param with_profile_uid: If true will return the User Profile ID for a user, - if any. + :param with_profile_uid: Determines whether to retrieve the user profile UID, + if it exists, for the users. """ __path_parts: t.Dict[str, str] if username not in SKIP_IN_PATH: @@ -2039,7 +2137,10 @@ async def get_user_privileges( username: t.Optional[t.Union[None, str]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get user privileges. + Get user privileges. Get the security privileges for the logged in user. All + users can use this API, but only to determine their own privileges. To check + the privileges of other users, you must use the run as feature. To check whether + a user has a specific list of privileges, use the has privileges API. ``_ @@ -2160,28 +2261,30 @@ async def grant_api_key( Grant an API key. Create an API key on behalf of another user. This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. The caller must have authentication - credentials (either an access token, or a username and password) for the user - on whose behalf the API key will be created. It is not possible to use this API - to create an API key without that user’s credentials. The user, for whom the - authentication credentials is provided, can optionally "run as" (impersonate) - another user. In this case, the API key will be created on behalf of the impersonated - user. This API is intended be used by applications that need to create and manage - API keys for end users, but cannot guarantee that those users have permission - to create API keys on their own behalf. A successful grant API key API call returns - a JSON structure that contains the API key, its unique id, and its name. If applicable, + credentials for the user on whose behalf the API key will be created. It is not + possible to use this API to create an API key without that user's credentials. + The supported user authentication credential types are: * username and password + * Elasticsearch access tokens * JWTs The user, for whom the authentication credentials + is provided, can optionally "run as" (impersonate) another user. In this case, + the API key will be created on behalf of the impersonated user. This API is intended + be used by applications that need to create and manage API keys for end users, + but cannot guarantee that those users have permission to create API keys on their + own behalf. The API keys are created by the Elasticsearch API key service, which + is automatically enabled. A successful grant API key API call returns a JSON + structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. By default, API keys never expire. You can specify expiration information when you create the API keys. ``_ - :param api_key: Defines the API key. + :param api_key: The API key. :param grant_type: The type of grant. Supported grant types are: `access_token`, `password`. - :param access_token: The user’s access token. If you specify the `access_token` + :param access_token: The user's access token. If you specify the `access_token` grant type, this parameter is required. It is not valid with other grant types. - :param password: The user’s password. If you specify the `password` grant type, + :param password: The user's password. If you specify the `password` grant type, this parameter is required. It is not valid with other grant types. :param run_as: The name of the user to be impersonated. :param username: The user name that identifies the user. If you specify the `password` @@ -2313,7 +2416,8 @@ async def has_privileges( ) -> ObjectApiResponse[t.Any]: """ Check user privileges. Determine whether the specified user has a specified list - of privileges. + of privileges. All users can use this API, but only to determine their own privileges. + To check the privileges of other users, you must use the run as feature. ``_ @@ -2440,13 +2544,16 @@ async def invalidate_api_key( key or grant API key APIs. Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically - deleted. The `manage_api_key` privilege allows deleting any API keys. The `manage_own_api_key` - only allows deleting API keys that are owned by the user. In addition, with the - `manage_own_api_key` privilege, an invalidation request must be issued in one - of the three formats: - Set the parameter `owner=true`. - Or, set both `username` - and `realm_name` to match the user’s identity. - Or, if the request is issued - by an API key, that is to say an API key invalidates itself, specify its ID in - the `ids` field. + deleted. To use this API, you must have at least the `manage_security`, `manage_api_key`, + or `manage_own_api_key` cluster privileges. The `manage_security` privilege allows + deleting any API key, including both REST and cross cluster API keys. The `manage_api_key` + privilege allows deleting any REST API key, but not cross cluster API keys. The + `manage_own_api_key` only allows deleting REST API keys that are owned by the + user. In addition, with the `manage_own_api_key` privilege, an invalidation request + must be issued in one of the three formats: - Set the parameter `owner=true`. + - Or, set both `username` and `realm_name` to match the user's identity. - Or, + if the request is issued by an API key, that is to say an API key invalidates + itself, specify its ID in the `ids` field. ``_ @@ -2455,14 +2562,15 @@ async def invalidate_api_key( `name`, `realm_name`, or `username`. :param name: An API key name. This parameter cannot be used with any of `ids`, `realm_name` or `username`. - :param owner: Can be used to query API keys owned by the currently authenticated - user. The `realm_name` or `username` parameters cannot be specified when - this parameter is set to `true` as they are assumed to be the currently authenticated - ones. + :param owner: Query API keys owned by the currently authenticated user. The `realm_name` + or `username` parameters cannot be specified when this parameter is set to + `true` as they are assumed to be the currently authenticated ones. NOTE: + At least one of `ids`, `name`, `username`, and `realm_name` must be specified + if `owner` is `false`. :param realm_name: The name of an authentication realm. This parameter cannot be used with either `ids` or `name`, or when `owner` flag is set to `true`. :param username: The username of a user. This parameter cannot be used with either - `ids` or `name`, or when `owner` flag is set to `true`. + `ids` or `name` or when `owner` flag is set to `true`. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/api_key" @@ -2522,14 +2630,21 @@ async def invalidate_token( longer be used. The time period is defined by the `xpack.security.authc.token.timeout` setting. The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once. If you want to invalidate one or - more access or refresh tokens immediately, use this invalidate token API. + more access or refresh tokens immediately, use this invalidate token API. NOTE: + While all parameters are optional, at least one of them is required. More specifically, + either one of `token` or `refresh_token` parameters is required. If none of these + two are specified, then `realm_name` and/or `username` need to be specified. ``_ - :param realm_name: - :param refresh_token: - :param token: - :param username: + :param realm_name: The name of an authentication realm. This parameter cannot + be used with either `refresh_token` or `token`. + :param refresh_token: A refresh token. This parameter cannot be used if any of + `refresh_token`, `realm_name`, or `username` are used. + :param token: An access token. This parameter cannot be used if any of `refresh_token`, + `realm_name`, or `username` are used. + :param username: The username of a user. This parameter cannot be used with either + `refresh_token` or `token`. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/oauth2/token" @@ -2806,7 +2921,20 @@ async def put_privileges( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update application privileges. + Create or update application privileges. To use this API, you must have one of + the following privileges: * The `manage_security` cluster privilege (or a greater + privilege such as `all`). * The "Manage Application Privileges" global privilege + for the application being referenced in the request. Application names are formed + from a prefix, with an optional suffix that conform to the following rules: * + The prefix must begin with a lowercase ASCII letter. * The prefix must contain + only ASCII letters or digits. * The prefix must be at least 3 characters long. + * If the suffix exists, it must begin with either a dash `-` or `_`. * The suffix + cannot contain any of the following characters: `\\`, `/`, `*`, `?`, `"`, `<`, + `>`, `|`, `,`, `*`. * No part of the name can contain whitespace. Privilege names + must begin with a lowercase ASCII letter and must contain only ASCII letters + and digits along with the characters `_`, `-`, and `.`. Action names can contain + any number of printable ASCII characters and must contain at least one of the + following characters: `/`, `*`, `:`. ``_ @@ -2977,7 +3105,10 @@ async def put_role( 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. :param remote_cluster: A list of remote cluster permissions entries. - :param remote_indices: A list of remote indices permissions entries. + :param remote_indices: A list of remote indices permissions entries. NOTE: Remote + indices are effective for remote clusters configured with the API key based + model. They have no effect for remote clusters configured with the certificate + based model. :param run_as: A list of users that the owners of this role can impersonate. *Note*: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will @@ -3072,21 +3203,45 @@ async def put_role_mapping( that are granted to those users. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role - mapping files. This API does not create roles. Rather, it maps users to existing - roles. Roles can be created by using the create or update roles API or roles - files. + mapping files. NOTE: This API does not create roles. Rather, it maps users to + existing roles. Roles can be created by using the create or update roles API + or roles files. **Role templates** The most common use for role mappings is to + create a mapping from a known value on the user to a fixed role name. For example, + all users in the `cn=admin,dc=example,dc=com` LDAP group should be given the + superuser role in Elasticsearch. The `roles` field is used for this purpose. + For more complex needs, it is possible to use Mustache templates to dynamically + determine the names of the roles that should be granted to the user. The `role_templates` + field is used for this purpose. NOTE: To use role templates successfully, the + relevant scripting feature must be enabled. Otherwise, all attempts to create + a role mapping with role templates fail. All of the user fields that are available + in the role mapping rules are also available in the role templates. Thus it is + possible to assign a user to a role that reflects their username, their groups, + or the name of the realm to which they authenticated. By default a template is + evaluated to produce a single string that is the name of the role which should + be assigned to the user. If the format of the template is set to "json" then + the template is expected to produce a JSON string or an array of JSON strings + for the role names. ``_ - :param name: Role-mapping name - :param enabled: - :param metadata: + :param name: The distinct name that identifies the role mapping. The name is + used solely as an identifier to facilitate interaction via the API; it does + not affect the behavior of the mapping in any way. + :param enabled: Mappings that have `enabled` set to `false` are ignored when + role mapping is performed. + :param metadata: Additional metadata that helps define which roles are assigned + to each user. Within the metadata object, keys beginning with `_` are reserved + for system usage. :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. - :param role_templates: - :param roles: - :param rules: + :param role_templates: A list of Mustache templates that will be evaluated to + determine the roles names that should granted to the users that match the + role mapping rules. Exactly one of `roles` or `role_templates` must be specified. + :param roles: A list of role names that are granted to the users that match the + role mapping rules. Exactly one of `roles` or `role_templates` must be specified. + :param rules: The rules that determine which users should be matched by the mapping. + A rule is a logical condition that is expressed by using a JSON DSL. :param run_as: """ if name in SKIP_IN_PATH: @@ -3161,23 +3316,38 @@ async def put_user( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update users. A password is required for adding a new user but is optional - when updating an existing user. To change a user’s password without updating - any other fields, use the change password API. + Create or update users. Add and update users in the native realm. A password + is required for adding a new user but is optional when updating an existing user. + To change a user's password without updating any other fields, use the change + password API. ``_ - :param username: The username of the User - :param email: - :param enabled: - :param full_name: - :param metadata: - :param password: - :param password_hash: - :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. - :param roles: + :param username: An identifier for the user. NOTE: Usernames must be at least + 1 and no more than 507 characters. They can contain alphanumeric characters + (a-z, A-Z, 0-9), spaces, punctuation, and printable symbols in the Basic + Latin (ASCII) block. Leading or trailing whitespace is not allowed. + :param email: The email of the user. + :param enabled: Specifies whether the user is enabled. + :param full_name: The full name of the user. + :param metadata: Arbitrary metadata that you want to associate with the user. + :param password: The user's password. Passwords must be at least 6 characters + long. When adding a user, one of `password` or `password_hash` is required. + When updating an existing user, the password is optional, so that other fields + on the user (such as their roles) may be updated without modifying the user's + password + :param password_hash: A hash of the user's password. This must be produced using + the same hashing algorithm as has been configured for password storage. For + more details, see the explanation of the `xpack.security.authc.password_hashing.algorithm` + setting in the user cache and password hash algorithm documentation. Using + this parameter allows the client to pre-hash the password for performance + and/or confidentiality reasons. The `password` parameter and the `password_hash` + parameter cannot be used in the same request. + :param refresh: Valid values are `true`, `false`, and `wait_for`. These values + have the same meaning as in the index API, but the default value for this + API is true. + :param roles: A set of roles the user has. The roles determine the user's access + permissions. To create a user without any roles, specify an empty list (`[]`). """ if username in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'username'") @@ -3261,7 +3431,12 @@ async def query_api_keys( ) -> ObjectApiResponse[t.Any]: """ Find API keys with a query. Get a paginated list of API keys and their information. - You can optionally filter the results with a query. + You can optionally filter the results with a query. To use this API, you must + have at least the `manage_own_api_key` or the `read_security` cluster privileges. + If you have only the `manage_own_api_key` privilege, this API returns only the + API keys that you own. If you have the `read_security`, `manage_api_key`, or + greater privileges (including `manage_security`), this API returns all API keys + regardless of ownership. ``_ @@ -3277,30 +3452,39 @@ async def query_api_keys( `terms`, `range`, `date_range`, `missing`, `cardinality`, `value_count`, `composite`, `filter`, and `filters`. Additionally, aggregations only run over the same subset of fields that query works with. - :param from_: Starting document offset. 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 from_: The starting document offset. 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 query: A query to filter which API keys to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following public information associated with an API key: `id`, `type`, `name`, `creation`, `expiration`, `invalidated`, `invalidation`, - `username`, `realm`, and `metadata`. - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: Other than `id`, all public fields of an API key are eligible for - sorting. In addition, sort can also be applied to the `_doc` field to sort - by index order. + `username`, `realm`, and `metadata`. NOTE: The queryable string values associated + with API keys are internally mapped as keywords. Consequently, if no `analyzer` + parameter is specified for a `match` query, then the provided match query + string is interpreted as a single keyword value. Such a match query is hence + equivalent to a `term` query. + :param search_after: The search after definition. + :param size: The number of hits to return. It must not be negative. The `size` + parameter can be set to `0`, in which case no API key matches are returned, + only the aggregation results. 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. Other than `id`, all public fields of an API + key are eligible for sorting. In addition, sort can also be applied to the + `_doc` field to sort by index order. :param typed_keys: Determines whether aggregation names are prefixed by their respective types in the response. :param with_limited_by: Return the snapshot of the owner user's role descriptors associated with the API key. An API key's actual permission is the intersection - of its assigned role descriptors and the owner user's role descriptors. - :param with_profile_uid: Determines whether to also retrieve the profile uid, - for the API key owner principal, if it exists. + of its assigned role descriptors and the owner user's role descriptors (effectively + limited by it). An API key cannot retrieve any API key’s limited-by role + descriptors (including itself) unless it has `manage_api_key` or higher privileges. + :param with_profile_uid: Determines whether to also retrieve the profile UID + for the API key owner principal. If it exists, the profile UID is returned + under the `profile_uid` response field for each API key. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/api_key" @@ -3387,26 +3571,30 @@ async def query_role( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Find roles with a query. Get roles in a paginated manner. You can optionally - filter the results with a query. + Find roles with a query. Get roles in a paginated manner. The role management + APIs are generally the preferred way to manage roles, rather than using file-based + role management. The query roles API does not retrieve roles that are defined + in roles files, nor built-in ones. You can optionally filter the results with + a query. Also, the results can be paginated and sorted. ``_ - :param from_: Starting document offset. 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 from_: The starting document offset. 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 query: A query to filter which roles to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following information associated with roles: `name`, `description`, - `metadata`, `applications.application`, `applications.privileges`, `applications.resources`. - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: All public fields of a role are eligible for sorting. In addition, - sort can also be applied to the `_doc` field to sort by index order. + `metadata`, `applications.application`, `applications.privileges`, and `applications.resources`. + :param search_after: The search after definition. + :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`. + In addition, sort can also be applied to the `_doc` field to sort by index + order. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/role" @@ -3474,27 +3662,30 @@ async def query_user( ) -> ObjectApiResponse[t.Any]: """ Find users with a query. Get information for users in a paginated manner. You - can optionally filter the results with a query. + can optionally filter the results with a query. NOTE: As opposed to the get user + API, built-in users are excluded from the result. This API is only for native + users. ``_ - :param from_: Starting document offset. 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 from_: The starting document offset. 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 query: A query to filter which users to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following information associated with user: `username`, - `roles`, `enabled` - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: Fields eligible for sorting are: username, roles, enabled In addition, - sort can also be applied to the `_doc` field to sort by index order. - :param with_profile_uid: If true will return the User Profile ID for the users - in the query result, if any. + `roles`, `enabled`, `full_name`, and `email`. + :param search_after: The search after definition + :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. Fields eligible for sorting are: `username`, + `roles`, `enabled`. In addition, sort can also be applied to the `_doc` field + to sort by index order. + :param with_profile_uid: Determines whether to retrieve the user profile UID, + if it exists, for the users. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/user" @@ -4034,38 +4225,44 @@ async def update_api_key( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update an API key. Updates attributes of an existing API key. Users can only - update API keys that they created or that were granted to them. Use this API - to update API keys created by the create API Key or grant API Key APIs. If you - need to apply the same update to many API keys, you can use bulk update API Keys - to reduce overhead. It’s not possible to update expired API keys, or API keys - that have been invalidated by invalidate API Key. This API supports updates to - an API key’s access scope and metadata. The access scope of an API key is derived - from the `role_descriptors` you specify in the request, and a snapshot of the - owner user’s permissions at the time of the request. The snapshot of the owner’s - permissions is updated automatically on every call. If you don’t specify `role_descriptors` - in the request, a call to this API might still change the API key’s access scope. - This change can occur if the owner user’s permissions have changed since the - API key was created or last modified. To update another user’s API key, use the - `run_as` feature to submit a request on behalf of another user. IMPORTANT: It’s - not possible to use an API key as the authentication credential for this API. - To update an API key, the owner user’s credentials are required. + Update an API key. Update attributes of an existing API key. This API supports + updates to an API key's access scope, expiration, and metadata. To use this API, + you must have at least the `manage_own_api_key` cluster privilege. Users can + only update API keys that they created or that were granted to them. To update + another user’s API key, use the `run_as` feature to submit a request on behalf + of another user. IMPORTANT: It's not possible to use an API key as the authentication + credential for this API. The owner user’s credentials are required. Use this + API to update API keys created by the create API key or grant API Key APIs. If + you need to apply the same update to many API keys, you can use the bulk update + API keys API to reduce overhead. It's not possible to update expired API keys + or API keys that have been invalidated by the invalidate API key API. The access + scope of an API key is derived from the `role_descriptors` you specify in the + request and a snapshot of the owner user's permissions at the time of the request. + The snapshot of the owner's permissions is updated automatically on every call. + IMPORTANT: If you don't specify `role_descriptors` in the request, a call to + this API might still change the API key's access scope. This change can occur + if the owner user's permissions have changed since the API key was created or + last modified. ``_ :param id: The ID of the API key to update. - :param expiration: Expiration time for the API key. + :param expiration: The expiration time for the API key. By default, API keys + never expire. This property can be omitted to leave the expiration unchanged. :param metadata: Arbitrary metadata that you want to associate with the API key. - It supports nested data structure. Within the metadata object, keys beginning - with _ are reserved for system usage. - :param role_descriptors: An array of role descriptors for this API key. This - parameter is optional. When it is not specified or is an empty array, then - the API key will have a point in time snapshot of permissions of the authenticated - user. If you supply role descriptors then the resultant permissions would - be an intersection of API keys permissions and authenticated user’s permissions - thereby limiting the access scope for API keys. The structure of role descriptor - is the same as the request for create role API. For more details, see create - or update roles API. + It supports a nested data structure. Within the metadata object, keys beginning + with `_` are reserved for system usage. When specified, this value fully + replaces the metadata previously associated with the API key. + :param role_descriptors: The role descriptors to assign to this API key. The + API key's effective permissions are an intersection of its assigned privileges + and the point in time snapshot of permissions of the owner user. You can + assign new privileges by specifying them in this parameter. To remove assigned + privileges, you can supply an empty `role_descriptors` parameter, that is + to say, an empty object `{}`. If an API key has no assigned privileges, it + inherits the owner user's full permissions. The snapshot of the owner's permissions + is always updated, whether you supply the `role_descriptors` parameter or + not. The structure of a role descriptor is the same as the request for the + create API keys API. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -4206,10 +4403,12 @@ async def update_settings( """ Update security index settings. Update the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of - settings are allowed to be modified, for example `index.auto_expand_replicas` - and `index.number_of_replicas`. If a specific index is not in use on the system - and settings are provided for it, the request will be rejected. This API does - not yet support configuring the settings for indices before they are in use. + settings are allowed to be modified. This includes `index.auto_expand_replicas` + and `index.number_of_replicas`. NOTE: If `index.auto_expand_replicas` is set, + `index.number_of_replicas` will be ignored during updates. If a specific index + is not in use on the system and settings are provided for it, the request will + be rejected. This API does not yet support configuring the settings for indices + before they are in use. ``_ diff --git a/elasticsearch/_sync/client/__init__.py b/elasticsearch/_sync/client/__init__.py index 1273d3fcc..52e971fba 100644 --- a/elasticsearch/_sync/client/__init__.py +++ b/elasticsearch/_sync/client/__init__.py @@ -1115,38 +1115,119 @@ def create( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Index a document. Adds a JSON document to the specified data stream or index - and makes it searchable. If the target is an index and the document already exists, - the request updates the document and increments its version. + Create a new document in the index. You can index a new JSON document with the + `//_doc/` or `//_create/<_id>` APIs Using `_create` guarantees + that the document is indexed only if it does not already exist. It returns a + 409 response when a document with a same ID already exists in the index. To update + an existing document, you must use the `//_doc/` API. If the Elasticsearch + security features are enabled, you must have the following index privileges for + the target data stream, index, or index alias: * To add a document using the + `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, + you must have the `create_doc`, `create`, `index`, or `write` index privilege. + * To automatically create a data stream or index with this API request, you must + have the `auto_configure`, `create_index`, or `manage` index privilege. Automatic + data stream creation requires a matching index template with data stream enabled. + **Automatically create data streams and indices** If the request's target doesn't + exist and matches an index template with a `data_stream` definition, the index + operation automatically creates the data stream. If the target doesn't exist + and doesn't match a data stream template, the operation automatically creates + the index and applies any matching index templates. NOTE: Elasticsearch includes + several built-in index templates. To avoid naming collisions with these templates, + refer to index pattern documentation. If no mapping exists, the index operation + creates a dynamic mapping. By default, new fields and objects are automatically + added to the mapping if needed. Automatic index creation is controlled by the + `action.auto_create_index` setting. If it is `true`, any index can be created + automatically. You can modify this setting to explicitly allow or block automatic + creation of indices that match specified patterns or set it to `false` to turn + off automatic index creation entirely. Specify a comma-separated list of patterns + you want to allow or prefix each pattern with `+` or `-` to indicate whether + it should be allowed or blocked. When a list is specified, the default behaviour + is to disallow. NOTE: The `action.auto_create_index` setting affects the automatic + creation of indices only. It does not affect the creation of data streams. **Routing** + By default, shard placement — or routing — is controlled by using a hash of the + document's ID value. For more explicit control, the value fed into the hash function + used by the router can be directly specified on a per-operation basis using the + `routing` parameter. When setting up explicit mapping, you can also use the `_routing` + field to direct the index operation to extract the routing value from the document + itself. This does come at the (very minimal) cost of an additional document parsing + pass. If the `_routing` mapping is defined and set to be required, the index + operation will fail if no routing value is provided or extracted. NOTE: Data + streams do not support custom routing unless they were created with the `allow_custom_routing` + setting enabled in the template. **Distributed** The index operation is directed + to the primary shard based on its route and performed on the actual node containing + this shard. After the primary shard completes the operation, if needed, the update + is distributed to applicable replicas. **Active shards** To improve the resiliency + of writes to the system, indexing operations can be configured to wait for a + certain number of active shard copies before proceeding with the operation. If + the requisite number of active shard copies are not available, then the write + operation must wait and retry, until either the requisite shard copies have started + or a timeout occurs. By default, write operations only wait for the primary shards + to be active before proceeding (that is to say `wait_for_active_shards` is `1`). + This default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. + To alter this behavior per operation, use the `wait_for_active_shards request` + parameter. Valid values are all or any positive integer up to the total number + of configured copies per shard in the index (which is `number_of_replicas`+1). + Specifying a negative value or a number greater than the number of shard copies + will throw an error. For example, suppose you have a cluster of three nodes, + A, B, and C and you create an index index with the number of replicas set to + 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt + an indexing operation, by default the operation will only ensure the primary + copy of each shard is available before proceeding. This means that even if B + and C went down and A hosted the primary shard copies, the indexing operation + would still proceed with only one copy of the data. If `wait_for_active_shards` + is set on the request to `3` (and all three nodes are up), the indexing operation + will require 3 active shard copies before proceeding. This requirement should + be met because there are 3 active nodes in the cluster, each one holding a copy + of the shard. However, if you set `wait_for_active_shards` to `all` (or to `4`, + which is the same in this situation), the indexing operation will not proceed + as you do not have all 4 copies of each shard active in the index. The operation + will timeout unless a new node is brought up in the cluster to host the fourth + copy of the shard. It is important to note that this setting greatly reduces + the chances of the write operation not writing to the requisite number of shard + copies, but it does not completely eliminate the possibility, because this check + occurs before the write operation starts. After the write operation is underway, + it is still possible for replication to fail on any number of shard copies but + still succeed on the primary. The `_shards` section of the API response reveals + the number of shard copies on which replication succeeded and failed. ``_ - :param index: Name of the data stream or index to target. If the target doesn’t + :param index: The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. If - the target doesn’t exist and doesn’t match a data stream template, this request + the target doesn't exist and doesn’t match a data stream template, this request creates the index. - :param id: Unique identifier for the document. + :param id: A unique identifier for the document. To automatically generate a + document ID, use the `POST //_doc/` request format. :param document: - :param pipeline: ID of the pipeline to use to preprocess incoming documents. - If the index has a default ingest pipeline specified, then setting the value - to `_none` disables the default ingest pipeline for this request. If a final - pipeline is configured it will always run, regardless of the value of this + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. + If the index has a default ingest pipeline specified, setting the value to + `_none` turns off the default ingest pipeline for this request. If a final + pipeline is configured, it will always run regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period the request waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. + :param routing: A custom value that is used to route operations to a specific + shard. + :param timeout: The period the request waits for the following operations: automatic + index creation, dynamic mapping updates, waiting for active shards. Elasticsearch + waits for at least the specified timeout period before failing. The actual + wait time could be longer, particularly when multiple waits occur. This parameter + is useful for situations where the primary shard assigned to perform the + operation might not be available when the operation runs. Some reasons for + this might be that the primary shard is currently recovering from a gateway + or undergoing relocation. By default, the operation will wait on the primary + shard to become available for at least 1 minute before failing and responding + with an error. The actual wait time could be longer, particularly when multiple + waits occur. + :param version: The explicit version number for concurrency control. It must + be a non-negative long number. + :param version_type: The version type. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. You can set it to `all` or any positive + integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1221,29 +1302,57 @@ def delete( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a document. Removes a JSON document from the specified index. + Delete a document. Remove a JSON document from the specified index. NOTE: You + cannot send deletion requests directly to a data stream. To delete a document + in a data stream, you must target the backing index containing the document. + **Optimistic concurrency control** Delete operations can be made conditional + and only be performed if the last modification to the document was assigned the + sequence number and primary term specified by the `if_seq_no` and `if_primary_term` + parameters. If a mismatch is detected, the operation will result in a `VersionConflictException` + and a status code of `409`. **Versioning** Each document indexed is versioned. + When deleting a document, the version can be specified to make sure the relevant + document you are trying to delete is actually being deleted and it has not changed + in the meantime. Every write operation run on a document, deletes included, causes + its version to be incremented. The version number of a deleted document remains + available for a short time after deletion to allow for control of concurrent + operations. The length of time for which a deleted document's version remains + available is determined by the `index.gc_deletes` index setting. **Routing** + If routing is used during indexing, the routing value also needs to be specified + to delete a document. If the `_routing` mapping is set to `required` and no routing + value is specified, the delete API throws a `RoutingMissingException` and rejects + the request. For example: ``` DELETE /my-index-000001/_doc/1?routing=shard-1 + ``` This request deletes the document with ID 1, but it is routed based on the + user. The document is not deleted if the correct routing is not specified. **Distributed** + The delete operation gets hashed into a specific shard ID. It then gets redirected + into the primary shard within that ID group and replicated (if needed) to shard + replicas within that ID group. ``_ - :param index: Name of the target index. - :param id: Unique identifier for the document. + :param index: The name of the target index. + :param id: A unique identifier for the document. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period to wait for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. + :param routing: A custom value used to route operations to a specific shard. + :param timeout: The period to wait for active shards. This parameter is useful + for situations where the primary shard assigned to perform the delete operation + might not be available when the delete operation runs. Some reasons for this + might be that the primary shard is currently recovering from a store or undergoing + relocation. By default, the delete operation will wait on the primary shard + to become available for up to 1 minute before failing and responding with + an error. + :param version: An explicit version number for concurrency control. It must match + the current version of the document for the request to succeed. + :param version_type: The version type. + :param wait_for_active_shards: The minimum number of shard copies that must be + active before proceeding with the operation. You can set it to `all` or any + positive integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1638,32 +1747,54 @@ def exists( ] = None, ) -> HeadApiResponse: """ - Check a document. Checks if a specified document exists. + Check a document. Verify that a document exists. For example, check to see if + a document with the `_id` 0 exists: ``` HEAD my-index-000001/_doc/0 ``` If the + document exists, the API returns a status code of `200 - OK`. If the document + doesn’t exist, the API returns `404 - Not Found`. **Versioning support** You + can use the `version` parameter to check the document only if its current version + is equal to the specified one. Internally, Elasticsearch has marked the old document + as deleted and added an entirely new document. The old version of the document + doesn't disappear immediately, although you won't be able to access it. Elasticsearch + cleans up deleted documents in the background as you continue to index more data. ``_ - :param index: Comma-separated list of data streams, indices, and aliases. Supports - wildcards (`*`). - :param id: Identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param index: A comma-separated list of data streams, indices, and aliases. It + supports wildcards (`*`). + :param id: A unique document identifier. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. If it is + set to `_local`, the operation will prefer to be run on a local allocated + shard when possible. If it is set to a custom value, the value is used to + guarantee that the same shards will be used for the same custom value. This + can help with "jumping values" when hitting different shards in different + refresh states. A sample value can be something like the web session ID or + the user name. :param realtime: If `true`, the request is real-time as opposed to near-real-time. - :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. - :param routing: Target the specified primary shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. - :param source_excludes: A comma-separated list of source fields to exclude in - the response. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :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_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` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to false. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` parameter defaults to + `false`. :param version: Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1739,29 +1870,32 @@ def exists_source( ] = None, ) -> HeadApiResponse: """ - Check for a document source. Checks if a document's `_source` is stored. + Check for a document source. Check whether a document source exists in an index. + For example: ``` HEAD my-index-000001/_source/1 ``` A document's source is not + available if it is disabled in the mapping. ``_ - :param index: Comma-separated list of data streams, indices, and aliases. Supports - wildcards (`*`). - :param id: Identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param realtime: If true, the request is real-time as opposed to near-real-time. - :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. - :param routing: Target the specified primary shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. + :param index: A comma-separated list of data streams, indices, and aliases. It + supports wildcards (`*`). + :param id: A unique identifier for the document. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. + :param realtime: If `true`, the request is real-time as opposed to near-real-time. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :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_excludes: A comma-separated list of source fields to exclude in the response. :param source_includes: A comma-separated list of source fields to include in the response. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2079,36 +2213,78 @@ def get( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a document by its ID. Retrieves the document with the specified ID from an - index. + Get a document by its ID. Get a document and its source or stored fields from + an index. By default, this API is realtime and is not affected by the refresh + rate of the index (when data will become visible for search). In the case where + stored fields are requested with the `stored_fields` parameter and the document + has been updated but is not yet refreshed, the API will have to parse and analyze + the source to extract the stored fields. To turn off realtime behavior, set the + `realtime` parameter to false. **Source filtering** By default, the API returns + the contents of the `_source` field unless you have used the `stored_fields` + parameter or the `_source` field is turned off. You can turn off `_source` retrieval + by using the `_source` parameter: ``` GET my-index-000001/_doc/0?_source=false + ``` If you only need one or two fields from the `_source`, use the `_source_includes` + or `_source_excludes` parameters to include or filter out particular fields. + This can be helpful with large documents where partial retrieval can save on + network overhead Both parameters take a comma separated list of fields or wildcard + expressions. For example: ``` GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities + ``` If you only want to specify includes, you can use a shorter notation: ``` + GET my-index-000001/_doc/0?_source=*.id ``` **Routing** If routing is used during + indexing, the routing value also needs to be specified to retrieve a document. + For example: ``` GET my-index-000001/_doc/2?routing=user1 ``` This request gets + the document with ID 2, but it is routed based on the user. The document is not + fetched if the correct routing is not specified. **Distributed** The GET operation + is hashed into a specific shard ID. It is then redirected to one of the replicas + within that shard ID and returns the result. The replicas are the primary shard + and its replicas within that shard ID group. This means that the more replicas + you have, the better your GET scaling will be. **Versioning support** You can + use the `version` parameter to retrieve the document only if its current version + is equal to the specified one. Internally, Elasticsearch has marked the old document + as deleted and added an entirely new document. The old version of the document + doesn't disappear immediately, although you won't be able to access it. Elasticsearch + cleans up deleted documents in the background as you continue to index more data. ``_ - :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. - :param force_synthetic_source: Should this request force synthetic _source? Use - this to test if the mapping supports synthetic _source and to get a sense - of the worst case performance. Fetches with this enabled will be slower the - enabling synthetic source natively in the index. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param index: The name of the index that contains the document. + :param id: A unique document identifier. + :param force_synthetic_source: Indicates whether the request forces synthetic + `_source`. Use this paramater to test if the mapping supports synthetic `_source` + and to get a sense of the worst case performance. Fetches with this parameter + enabled will be slower than enabling synthetic source natively in the index. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. If it is + set to `_local`, the operation will prefer to be run on a local allocated + shard when possible. If it is set to a custom value, the value is used to + guarantee that the same shards will be used for the same custom value. This + can help with "jumping values" when hitting different shards in different + refresh states. A sample value can be something like the web session ID or + the user name. :param realtime: If `true`, the request is real-time as opposed to near-real-time. - :param refresh: If true, Elasticsearch refreshes the affected shards to make - this operation visible to search. If false, do nothing with refreshes. - :param routing: Target the specified primary shard. - :param source: True or false to return the _source field or not, or a list of - fields to return. - :param source_excludes: A comma-separated list of source fields to exclude in - the response. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :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_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` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to false. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: internal, external, external_gte. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` parameter defaults to + `false`. Only leaf fields can be retrieved with the `stored_field` option. + Object fields can't be returned;​if specified, the request fails. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2301,29 +2477,34 @@ def get_source( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a document's source. Returns the source of a document. + Get a document's source. Get the source of a document. For example: ``` GET my-index-000001/_source/1 + ``` You can use the source filtering parameters to control which parts of the + `_source` are returned: ``` GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities + ``` ``_ - :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param realtime: Boolean) If true, the request is real-time as opposed to near-real-time. - :param refresh: If true, Elasticsearch refreshes the affected shards to make - this operation visible to search. If false, do nothing with refreshes. - :param routing: Target the specified primary shard. - :param source: True or false to return the _source field or not, or a list of - fields to return. + :param index: The name of the index that contains the document. + :param id: A unique document identifier. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. + :param realtime: If `true`, the request is real-time as opposed to near-real-time. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :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_excludes: A comma-separated list of source fields to exclude in the response. :param source_includes: A comma-separated list of source fields to include in the response. - :param stored_fields: - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: internal, external, external_gte. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2478,44 +2659,170 @@ def index( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Index a document. Adds a JSON document to the specified data stream or index - and makes it searchable. If the target is an index and the document already exists, - the request updates the document and increments its version. + Create or update a document in an index. Add a JSON document to the specified + data stream or index and make it searchable. If the target is an index and the + document already exists, the request updates the document and increments its + version. NOTE: You cannot use this API to send update requests for existing documents + in a data stream. If the Elasticsearch security features are enabled, you must + have the following index privileges for the target data stream, index, or index + alias: * To add or overwrite a document using the `PUT //_doc/<_id>` + request format, you must have the `create`, `index`, or `write` index privilege. + * To add a document using the `POST //_doc/` request format, you must + have the `create_doc`, `create`, `index`, or `write` index privilege. * To automatically + create a data stream or index with this API request, you must have the `auto_configure`, + `create_index`, or `manage` index privilege. Automatic data stream creation requires + a matching index template with data stream enabled. NOTE: Replica shards might + not all be started when an indexing operation returns successfully. By default, + only the primary is required. Set `wait_for_active_shards` to change this default + behavior. **Automatically create data streams and indices** If the request's + target doesn't exist and matches an index template with a `data_stream` definition, + the index operation automatically creates the data stream. If the target doesn't + exist and doesn't match a data stream template, the operation automatically creates + the index and applies any matching index templates. NOTE: Elasticsearch includes + several built-in index templates. To avoid naming collisions with these templates, + refer to index pattern documentation. If no mapping exists, the index operation + creates a dynamic mapping. By default, new fields and objects are automatically + added to the mapping if needed. Automatic index creation is controlled by the + `action.auto_create_index` setting. If it is `true`, any index can be created + automatically. You can modify this setting to explicitly allow or block automatic + creation of indices that match specified patterns or set it to `false` to turn + off automatic index creation entirely. Specify a comma-separated list of patterns + you want to allow or prefix each pattern with `+` or `-` to indicate whether + it should be allowed or blocked. When a list is specified, the default behaviour + is to disallow. NOTE: The `action.auto_create_index` setting affects the automatic + creation of indices only. It does not affect the creation of data streams. **Optimistic + concurrency control** Index operations can be made conditional and only be performed + if the last modification to the document was assigned the sequence number and + primary term specified by the `if_seq_no` and `if_primary_term` parameters. If + a mismatch is detected, the operation will result in a `VersionConflictException` + and a status code of `409`. **Routing** By default, shard placement — or routing + — is controlled by using a hash of the document's ID value. For more explicit + control, the value fed into the hash function used by the router can be directly + specified on a per-operation basis using the `routing` parameter. When setting + up explicit mapping, you can also use the `_routing` field to direct the index + operation to extract the routing value from the document itself. This does come + at the (very minimal) cost of an additional document parsing pass. If the `_routing` + mapping is defined and set to be required, the index operation will fail if no + routing value is provided or extracted. NOTE: Data streams do not support custom + routing unless they were created with the `allow_custom_routing` setting enabled + in the template. **Distributed** The index operation is directed to the primary + shard based on its route and performed on the actual node containing this shard. + After the primary shard completes the operation, if needed, the update is distributed + to applicable replicas. **Active shards** To improve the resiliency of writes + to the system, indexing operations can be configured to wait for a certain number + of active shard copies before proceeding with the operation. If the requisite + number of active shard copies are not available, then the write operation must + wait and retry, until either the requisite shard copies have started or a timeout + occurs. By default, write operations only wait for the primary shards to be active + before proceeding (that is to say `wait_for_active_shards` is `1`). This default + can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. + To alter this behavior per operation, use the `wait_for_active_shards request` + parameter. Valid values are all or any positive integer up to the total number + of configured copies per shard in the index (which is `number_of_replicas`+1). + Specifying a negative value or a number greater than the number of shard copies + will throw an error. For example, suppose you have a cluster of three nodes, + A, B, and C and you create an index index with the number of replicas set to + 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt + an indexing operation, by default the operation will only ensure the primary + copy of each shard is available before proceeding. This means that even if B + and C went down and A hosted the primary shard copies, the indexing operation + would still proceed with only one copy of the data. If `wait_for_active_shards` + is set on the request to `3` (and all three nodes are up), the indexing operation + will require 3 active shard copies before proceeding. This requirement should + be met because there are 3 active nodes in the cluster, each one holding a copy + of the shard. However, if you set `wait_for_active_shards` to `all` (or to `4`, + which is the same in this situation), the indexing operation will not proceed + as you do not have all 4 copies of each shard active in the index. The operation + will timeout unless a new node is brought up in the cluster to host the fourth + copy of the shard. It is important to note that this setting greatly reduces + the chances of the write operation not writing to the requisite number of shard + copies, but it does not completely eliminate the possibility, because this check + occurs before the write operation starts. After the write operation is underway, + it is still possible for replication to fail on any number of shard copies but + still succeed on the primary. The `_shards` section of the API response reveals + the number of shard copies on which replication succeeded and failed. **No operation + (noop) updates** When updating a document by using this API, a new version of + the document is always created even if the document hasn't changed. If this isn't + acceptable use the `_update` API with `detect_noop` set to `true`. The `detect_noop` + option isn't available on this API because it doesn’t fetch the old source and + isn't able to compare it against the new source. There isn't a definitive rule + for when noop updates aren't acceptable. It's a combination of lots of factors + like how frequently your data source sends updates that are actually noops and + how many queries per second Elasticsearch runs on the shard receiving the updates. + **Versioning** Each indexed document is given a version number. By default, internal + versioning is used that starts at 1 and increments with each update, deletes + included. Optionally, the version number can be set to an external value (for + example, if maintained in a database). To enable this functionality, `version_type` + should be set to `external`. The value provided must be a numeric, long value + greater than or equal to 0, and less than around `9.2e+18`. NOTE: Versioning + is completely real time, and is not affected by the near real time aspects of + search operations. If no version is provided, the operation runs without any + version checks. When using the external version type, the system checks to see + if the version number passed to the index request is greater than the version + of the currently stored document. If true, the document will be indexed and the + new version number used. If the value provided is less than or equal to the stored + document's version number, a version conflict will occur and the index operation + will fail. For example: ``` PUT my-index-000001/_doc/1?version=2&version_type=external + { "user": { "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. ``_ - :param index: Name of the data stream or index to target. + :param index: The name of the data stream or index to target. If the target doesn't + exist and matches the name or wildcard (`*`) pattern of an index template + with a `data_stream` definition, this request creates the data stream. If + the target doesn't exist and doesn't match a data stream template, this request + creates the index. You can check for existing targets with the resolve index + API. :param document: - :param id: Unique identifier for the document. + :param id: A unique identifier for the document. To automatically generate a + document ID, use the `POST //_doc/` request format and omit this + parameter. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. - :param op_type: Set to create to only index the document if it does not already + :param op_type: Set to `create` to only index the document if it does not already exist (put if absent). If a document with the specified `_id` already exists, - the indexing operation will fail. Same as using the `/_create` endpoint. - Valid values: `index`, `create`. If document id is specified, it defaults - to `index`. Otherwise, it defaults to `create`. - :param pipeline: ID of the pipeline to use to preprocess incoming documents. + the indexing operation will fail. The behavior is the same as using the `/_create` + endpoint. If a document ID is specified, this paramater defaults to `index`. + Otherwise, it defaults to `create`. If the request targets a data stream, + an `op_type` of `create` is required. + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. :param require_alias: If `true`, the destination must be an index alias. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period the request waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param routing: A custom value that is used to route operations to a specific + shard. + :param timeout: The period the request waits for the following operations: automatic + index creation, dynamic mapping updates, waiting for active shards. This + parameter is useful for situations where the primary shard assigned to perform + the operation might not be available when the operation runs. Some reasons + for this might be that the primary shard is currently recovering from a gateway + or undergoing relocation. By default, the operation will wait on the primary + shard to become available for at least 1 minute before failing and responding + with an error. The actual wait time could be longer, particularly when multiple + waits occur. + :param version: An explicit version number for concurrency control. It must be + a non-negative long number. + :param version_type: The version type. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to all or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. You can set it to `all` or any positive + integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -3504,33 +3811,191 @@ def reindex( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Reindex documents. Copies documents from a source to a destination. The source - can be any existing index, alias, or data stream. The destination must differ - from the source. For example, you cannot reindex a data stream into itself. + Reindex documents. Copy documents from a source to a destination. You can copy + all documents to the destination index or reindex a subset of the documents. + The source can be any existing index, alias, or data stream. The destination + must differ from the source. For example, you cannot reindex a data stream into + itself. IMPORTANT: Reindex requires `_source` to be enabled for all documents + in the source. The destination should be configured as wanted before calling + the reindex API. Reindex does not copy the settings from the source or its associated + template. Mappings, shard counts, and replicas, for example, must be configured + ahead of time. If the Elasticsearch security features are enabled, you must have + the following security privileges: * The `read` index privilege for the source + data stream, index, or alias. * The `write` index privilege for the destination + data stream, index, or index alias. * To automatically create a data stream or + index with a reindex API request, you must have the `auto_configure`, `create_index`, + or `manage` index privilege for the destination data stream, index, or alias. + * If reindexing from a remote cluster, the `source.remote.user` must have the + `monitor` cluster privilege and the `read` index privilege for the source data + stream, index, or alias. If reindexing from a remote cluster, you must explicitly + allow the remote host in the `reindex.remote.whitelist` setting. Automatic data + stream creation requires a matching index template with data stream enabled. + The `dest` element can be configured like the index API to control optimistic + concurrency control. Omitting `version_type` or setting it to `internal` causes + Elasticsearch to blindly dump documents into the destination, overwriting any + that happen to have the same ID. Setting `version_type` to `external` causes + Elasticsearch to preserve the `version` from the source, create any documents + that are missing, and update any documents that have an older version in the + destination than they do in the source. Setting `op_type` to `create` causes + the reindex API to create only missing documents in the destination. All existing + documents will cause a version conflict. IMPORTANT: Because data streams are + append-only, any reindex request to a destination data stream must have an `op_type` + of `create`. A reindex can only add new documents to a destination data stream. + It cannot update existing documents in a destination data stream. By default, + version conflicts abort the reindex process. To continue reindexing if there + are conflicts, set the `conflicts` request body property to `proceed`. In this + case, the response includes a count of the version conflicts that were encountered. + Note that the handling of other error types is unaffected by the `conflicts` + property. Additionally, if you opt to count version conflicts, the operation + could attempt to reindex more documents from the source than `max_docs` until + it has successfully indexed `max_docs` documents into the target or it has gone + through every document in the source query. NOTE: The reindex API makes no effort + to handle ID collisions. The last document written will "win" but the order isn't + usually predictable so it is not a good idea to rely on this behavior. Instead, + make sure that IDs are unique by using a script. **Running reindex asynchronously** + If the request contains `wait_for_completion=false`, Elasticsearch performs some + preflight checks, launches the request, and returns a task you can use to cancel + or get the status of the task. Elasticsearch creates a record of this task as + a document at `_tasks/`. **Reindex from multiple sources** If you have + many sources to reindex it is generally better to reindex them one at a time + rather than using a glob pattern to pick up multiple sources. That way you can + resume the process if there are any errors by removing the partially completed + source and starting over. It also makes parallelizing the process fairly simple: + split the list of sources to reindex and run each list in parallel. For example, + you can use a bash script like this: ``` for index in i1 i2 i3 i4 i5; do curl + -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{ "source": + { "index": "'$index'" }, "dest": { "index": "'$index'-reindexed" } }' done ``` + **Throttling** Set `requests_per_second` to any positive decimal number (`1.4`, + `6`, `1000`, for example) to throttle the rate at which reindex issues batches + of index operations. Requests are throttled by padding each batch with a wait + time. To turn off throttling, set `requests_per_second` to `-1`. The throttling + is done by waiting between batches so that the scroll that reindex uses internally + can be given a timeout that takes into account the padding. The padding time + is the difference between the batch size divided by the `requests_per_second` + and the time spent writing. By default the batch size is `1000`, so if `requests_per_second` + is set to `500`: ``` target_time = 1000 / 500 per second = 2 seconds wait_time + = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds ``` Since the + batch is issued as a single bulk request, large batch sizes cause Elasticsearch + to create many requests and then wait for a while before starting the next set. + This is "bursty" instead of "smooth". **Slicing** Reindex supports sliced scroll + to parallelize the reindexing process. This parallelization can improve efficiency + and provide a convenient way to break the request down into smaller parts. NOTE: + Reindexing from remote clusters does not support manual or automatic slicing. + You can slice a reindex request manually by providing a slice ID and total number + of slices to each request. You can also let reindex automatically parallelize + by using sliced scroll to slice on `_id`. The `slices` parameter specifies the + number of slices to use. Adding `slices` to the reindex request just automates + the manual process, creating sub-requests which means it has some quirks: * You + can see these requests in the tasks API. These sub-requests are "child" tasks + of the task for the request with slices. * Fetching the status of the task for + the request with `slices` only contains the status of completed slices. * These + sub-requests are individually addressable for things like cancellation and rethrottling. + * Rethrottling the request with `slices` will rethrottle the unfinished sub-request + proportionally. * Canceling the request with `slices` will cancel each sub-request. + * Due to the nature of `slices`, each sub-request won't get a perfectly even + portion of the documents. All documents will be addressed, but some slices may + be larger than others. Expect larger slices to have a more even distribution. + * Parameters like `requests_per_second` and `max_docs` on a request with `slices` + are distributed proportionally to each sub-request. Combine that with the previous + point about distribution being uneven and you should conclude that using `max_docs` + with `slices` might not result in exactly `max_docs` documents being reindexed. + * Each sub-request gets a slightly different snapshot of the source, though these + are all taken at approximately the same time. If slicing automatically, setting + `slices` to `auto` will choose a reasonable number for most indices. If slicing + manually or otherwise tuning automatic slicing, use the following guidelines. + Query performance is most efficient when the number of slices is equal to the + number of shards in the index. If that number is large (for example, `500`), + choose a lower number as too many slices will hurt performance. Setting slices + higher than the number of shards generally does not improve efficiency and adds + overhead. Indexing performance scales linearly across available resources with + the number of slices. Whether query or indexing performance dominates the runtime + depends on the documents being reindexed and cluster resources. **Modify documents + during reindexing** Like `_update_by_query`, reindex operations support a script + that modifies the document. Unlike `_update_by_query`, the script is allowed + to modify the document's metadata. Just as in `_update_by_query`, you can set + `ctx.op` to change the operation that is run on the destination. For example, + set `ctx.op` to `noop` if your script decides that the document doesn’t have + to be indexed in the destination. This "no operation" will be reported in the + `noop` counter in the response body. Set `ctx.op` to `delete` if your script + decides that the document must be deleted from the destination. The deletion + will be reported in the `deleted` counter in the response body. Setting `ctx.op` + to anything else will return an error, as will setting any other field in `ctx`. + Think of the possibilities! Just be careful; you are able to change: * `_id` + * `_index` * `_version` * `_routing` Setting `_version` to `null` or clearing + it from the `ctx` map is just like not sending the version in an indexing request. + It will cause the document to be overwritten in the destination regardless of + the version on the target or the version type you use in the reindex API. **Reindex + from remote** Reindex supports reindexing from a remote Elasticsearch cluster. + The `host` parameter must contain a scheme, host, port, and optional path. The + `username` and `password` parameters are optional and when they are present the + reindex operation will connect to the remote Elasticsearch node using basic authentication. + Be sure to use HTTPS when using basic authentication or the password will be + sent in plain text. There are a range of settings available to configure the + behavior of the HTTPS connection. When using Elastic Cloud, it is also possible + to authenticate against the remote cluster through the use of a valid API key. + Remote hosts must be explicitly allowed with the `reindex.remote.whitelist` setting. + It can be set to a comma delimited list of allowed remote host and port combinations. + Scheme is ignored; only the host and port are used. For example: ``` reindex.remote.whitelist: + [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*"] ``` The list of + allowed hosts must be configured on any nodes that will coordinate the reindex. + This feature should work with remote clusters of any version of Elasticsearch. + This should enable you to upgrade from any version of Elasticsearch to the current + version by reindexing from a cluster of the old version. WARNING: Elasticsearch + does not support forward compatibility across major versions. For example, you + cannot reindex from a 7.x cluster into a 6.x cluster. To enable queries sent + to older versions of Elasticsearch, the `query` parameter is sent directly to + the remote host without validation or modification. NOTE: Reindexing from remote + clusters does not support manual or automatic slicing. Reindexing from a remote + server uses an on-heap buffer that defaults to a maximum size of 100mb. If the + remote index includes very large documents you'll need to use a smaller batch + size. It is also possible to set the socket read timeout on the remote connection + with the `socket_timeout` field and the connection timeout with the `connect_timeout` + field. Both default to 30 seconds. **Configuring SSL parameters** Reindex from + remote supports configurable SSL settings. These must be specified in the `elasticsearch.yml` + file, with the exception of the secure settings, which you add in the Elasticsearch + keystore. It is not possible to configure SSL in the body of the reindex request. ``_ :param dest: The destination you are copying to. :param source: The source you are copying from. - :param conflicts: Set to proceed to continue reindexing even if there are conflicts. - :param max_docs: The maximum number of documents to reindex. + :param conflicts: Indicates whether to continue reindexing even when there are + conflicts. + :param max_docs: The maximum number of documents to reindex. By default, all + documents are reindexed. If it is a value less then or equal to `scroll_size`, + a scroll will not be used to retrieve the results for the operation. If `conflicts` + is set to `proceed`, the reindex operation could attempt to reindex more + documents from the source than `max_docs` until it has successfully indexed + `max_docs` documents into the target or it has gone through every document + in the source query. :param refresh: If `true`, the request refreshes affected shards to make this operation visible to search. :param requests_per_second: The throttle for this request in sub-requests per - second. Defaults to no throttle. + second. By default, there is no throttle. :param require_alias: If `true`, the destination must be an index alias. :param script: The script to run to update the document source or metadata when reindexing. - :param scroll: Specifies how long a consistent view of the index should be maintained - for scrolled search. + :param scroll: The period of time that a consistent view of the index should + be maintained for scrolled search. :param size: - :param slices: The number of slices this task should be divided into. Defaults - to 1 slice, meaning the task isn’t sliced into subtasks. - :param timeout: Period each indexing waits for automatic index creation, dynamic - mapping updates, and waiting for active shards. + :param slices: The number of slices this task should be divided into. It defaults + to one slice, which means the task isn't sliced into subtasks. Reindex supports + sliced scroll to parallelize the reindexing process. This parallelization + can improve efficiency and provide a convenient way to break the request + down into smaller parts. NOTE: Reindexing from remote clusters does not support + manual or automatic slicing. If set to `auto`, Elasticsearch chooses the + number of slices to use. This setting will use one slice per shard, up to + a certain limit. If there are multiple sources, it will choose the number + of slices based on the index or backing index with the smallest number of + shards. + :param timeout: The period each indexing waits for automatic index creation, + dynamic mapping updates, and waiting for active shards. By default, Elasticsearch + waits for at least one minute before failing. The actual wait time could + be longer, particularly when multiple waits occur. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. Set it to `all` or any positive integer + up to the total number of shards in the index (`number_of_replicas+1`). The + default value is one, which means it waits for each primary shard to be active. :param wait_for_completion: If `true`, the request blocks until the operation is complete. """ @@ -3603,13 +4068,17 @@ def reindex_rethrottle( ) -> ObjectApiResponse[t.Any]: """ Throttle a reindex operation. Change the number of requests per second for a - particular reindex operation. + particular reindex operation. For example: ``` POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1 + ``` Rethrottling that speeds up the query takes effect immediately. Rethrottling + that slows down the query will take effect after completing the current batch. + This behavior prevents scroll timeouts. ``_ - :param task_id: Identifier for the task. + :param task_id: The task identifier, which can be found by using the tasks API. :param requests_per_second: The throttle for this request in sub-requests per - second. + second. It can be either `-1` to turn off throttling or any decimal number + like `1.7` or `12` to throttle to that level. """ if task_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'task_id'") @@ -5056,46 +5525,60 @@ def update( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a document. Updates a document by running a script or passing a partial - document. + Update a document. Update a document by running a script or passing a partial + document. If the Elasticsearch security features are enabled, you must have the + `index` or `write` index privilege for the target index or index alias. The script + can update, delete, or skip modifying the document. The API also supports passing + a partial document, which is merged into the existing document. To fully replace + an existing document, use the index API. This operation: * Gets the document + (collocated with the shard) from the index. * Runs the specified script. * Indexes + the result. The document must still be reindexed, but using this API removes + some network roundtrips and reduces chances of version conflicts between the + GET and the index operation. The `_source` field must be enabled to use this + API. In addition to `_source`, you can access the following variables through + the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the + current timestamp). ``_ - :param index: The name of the index - :param id: Document ID - :param detect_noop: Set to false to disable setting 'result' in the response - to 'noop' if no change to the document occurred. - :param doc: A partial update to an existing document. - :param doc_as_upsert: Set to true to use the contents of 'doc' as the value of - 'upsert' + :param index: The name of the target index. By default, the index is created + automatically if it doesn't exist. + :param id: A unique identifier for the document to be updated. + :param detect_noop: If `true`, the `result` in the response is set to `noop` + (no operation) when there are no changes to the document. + :param doc: A partial update to an existing document. If both `doc` and `script` + are specified, `doc` is ignored. + :param doc_as_upsert: If `true`, use the contents of 'doc' as the value of 'upsert'. + NOTE: Using ingest pipelines with `doc_as_upsert` is not supported. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. :param lang: The script language. :param refresh: If 'true', Elasticsearch refreshes the affected shards to make - this operation visible to search, if 'wait_for' then wait for a refresh to - make this operation visible to search, if 'false' do nothing with refreshes. - :param require_alias: If true, the destination must be an index alias. - :param retry_on_conflict: Specify how many times should the operation be retried + this operation visible to search. If 'wait_for', it waits for a refresh to + make this operation visible to search. If 'false', it does nothing with refreshes. + :param require_alias: If `true`, the destination must be an index alias. + :param retry_on_conflict: The number of times the operation should be retried when a conflict occurs. - :param routing: Custom value used to route operations to a specific shard. - :param script: Script to execute to update the document. - :param scripted_upsert: Set to true to execute the script whether or not the - document exists. - :param source: Set to false to disable source retrieval. You can also specify - a comma-separated list of the fields you want to retrieve. - :param source_excludes: Specify the source fields you want to exclude. - :param source_includes: Specify the source fields you want to retrieve. - :param timeout: Period to wait for dynamic mapping updates and active shards. - This guarantees Elasticsearch waits for at least the timeout before failing. - The actual wait time could be longer, particularly when multiple waits occur. + :param routing: A custom value used to route operations to a specific shard. + :param script: The script to run to update the document. + :param scripted_upsert: If `true`, run the script whether or not the document + exists. + :param source: If `false`, turn off source retrieval. You can also specify a + comma-separated list of the fields you want to retrieve. + :param source_excludes: The source fields you want to exclude. + :param source_includes: The source fields you want to retrieve. + :param timeout: The period to wait for the following operations: dynamic mapping + updates and waiting for active shards. Elasticsearch waits for at least the + timeout period before failing. The actual wait time could be longer, particularly + when multiple waits occur. :param upsert: If the document does not already exist, the contents of 'upsert' - are inserted as a new document. If the document exists, the 'script' is executed. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operations. Set to 'all' or any positive integer - up to the total number of shards in the index (number_of_replicas+1). Defaults - to 1 meaning the primary shard. + are inserted as a new document. If the document exists, the 'script' is run. + :param wait_for_active_shards: The number of copies of each shard that must be + active before proceeding with the operation. Set to 'all' or any positive + integer up to the total number of shards in the index (`number_of_replicas`+1). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") diff --git a/elasticsearch/_sync/client/cat.py b/elasticsearch/_sync/client/cat.py index bb66e693e..654478566 100644 --- a/elasticsearch/_sync/client/cat.py +++ b/elasticsearch/_sync/client/cat.py @@ -56,8 +56,8 @@ def aliases( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get aliases. Retrieves the cluster’s index aliases, including filter and routing - information. The API does not return data stream aliases. CAT APIs are only intended + Get aliases. Get the cluster's index aliases, including filter and routing information. + This API does not return data stream aliases. IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API. @@ -66,14 +66,19 @@ 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 expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. + :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 help: When set to `true` will output available columns. This option can't be combined with any other query string option. - :param master_timeout: Period to wait for a connection to the master node. + :param master_timeout: The period to wait for a connection to the master node. + If the master node is not available before the timeout expires, the request + fails and returns an error. To indicated that the request should never timeout, + you can set it to `-1`. :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. @@ -141,13 +146,13 @@ def allocation( ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ Get shard allocation information. Get a snapshot of the number of shards allocated - to each data node and their disk space. IMPORTANT: cat APIs are only intended + to each data node and their disk space. IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. ``_ - :param node_id: Comma-separated list of node identifiers or names used to limit + :param node_id: A comma-separated list of node identifiers or names used to limit the returned information. :param bytes: The unit used to display byte values. :param format: Specifies the format to return the columnar data in, can be set @@ -225,17 +230,17 @@ def component_templates( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get component templates. Returns information about component templates in a cluster. + Get component templates. Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that - specify index mappings, settings, and aliases. CAT APIs are only intended for - human consumption using the command line or Kibana console. They are not intended - for use by applications. For application consumption, use the get component template - API. + specify index mappings, settings, and aliases. IMPORTANT: CAT APIs are only intended + for human consumption using the command line or Kibana console. They are not + intended for use by applications. For application consumption, use the get component + template API. ``_ - :param name: The name of the component template. Accepts wildcard expressions. - If omitted, all component templates are returned. + :param name: The name of the component template. It accepts wildcard expressions. + If it is omitted, all component templates are returned. :param 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. @@ -245,7 +250,7 @@ def component_templates( the local cluster state. If `false` the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node. - :param master_timeout: Period to wait for a connection to the master node. + :param master_timeout: The period to wait for a connection to the master node. :param s: List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting `:asc` or `:desc` as a suffix to the column name. @@ -307,17 +312,17 @@ def count( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get a document count. Provides quick access to a document count for a data stream, + Get a document count. Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, - not deleted documents which have not yet been removed by the merge process. CAT - APIs are only intended for human consumption using the command line or Kibana + not deleted documents which have not yet been removed by the merge process. IMPORTANT: + CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API. ``_ - :param index: Comma-separated list of data streams, indices, and aliases used - to limit the request. Supports wildcards (`*`). To target all data streams + :param index: A comma-separated list of data streams, indices, and aliases used + to limit the request. It supports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`. :param format: Specifies the format to return the columnar data in, can be set to `text`, `json`, `cbor`, `yaml`, or `smile`. @@ -462,7 +467,7 @@ def health( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get the cluster health status. IMPORTANT: cat APIs are only intended for human + Get the cluster health status. IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the cluster health API. This API is often used to check malfunctioning clusters. To help you track cluster @@ -526,7 +531,7 @@ def health( @_rewrite_parameters() def help(self) -> TextApiResponse: """ - Get CAT help. Returns help for the CAT APIs. + Get CAT help. Get help for the CAT APIs. ``_ """ @@ -577,7 +582,7 @@ def indices( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get index information. Returns high-level information about indices in a cluster, + Get index information. Get high-level information about indices in a cluster, including backing indices for data streams. Use this request to get the following information for each index in a cluster: - shard count - document count - deleted document count - primary store size - total store size of all shards, including @@ -853,9 +858,9 @@ def ml_data_frame_analytics( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get data frame analytics jobs. Returns configuration and usage information about - data frame analytics jobs. CAT APIs are only intended for human consumption using - the Kibana console or command line. They are not intended for use by applications. + Get data frame analytics jobs. Get configuration and usage information about + data frame analytics jobs. IMPORTANT: CAT APIs are only intended for human consumption + using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get data frame analytics jobs statistics API. @@ -1015,12 +1020,13 @@ def ml_datafeeds( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get datafeeds. Returns configuration and usage information about datafeeds. This + Get datafeeds. Get configuration and usage information about datafeeds. This API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` - cluster privileges to use this API. CAT APIs are only intended for human consumption - using the Kibana console or command line. They are not intended for use by applications. - For application consumption, use the get datafeed statistics API. + cluster privileges to use this API. IMPORTANT: CAT APIs are only intended for + human consumption using the Kibana console or command line. They are not intended + for use by applications. For application consumption, use the get datafeed statistics + API. ``_ @@ -1376,13 +1382,13 @@ def ml_jobs( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get anomaly detection jobs. Returns configuration and usage information for anomaly + Get anomaly detection jobs. Get configuration and usage information for anomaly detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, - or `manage` cluster privileges to use this API. CAT APIs are only intended for - human consumption using the Kibana console or command line. They are not intended - for use by applications. For application consumption, use the get anomaly detection - job statistics API. + or `manage` cluster privileges to use this API. IMPORTANT: CAT APIs are only + intended for human consumption using the Kibana console or command line. They + are not intended for use by applications. For application consumption, use the + get anomaly detection job statistics API. ``_ @@ -1560,10 +1566,10 @@ def ml_trained_models( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get trained models. Returns configuration and usage information about inference - trained models. CAT APIs are only intended for human consumption using the Kibana - console or command line. They are not intended for use by applications. For application - consumption, use the get trained models statistics API. + Get trained models. Get configuration and usage information about inference trained + models. IMPORTANT: CAT APIs are only intended for human consumption using the + Kibana console or command line. They are not intended for use by applications. + For application consumption, use the get trained models statistics API. ``_ @@ -2325,7 +2331,7 @@ def snapshots( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get snapshot information Get information about the snapshots stored in one or + Get snapshot information. Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. diff --git a/elasticsearch/_sync/client/indices.py b/elasticsearch/_sync/client/indices.py index 196eeb418..b74f28523 100644 --- a/elasticsearch/_sync/client/indices.py +++ b/elasticsearch/_sync/client/indices.py @@ -4943,89 +4943,6 @@ def stats( path_parts=__path_parts, ) - @_rewrite_parameters() - def unfreeze( - self, - *, - index: str, - allow_no_indices: t.Optional[bool] = 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, - human: t.Optional[bool] = None, - ignore_unavailable: 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, - wait_for_active_shards: t.Optional[str] = None, - ) -> ObjectApiResponse[t.Any]: - """ - Unfreeze an index. When a frozen index is unfrozen, the index goes through the - normal recovery process and becomes writeable again. - - ``_ - - :param index: Identifier for the index. - :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. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. - :param ignore_unavailable: If `false`, the request returns an error if it targets - a missing or closed index. - :param master_timeout: Period to wait for a connection to the master node. If - no response is received before the timeout expires, the request fails and - returns an error. - :param timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). - """ - if index in SKIP_IN_PATH: - raise ValueError("Empty value passed for parameter 'index'") - __path_parts: t.Dict[str, str] = {"index": _quote(index)} - __path = f'/{__path_parts["index"]}/_unfreeze' - __query: t.Dict[str, t.Any] = {} - if allow_no_indices is not None: - __query["allow_no_indices"] = allow_no_indices - 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 human is not None: - __query["human"] = human - if ignore_unavailable is not None: - __query["ignore_unavailable"] = ignore_unavailable - 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 - if wait_for_active_shards is not None: - __query["wait_for_active_shards"] = wait_for_active_shards - __headers = {"accept": "application/json"} - return self.perform_request( # type: ignore[return-value] - "POST", - __path, - params=__query, - headers=__headers, - endpoint_id="indices.unfreeze", - path_parts=__path_parts, - ) - @_rewrite_parameters( body_fields=("actions",), ) diff --git a/elasticsearch/_sync/client/security.py b/elasticsearch/_sync/client/security.py index 17ee5dcbc..7f8d4c701 100644 --- a/elasticsearch/_sync/client/security.py +++ b/elasticsearch/_sync/client/security.py @@ -481,7 +481,8 @@ def clear_cached_privileges( ``_ - :param application: A comma-separated list of application names + :param application: A comma-separated list of applications. To clear all applications, + use an asterism (`*`). It does not support other wildcard patterns. """ if application in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'application'") @@ -519,12 +520,19 @@ def clear_cached_realms( ) -> ObjectApiResponse[t.Any]: """ Clear the user cache. Evict users from the user cache. You can completely clear - the cache or evict specific users. + the cache or evict specific users. User credentials are cached in memory on each + node to avoid connecting to a remote authentication service or hitting the disk + for every incoming request. There are realm settings that you can use to configure + the user cache. For more information, refer to the documentation about controlling + the user cache. ``_ - :param realms: Comma-separated list of realms to clear - :param usernames: Comma-separated list of usernames to clear from the cache + :param realms: A comma-separated list of realms. To clear all realms, use an + asterisk (`*`). It does not support other wildcard patterns. + :param usernames: A comma-separated list of the users to clear from the cache. + If you do not specify this parameter, the API evicts all users from the user + cache. """ if realms in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'realms'") @@ -566,7 +574,9 @@ def clear_cached_roles( ``_ - :param name: Role name + :param name: A comma-separated list of roles to evict from the role cache. To + evict all roles, use an asterisk (`*`). It does not support other wildcard + patterns. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -605,13 +615,20 @@ def clear_cached_service_tokens( ) -> ObjectApiResponse[t.Any]: """ Clear service account token caches. Evict a subset of all entries from the service - account token caches. + account token caches. Two separate caches exist for service account tokens: one + cache for tokens backed by the `service_tokens` file, and another for tokens + backed by the `.security` index. This API clears matching entries from both caches. + The cache for service account tokens backed by the `.security` index is cleared + automatically on state changes of the security index. The cache for tokens backed + by the `service_tokens` file is cleared automatically on file changes. ``_ - :param namespace: An identifier for the namespace - :param service: An identifier for the service name - :param name: A comma-separated list of service token names + :param namespace: The namespace, which is a top-level grouping of service accounts. + :param service: The name of the service, which must be unique within its namespace. + :param name: A comma-separated list of token names to evict from the service + account token caches. Use a wildcard (`*`) to evict all tokens that belong + to a service account. It does not support other wildcard patterns. """ if namespace in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'namespace'") @@ -665,30 +682,40 @@ def create_api_key( ) -> ObjectApiResponse[t.Any]: """ Create an API key. Create an API key for access without requiring basic authentication. - A successful request returns a JSON structure that contains the API key, its - unique id, and its name. If applicable, it also returns expiration information - for the API key in milliseconds. NOTE: By default, API keys never expire. You - can specify expiration information when you create the API keys. + IMPORTANT: If the credential that is used to authenticate this request is an + API key, the derived API key cannot have any privileges. If you specify privileges, + the API returns an error. A successful request returns a JSON structure that + contains the API key, its unique id, and its name. If applicable, it also returns + expiration information for the API key in milliseconds. NOTE: By default, API + keys never expire. You can specify expiration information when you create the + API keys. The API keys are created by the Elasticsearch API key service, which + is automatically enabled. To configure or turn off the API key service, refer + to API key service setting documentation. ``_ - :param expiration: Expiration time for the API key. By default, API keys never - expire. + :param expiration: The expiration time for the API key. By default, API keys + never expire. :param metadata: Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with `_` are reserved for system usage. - :param name: Specifies the name for this API key. + :param name: A name for the API key. :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. - :param role_descriptors: An array of role descriptors for this API key. This - parameter is optional. When it is not specified or is an empty array, then - the API key will have a point in time snapshot of permissions of the authenticated - user. If you supply role descriptors then the resultant permissions would - be an intersection of API keys permissions and authenticated user’s permissions - thereby limiting the access scope for API keys. The structure of role descriptor - is the same as the request for create role API. For more details, see create - or update roles API. + :param role_descriptors: An array of role descriptors for this API key. When + it is not specified or it is an empty array, the API key will have a point + in time snapshot of permissions of the authenticated user. If you supply + role descriptors, the resultant permissions are an intersection of API keys + permissions and the authenticated user's permissions thereby limiting the + access scope for API keys. The structure of role descriptor is the same as + the request for the create role API. For more details, refer to the create + or update roles API. NOTE: Due to the way in which this permission intersection + is calculated, it is not possible to create an API key that is a child of + another API key, unless the derived key is created without any privileges. + In this case, you must explicitly specify a role descriptor with no privileges. + The derived API key can be used for authentication; it will not have authority + to call Elasticsearch APIs. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/api_key" @@ -825,13 +852,21 @@ def create_service_token( ) -> ObjectApiResponse[t.Any]: """ Create a service account token. Create a service accounts token for access without - requiring basic authentication. + requiring basic authentication. NOTE: Service account tokens never expire. You + must actively delete them if they are no longer needed. ``_ - :param namespace: An identifier for the namespace - :param service: An identifier for the service name - :param name: An identifier for the token name + :param namespace: The name of the namespace, which is a top-level grouping of + service accounts. + :param service: The name of the service. + :param name: The name for the service account token. If omitted, a random name + will be generated. Token names must be at least one and no more than 256 + characters. They can contain alphanumeric characters (a-z, A-Z, 0-9), dashes + (`-`), and underscores (`_`), but cannot begin with an underscore. NOTE: + 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 make this operation visible to search, if `false` then do nothing with refreshes. @@ -963,12 +998,16 @@ def delete_privileges( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete application privileges. + Delete application privileges. To use this API, you must have one of the following + privileges: * The `manage_security` cluster privilege (or a greater privilege + such as `all`). * The "Manage Application Privileges" global privilege for the + application being referenced in the request. ``_ - :param application: Application name - :param name: Privilege name + :param application: The name of the application. Application privileges are always + associated with exactly one application. + :param name: The name of the privilege. :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. @@ -1019,11 +1058,14 @@ def delete_role( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete roles. Delete roles in the native realm. + Delete roles. Delete roles in the native realm. The role management APIs are + generally the preferred way to manage roles, rather than using file-based role + management. The delete roles API cannot remove roles that are defined in roles + files. ``_ - :param name: Role name + :param name: The name of the role. :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. @@ -1067,11 +1109,16 @@ def delete_role_mapping( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete role mappings. + Delete role mappings. Role mappings define which roles are assigned to each user. + The role mapping APIs are generally the preferred way to manage role mappings + rather than using role mapping files. The delete role mappings API cannot remove + role mappings that are defined in role mapping files. ``_ - :param name: Role-mapping name + :param name: The distinct name that identifies the role mapping. The name is + used solely as an identifier to facilitate interaction via the API; it does + not affect the behavior of the mapping in any way. :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. @@ -1122,9 +1169,9 @@ def delete_service_token( ``_ - :param namespace: An identifier for the namespace - :param service: An identifier for the service name - :param name: An identifier for the token name + :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 make this operation visible to search, if `false` then do nothing with refreshes. @@ -1180,7 +1227,7 @@ def delete_user( ``_ - :param username: username + :param username: An identifier for the user. :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. @@ -1224,11 +1271,12 @@ def disable_user( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Disable users. Disable users in the native realm. + Disable users. Disable users in the native realm. By default, when you create + users, they are enabled. You can use this API to revoke a user's access to Elasticsearch. ``_ - :param username: The username of the user to disable + :param username: An identifier for the user. :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. @@ -1328,11 +1376,12 @@ def enable_user( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Enable users. Enable users in the native realm. + Enable users. Enable users in the native realm. By default, when you create users, + they are enabled. ``_ - :param username: The username of the user to enable + :param username: An identifier for the user. :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. @@ -1428,7 +1477,10 @@ def enroll_kibana( ) -> ObjectApiResponse[t.Any]: """ Enroll Kibana. Enable a Kibana instance to configure itself for communication - with a secured Elasticsearch cluster. + with a secured Elasticsearch cluster. NOTE: This API is currently intended for + internal use only by Kibana. Kibana uses this API internally to configure itself + for communications with an Elasticsearch cluster that already has security features + enabled. ``_ """ @@ -1464,7 +1516,11 @@ def enroll_node( ) -> ObjectApiResponse[t.Any]: """ Enroll a node. Enroll a new node to allow it to join an existing cluster with - security features enabled. + security features enabled. The response contains all the necessary information + for the joining node to bootstrap discovery and security related settings so + that it can successfully join the cluster. The response contains key and certificate + material that allows the caller to generate valid signed certificates for the + HTTP layer of all nodes in the cluster. ``_ """ @@ -1623,12 +1679,18 @@ def get_privileges( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get application privileges. + Get application privileges. To use this API, you must have one of the following + privileges: * The `read_security` cluster privilege (or a greater privilege such + as `manage_security` or `all`). * The "Manage Application Privileges" global + privilege for the application being referenced in the request. ``_ - :param application: Application name - :param name: Privilege name + :param application: The name of the application. Application privileges are always + associated with exactly one application. If you do not specify this parameter, + the API returns information about all privileges for all applications. + :param name: The name of the privilege. If you do not specify this parameter, + the API returns information about all privileges for the requested application. """ __path_parts: t.Dict[str, str] if application not in SKIP_IN_PATH and name not in SKIP_IN_PATH: @@ -1670,7 +1732,9 @@ def get_role( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get roles. Get roles in the native realm. + Get roles. Get roles in the native realm. The role management APIs are generally + the preferred way to manage roles, rather than using file-based role management. + The get roles API cannot retrieve roles that are defined in roles files. ``_ @@ -1767,14 +1831,15 @@ def get_service_accounts( ) -> ObjectApiResponse[t.Any]: """ Get service accounts. Get a list of service accounts that match the provided - path parameters. + path parameters. NOTE: Currently, only the `elastic/fleet-server` service account + is available. ``_ - :param namespace: Name of the namespace. Omit this parameter to retrieve information - about all service accounts. If you omit this parameter, you must also omit - the `service` parameter. - :param service: Name of the service name. Omit this parameter to retrieve information + :param namespace: The name of the namespace. Omit this parameter to retrieve + information about all service accounts. If you omit this parameter, you must + also omit the `service` parameter. + :param service: The service name. Omit this parameter to retrieve information about all service accounts that belong to the specified `namespace`. """ __path_parts: t.Dict[str, str] @@ -1818,12 +1883,19 @@ def get_service_credentials( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get service account credentials. + Get service account credentials. To use this API, you must have at least the + `read_security` cluster privilege (or a greater privilege such as `manage_service_account` + or `manage_security`). The response includes service account tokens that were + created with the create service account tokens API as well as file-backed tokens + from all nodes of the cluster. NOTE: For tokens backed by the `service_tokens` + file, the API collects them from all nodes of the cluster. Tokens with the same + name from different nodes are assumed to be the same token and are only counted + once towards the total number of service tokens. ``_ - :param namespace: Name of the namespace. - :param service: Name of the service name. + :param namespace: The name of the namespace. + :param service: The service name. """ if namespace in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'namespace'") @@ -1865,7 +1937,9 @@ def get_settings( ) -> ObjectApiResponse[t.Any]: """ Get security index settings. Get the user-configurable settings for the security - internal index (`.security` and associated indices). + internal index (`.security` and associated indices). Only a subset of the index + settings — those that are user-configurable—will be shown. This includes: * `index.auto_expand_replicas` + * `index.number_of_replicas` ``_ @@ -1930,15 +2004,39 @@ def get_token( ) -> ObjectApiResponse[t.Any]: """ Get a token. Create a bearer token for access without requiring basic authentication. + The tokens are created by the Elasticsearch Token Service, which is automatically + enabled when you configure TLS on the HTTP interface. Alternatively, you can + explicitly enable the `xpack.security.authc.token.enabled` setting. When you + are running in production mode, a bootstrap check prevents you from enabling + the token service unless you also enable TLS on the HTTP interface. The get token + API takes the same parameters as a typical OAuth 2.0 token API except for the + use of a JSON request body. A successful get token API call returns a JSON structure + that contains the access token, the amount of time (seconds) that the token expires + in, the type, and the scope if available. The tokens returned by the get token + API have a finite period of time for which they are valid and after that time + period, they can no longer be used. That time period is defined by the `xpack.security.authc.token.timeout` + setting. If you want to invalidate a token immediately, you can do so by using + the invalidate token API. ``_ - :param grant_type: - :param kerberos_ticket: - :param password: - :param refresh_token: - :param scope: - :param username: + :param grant_type: The type of grant. Supported grant types are: `password`, + `_kerberos`, `client_credentials`, and `refresh_token`. + :param kerberos_ticket: The base64 encoded kerberos ticket. If you specify the + `_kerberos` grant type, this parameter is required. This parameter is not + valid with any other supported grant type. + :param password: The user's password. If you specify the `password` grant type, + this parameter is required. This parameter is not valid with any other supported + grant type. + :param refresh_token: The string that was returned when you created the token, + which enables you to extend its life. If you specify the `refresh_token` + grant type, this parameter is required. This parameter is not valid with + any other supported grant type. + :param scope: The scope of the token. Currently tokens are only issued for a + scope of FULL regardless of the value sent with the request. + :param username: The username that identifies the user. If you specify the `password` + grant type, this parameter is required. This parameter is not valid with + any other supported grant type. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/oauth2/token" @@ -1995,8 +2093,8 @@ def get_user( :param username: An identifier for the user. You can specify multiple usernames as a comma-separated list. If you omit this parameter, the API retrieves information about all users. - :param with_profile_uid: If true will return the User Profile ID for a user, - if any. + :param with_profile_uid: Determines whether to retrieve the user profile UID, + if it exists, for the users. """ __path_parts: t.Dict[str, str] if username not in SKIP_IN_PATH: @@ -2039,7 +2137,10 @@ def get_user_privileges( username: t.Optional[t.Union[None, str]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get user privileges. + Get user privileges. Get the security privileges for the logged in user. All + users can use this API, but only to determine their own privileges. To check + the privileges of other users, you must use the run as feature. To check whether + a user has a specific list of privileges, use the has privileges API. ``_ @@ -2160,28 +2261,30 @@ def grant_api_key( Grant an API key. Create an API key on behalf of another user. This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. The caller must have authentication - credentials (either an access token, or a username and password) for the user - on whose behalf the API key will be created. It is not possible to use this API - to create an API key without that user’s credentials. The user, for whom the - authentication credentials is provided, can optionally "run as" (impersonate) - another user. In this case, the API key will be created on behalf of the impersonated - user. This API is intended be used by applications that need to create and manage - API keys for end users, but cannot guarantee that those users have permission - to create API keys on their own behalf. A successful grant API key API call returns - a JSON structure that contains the API key, its unique id, and its name. If applicable, + credentials for the user on whose behalf the API key will be created. It is not + possible to use this API to create an API key without that user's credentials. + The supported user authentication credential types are: * username and password + * Elasticsearch access tokens * JWTs The user, for whom the authentication credentials + is provided, can optionally "run as" (impersonate) another user. In this case, + the API key will be created on behalf of the impersonated user. This API is intended + be used by applications that need to create and manage API keys for end users, + but cannot guarantee that those users have permission to create API keys on their + own behalf. The API keys are created by the Elasticsearch API key service, which + is automatically enabled. A successful grant API key API call returns a JSON + structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. By default, API keys never expire. You can specify expiration information when you create the API keys. ``_ - :param api_key: Defines the API key. + :param api_key: The API key. :param grant_type: The type of grant. Supported grant types are: `access_token`, `password`. - :param access_token: The user’s access token. If you specify the `access_token` + :param access_token: The user's access token. If you specify the `access_token` grant type, this parameter is required. It is not valid with other grant types. - :param password: The user’s password. If you specify the `password` grant type, + :param password: The user's password. If you specify the `password` grant type, this parameter is required. It is not valid with other grant types. :param run_as: The name of the user to be impersonated. :param username: The user name that identifies the user. If you specify the `password` @@ -2313,7 +2416,8 @@ def has_privileges( ) -> ObjectApiResponse[t.Any]: """ Check user privileges. Determine whether the specified user has a specified list - of privileges. + of privileges. All users can use this API, but only to determine their own privileges. + To check the privileges of other users, you must use the run as feature. ``_ @@ -2440,13 +2544,16 @@ def invalidate_api_key( key or grant API key APIs. Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically - deleted. The `manage_api_key` privilege allows deleting any API keys. The `manage_own_api_key` - only allows deleting API keys that are owned by the user. In addition, with the - `manage_own_api_key` privilege, an invalidation request must be issued in one - of the three formats: - Set the parameter `owner=true`. - Or, set both `username` - and `realm_name` to match the user’s identity. - Or, if the request is issued - by an API key, that is to say an API key invalidates itself, specify its ID in - the `ids` field. + deleted. To use this API, you must have at least the `manage_security`, `manage_api_key`, + or `manage_own_api_key` cluster privileges. The `manage_security` privilege allows + deleting any API key, including both REST and cross cluster API keys. The `manage_api_key` + privilege allows deleting any REST API key, but not cross cluster API keys. The + `manage_own_api_key` only allows deleting REST API keys that are owned by the + user. In addition, with the `manage_own_api_key` privilege, an invalidation request + must be issued in one of the three formats: - Set the parameter `owner=true`. + - Or, set both `username` and `realm_name` to match the user's identity. - Or, + if the request is issued by an API key, that is to say an API key invalidates + itself, specify its ID in the `ids` field. ``_ @@ -2455,14 +2562,15 @@ def invalidate_api_key( `name`, `realm_name`, or `username`. :param name: An API key name. This parameter cannot be used with any of `ids`, `realm_name` or `username`. - :param owner: Can be used to query API keys owned by the currently authenticated - user. The `realm_name` or `username` parameters cannot be specified when - this parameter is set to `true` as they are assumed to be the currently authenticated - ones. + :param owner: Query API keys owned by the currently authenticated user. The `realm_name` + or `username` parameters cannot be specified when this parameter is set to + `true` as they are assumed to be the currently authenticated ones. NOTE: + At least one of `ids`, `name`, `username`, and `realm_name` must be specified + if `owner` is `false`. :param realm_name: The name of an authentication realm. This parameter cannot be used with either `ids` or `name`, or when `owner` flag is set to `true`. :param username: The username of a user. This parameter cannot be used with either - `ids` or `name`, or when `owner` flag is set to `true`. + `ids` or `name` or when `owner` flag is set to `true`. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/api_key" @@ -2522,14 +2630,21 @@ def invalidate_token( longer be used. The time period is defined by the `xpack.security.authc.token.timeout` setting. The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once. If you want to invalidate one or - more access or refresh tokens immediately, use this invalidate token API. + more access or refresh tokens immediately, use this invalidate token API. NOTE: + While all parameters are optional, at least one of them is required. More specifically, + either one of `token` or `refresh_token` parameters is required. If none of these + two are specified, then `realm_name` and/or `username` need to be specified. ``_ - :param realm_name: - :param refresh_token: - :param token: - :param username: + :param realm_name: The name of an authentication realm. This parameter cannot + be used with either `refresh_token` or `token`. + :param refresh_token: A refresh token. This parameter cannot be used if any of + `refresh_token`, `realm_name`, or `username` are used. + :param token: An access token. This parameter cannot be used if any of `refresh_token`, + `realm_name`, or `username` are used. + :param username: The username of a user. This parameter cannot be used with either + `refresh_token` or `token`. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/oauth2/token" @@ -2806,7 +2921,20 @@ def put_privileges( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update application privileges. + Create or update application privileges. To use this API, you must have one of + the following privileges: * The `manage_security` cluster privilege (or a greater + privilege such as `all`). * The "Manage Application Privileges" global privilege + for the application being referenced in the request. Application names are formed + from a prefix, with an optional suffix that conform to the following rules: * + The prefix must begin with a lowercase ASCII letter. * The prefix must contain + only ASCII letters or digits. * The prefix must be at least 3 characters long. + * If the suffix exists, it must begin with either a dash `-` or `_`. * The suffix + cannot contain any of the following characters: `\\`, `/`, `*`, `?`, `"`, `<`, + `>`, `|`, `,`, `*`. * No part of the name can contain whitespace. Privilege names + must begin with a lowercase ASCII letter and must contain only ASCII letters + and digits along with the characters `_`, `-`, and `.`. Action names can contain + any number of printable ASCII characters and must contain at least one of the + following characters: `/`, `*`, `:`. ``_ @@ -2977,7 +3105,10 @@ def put_role( 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. :param remote_cluster: A list of remote cluster permissions entries. - :param remote_indices: A list of remote indices permissions entries. + :param remote_indices: A list of remote indices permissions entries. NOTE: Remote + indices are effective for remote clusters configured with the API key based + model. They have no effect for remote clusters configured with the certificate + based model. :param run_as: A list of users that the owners of this role can impersonate. *Note*: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will @@ -3072,21 +3203,45 @@ def put_role_mapping( that are granted to those users. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role - mapping files. This API does not create roles. Rather, it maps users to existing - roles. Roles can be created by using the create or update roles API or roles - files. + mapping files. NOTE: This API does not create roles. Rather, it maps users to + existing roles. Roles can be created by using the create or update roles API + or roles files. **Role templates** The most common use for role mappings is to + create a mapping from a known value on the user to a fixed role name. For example, + all users in the `cn=admin,dc=example,dc=com` LDAP group should be given the + superuser role in Elasticsearch. The `roles` field is used for this purpose. + For more complex needs, it is possible to use Mustache templates to dynamically + determine the names of the roles that should be granted to the user. The `role_templates` + field is used for this purpose. NOTE: To use role templates successfully, the + relevant scripting feature must be enabled. Otherwise, all attempts to create + a role mapping with role templates fail. All of the user fields that are available + in the role mapping rules are also available in the role templates. Thus it is + possible to assign a user to a role that reflects their username, their groups, + or the name of the realm to which they authenticated. By default a template is + evaluated to produce a single string that is the name of the role which should + be assigned to the user. If the format of the template is set to "json" then + the template is expected to produce a JSON string or an array of JSON strings + for the role names. ``_ - :param name: Role-mapping name - :param enabled: - :param metadata: + :param name: The distinct name that identifies the role mapping. The name is + used solely as an identifier to facilitate interaction via the API; it does + not affect the behavior of the mapping in any way. + :param enabled: Mappings that have `enabled` set to `false` are ignored when + role mapping is performed. + :param metadata: Additional metadata that helps define which roles are assigned + to each user. Within the metadata object, keys beginning with `_` are reserved + for system usage. :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. - :param role_templates: - :param roles: - :param rules: + :param role_templates: A list of Mustache templates that will be evaluated to + determine the roles names that should granted to the users that match the + role mapping rules. Exactly one of `roles` or `role_templates` must be specified. + :param roles: A list of role names that are granted to the users that match the + role mapping rules. Exactly one of `roles` or `role_templates` must be specified. + :param rules: The rules that determine which users should be matched by the mapping. + A rule is a logical condition that is expressed by using a JSON DSL. :param run_as: """ if name in SKIP_IN_PATH: @@ -3161,23 +3316,38 @@ def put_user( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update users. A password is required for adding a new user but is optional - when updating an existing user. To change a user’s password without updating - any other fields, use the change password API. + Create or update users. Add and update users in the native realm. A password + is required for adding a new user but is optional when updating an existing user. + To change a user's password without updating any other fields, use the change + password API. ``_ - :param username: The username of the User - :param email: - :param enabled: - :param full_name: - :param metadata: - :param password: - :param password_hash: - :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. - :param roles: + :param username: An identifier for the user. NOTE: Usernames must be at least + 1 and no more than 507 characters. They can contain alphanumeric characters + (a-z, A-Z, 0-9), spaces, punctuation, and printable symbols in the Basic + Latin (ASCII) block. Leading or trailing whitespace is not allowed. + :param email: The email of the user. + :param enabled: Specifies whether the user is enabled. + :param full_name: The full name of the user. + :param metadata: Arbitrary metadata that you want to associate with the user. + :param password: The user's password. Passwords must be at least 6 characters + long. When adding a user, one of `password` or `password_hash` is required. + When updating an existing user, the password is optional, so that other fields + on the user (such as their roles) may be updated without modifying the user's + password + :param password_hash: A hash of the user's password. This must be produced using + the same hashing algorithm as has been configured for password storage. For + more details, see the explanation of the `xpack.security.authc.password_hashing.algorithm` + setting in the user cache and password hash algorithm documentation. Using + this parameter allows the client to pre-hash the password for performance + and/or confidentiality reasons. The `password` parameter and the `password_hash` + parameter cannot be used in the same request. + :param refresh: Valid values are `true`, `false`, and `wait_for`. These values + have the same meaning as in the index API, but the default value for this + API is true. + :param roles: A set of roles the user has. The roles determine the user's access + permissions. To create a user without any roles, specify an empty list (`[]`). """ if username in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'username'") @@ -3261,7 +3431,12 @@ def query_api_keys( ) -> ObjectApiResponse[t.Any]: """ Find API keys with a query. Get a paginated list of API keys and their information. - You can optionally filter the results with a query. + You can optionally filter the results with a query. To use this API, you must + have at least the `manage_own_api_key` or the `read_security` cluster privileges. + If you have only the `manage_own_api_key` privilege, this API returns only the + API keys that you own. If you have the `read_security`, `manage_api_key`, or + greater privileges (including `manage_security`), this API returns all API keys + regardless of ownership. ``_ @@ -3277,30 +3452,39 @@ def query_api_keys( `terms`, `range`, `date_range`, `missing`, `cardinality`, `value_count`, `composite`, `filter`, and `filters`. Additionally, aggregations only run over the same subset of fields that query works with. - :param from_: Starting document offset. 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 from_: The starting document offset. 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 query: A query to filter which API keys to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following public information associated with an API key: `id`, `type`, `name`, `creation`, `expiration`, `invalidated`, `invalidation`, - `username`, `realm`, and `metadata`. - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: Other than `id`, all public fields of an API key are eligible for - sorting. In addition, sort can also be applied to the `_doc` field to sort - by index order. + `username`, `realm`, and `metadata`. NOTE: The queryable string values associated + with API keys are internally mapped as keywords. Consequently, if no `analyzer` + parameter is specified for a `match` query, then the provided match query + string is interpreted as a single keyword value. Such a match query is hence + equivalent to a `term` query. + :param search_after: The search after definition. + :param size: The number of hits to return. It must not be negative. The `size` + parameter can be set to `0`, in which case no API key matches are returned, + only the aggregation results. 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. Other than `id`, all public fields of an API + key are eligible for sorting. In addition, sort can also be applied to the + `_doc` field to sort by index order. :param typed_keys: Determines whether aggregation names are prefixed by their respective types in the response. :param with_limited_by: Return the snapshot of the owner user's role descriptors associated with the API key. An API key's actual permission is the intersection - of its assigned role descriptors and the owner user's role descriptors. - :param with_profile_uid: Determines whether to also retrieve the profile uid, - for the API key owner principal, if it exists. + of its assigned role descriptors and the owner user's role descriptors (effectively + limited by it). An API key cannot retrieve any API key’s limited-by role + descriptors (including itself) unless it has `manage_api_key` or higher privileges. + :param with_profile_uid: Determines whether to also retrieve the profile UID + for the API key owner principal. If it exists, the profile UID is returned + under the `profile_uid` response field for each API key. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/api_key" @@ -3387,26 +3571,30 @@ def query_role( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Find roles with a query. Get roles in a paginated manner. You can optionally - filter the results with a query. + Find roles with a query. Get roles in a paginated manner. The role management + APIs are generally the preferred way to manage roles, rather than using file-based + role management. The query roles API does not retrieve roles that are defined + in roles files, nor built-in ones. You can optionally filter the results with + a query. Also, the results can be paginated and sorted. ``_ - :param from_: Starting document offset. 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 from_: The starting document offset. 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 query: A query to filter which roles to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following information associated with roles: `name`, `description`, - `metadata`, `applications.application`, `applications.privileges`, `applications.resources`. - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: All public fields of a role are eligible for sorting. In addition, - sort can also be applied to the `_doc` field to sort by index order. + `metadata`, `applications.application`, `applications.privileges`, and `applications.resources`. + :param search_after: The search after definition. + :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`. + In addition, sort can also be applied to the `_doc` field to sort by index + order. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/role" @@ -3474,27 +3662,30 @@ def query_user( ) -> ObjectApiResponse[t.Any]: """ Find users with a query. Get information for users in a paginated manner. You - can optionally filter the results with a query. + can optionally filter the results with a query. NOTE: As opposed to the get user + API, built-in users are excluded from the result. This API is only for native + users. ``_ - :param from_: Starting document offset. 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 from_: The starting document offset. 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 query: A query to filter which users to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following information associated with user: `username`, - `roles`, `enabled` - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: Fields eligible for sorting are: username, roles, enabled In addition, - sort can also be applied to the `_doc` field to sort by index order. - :param with_profile_uid: If true will return the User Profile ID for the users - in the query result, if any. + `roles`, `enabled`, `full_name`, and `email`. + :param search_after: The search after definition + :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. Fields eligible for sorting are: `username`, + `roles`, `enabled`. In addition, sort can also be applied to the `_doc` field + to sort by index order. + :param with_profile_uid: Determines whether to retrieve the user profile UID, + if it exists, for the users. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/user" @@ -4034,38 +4225,44 @@ def update_api_key( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update an API key. Updates attributes of an existing API key. Users can only - update API keys that they created or that were granted to them. Use this API - to update API keys created by the create API Key or grant API Key APIs. If you - need to apply the same update to many API keys, you can use bulk update API Keys - to reduce overhead. It’s not possible to update expired API keys, or API keys - that have been invalidated by invalidate API Key. This API supports updates to - an API key’s access scope and metadata. The access scope of an API key is derived - from the `role_descriptors` you specify in the request, and a snapshot of the - owner user’s permissions at the time of the request. The snapshot of the owner’s - permissions is updated automatically on every call. If you don’t specify `role_descriptors` - in the request, a call to this API might still change the API key’s access scope. - This change can occur if the owner user’s permissions have changed since the - API key was created or last modified. To update another user’s API key, use the - `run_as` feature to submit a request on behalf of another user. IMPORTANT: It’s - not possible to use an API key as the authentication credential for this API. - To update an API key, the owner user’s credentials are required. + Update an API key. Update attributes of an existing API key. This API supports + updates to an API key's access scope, expiration, and metadata. To use this API, + you must have at least the `manage_own_api_key` cluster privilege. Users can + only update API keys that they created or that were granted to them. To update + another user’s API key, use the `run_as` feature to submit a request on behalf + of another user. IMPORTANT: It's not possible to use an API key as the authentication + credential for this API. The owner user’s credentials are required. Use this + API to update API keys created by the create API key or grant API Key APIs. If + you need to apply the same update to many API keys, you can use the bulk update + API keys API to reduce overhead. It's not possible to update expired API keys + or API keys that have been invalidated by the invalidate API key API. The access + scope of an API key is derived from the `role_descriptors` you specify in the + request and a snapshot of the owner user's permissions at the time of the request. + The snapshot of the owner's permissions is updated automatically on every call. + IMPORTANT: If you don't specify `role_descriptors` in the request, a call to + this API might still change the API key's access scope. This change can occur + if the owner user's permissions have changed since the API key was created or + last modified. ``_ :param id: The ID of the API key to update. - :param expiration: Expiration time for the API key. + :param expiration: The expiration time for the API key. By default, API keys + never expire. This property can be omitted to leave the expiration unchanged. :param metadata: Arbitrary metadata that you want to associate with the API key. - It supports nested data structure. Within the metadata object, keys beginning - with _ are reserved for system usage. - :param role_descriptors: An array of role descriptors for this API key. This - parameter is optional. When it is not specified or is an empty array, then - the API key will have a point in time snapshot of permissions of the authenticated - user. If you supply role descriptors then the resultant permissions would - be an intersection of API keys permissions and authenticated user’s permissions - thereby limiting the access scope for API keys. The structure of role descriptor - is the same as the request for create role API. For more details, see create - or update roles API. + It supports a nested data structure. Within the metadata object, keys beginning + with `_` are reserved for system usage. When specified, this value fully + replaces the metadata previously associated with the API key. + :param role_descriptors: The role descriptors to assign to this API key. The + API key's effective permissions are an intersection of its assigned privileges + and the point in time snapshot of permissions of the owner user. You can + assign new privileges by specifying them in this parameter. To remove assigned + privileges, you can supply an empty `role_descriptors` parameter, that is + to say, an empty object `{}`. If an API key has no assigned privileges, it + inherits the owner user's full permissions. The snapshot of the owner's permissions + is always updated, whether you supply the `role_descriptors` parameter or + not. The structure of a role descriptor is the same as the request for the + create API keys API. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -4206,10 +4403,12 @@ def update_settings( """ Update security index settings. Update the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of - settings are allowed to be modified, for example `index.auto_expand_replicas` - and `index.number_of_replicas`. If a specific index is not in use on the system - and settings are provided for it, the request will be rejected. This API does - not yet support configuring the settings for indices before they are in use. + settings are allowed to be modified. This includes `index.auto_expand_replicas` + and `index.number_of_replicas`. NOTE: If `index.auto_expand_replicas` is set, + `index.number_of_replicas` will be ignored during updates. If a specific index + is not in use on the system and settings are provided for it, the request will + be rejected. This API does not yet support configuring the settings for indices + before they are in use. ``_ diff --git a/elasticsearch/dsl/types.py b/elasticsearch/dsl/types.py index ce639c4ed..012defa9a 100644 --- a/elasticsearch/dsl/types.py +++ b/elasticsearch/dsl/types.py @@ -5630,8 +5630,8 @@ class RateAggregate(AttrDict[Any]): class Retries(AttrDict[Any]): """ - :arg bulk: (required) - :arg search: (required) + :arg bulk: (required) The number of bulk actions retried. + :arg search: (required) The number of search actions retried. """ bulk: int