Skip to content

Cosmos: GA throughput buckets #48838

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Simon Moreno (simorenoh) merged 5 commits into from
Sep 1, 2026
Merged

Cosmos: GA throughput buckets #48838

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4ccc00f
Update CHANGELOG.md
simorenoh Sep 1, 2026
bc6032e
GA throughput buckets
simorenoh Sep 1, 2026
9d21d9b
Update CHANGELOG.md
simorenoh Sep 1, 2026
9a12dd3
Update CHANGELOG.md
simorenoh Sep 1, 2026
17a3c17
Merge branch 'main' into changelog-update-cosmos
simorenoh Sep 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion sdk/cosmos/azure-cosmos/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,15 @@
> [!IMPORTANT]
> We strongly recommend that customers use at least version 4.16.3 of `azure-cosmos`.
Comment thread
simorenoh marked this conversation as resolved.

### 4.16.4 (2026-09-01)
### 4.16.4 (2026-09-02)

#### Bugs Fixed
* Fixed regression with handling of v1 legacy containers when passing `{}` as a partition key. `{}` and `NonePartitionKeyValue` now both resolve to the `Undefined` effective partition key. See [PR 48422](https://github.com/Azure/azure-sdk-for-python/pull/48422)
* Fixed the same `TypeError` on system key (migrated) containers, where a missing partition key value resolves to `_Empty` instead of `Undefined`. It now maps to the minimum effective partition key. See [PR 48422](https://github.com/Azure/azure-sdk-for-python/pull/48422)

#### Other Changes
* Marked the Throughput Buckets feature as GA. See [48838](https://github.com/Azure/azure-sdk-for-python/pull/48838).

### 4.16.3 (2026-07-29)

#### Bugs Fixed
Expand Down
2 changes: 1 addition & 1 deletion sdk/cosmos/azure-cosmos/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -963,7 +963,7 @@ may have additional latencies associated with searching in the service.

You can find our sync samples [here][cosmos_index_sample] and our async samples [here][cosmos_index_sample_async] as well for additional guidance.

### Public Preview - Throughput Buckets
### Throughput Buckets
When multiple workloads share the same Azure Cosmos DB container, resource contention can lead to throttling, increased latency, and potential business impact.
To address this, Cosmos DB allows you to allocate throughput buckets, which help manage resource consumption for workloads sharing a Cosmos DB container by limiting the maximum throughput a bucket can consume.
However, throughput isn't reserved for any bucket, it remains shared across all workloads.
Expand Down
20 changes: 10 additions & 10 deletions sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,7 @@ async def create_item(
:keyword int retry_write: Indicates how many times the SDK should automatically retry this write operation, even if
the operation is not guaranteed to be idempotent. This should only be enabled if the application can
tolerate such risks or has logic to safely detect and handle duplicate operations. Default is None (no retries).
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword Union[bool, dict[str, Any]] availability_strategy: Enables an availability strategy by using cross-region request hedging.
Can be True (use client config if present, otherwise use default values: threshold_ms=500, threshold_steps_ms=100),
False (disable hedging even if client has it enabled),
Expand Down Expand Up @@ -350,7 +350,7 @@ async def read_item(
:keyword Literal["High", "Low"] priority: Priority based execution allows users to set a priority for each
request. Once the user has reached their provisioned throughput, low priority requests are throttled
before high priority requests start getting throttled. Feature must first be enabled at the account level.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword Sequence[str] excluded_locations: Excluded locations to be skipped from preferred locations. The locations
in this list are specified as the names of the azure Cosmos locations like, 'West US', 'East US' and so on.
If all preferred locations were excluded, primary/hub location will be used.
Expand Down Expand Up @@ -424,7 +424,7 @@ def read_all_items(
:keyword Literal["High", "Low"] priority: Priority based execution allows users to set a priority for each
request. Once the user has reached their provisioned throughput, low priority requests are throttled
before high priority requests start getting throttled. Feature must first be enabled at the account level.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword Sequence[str] excluded_locations: Excluded locations to be skipped from preferred locations. The locations
in this list are specified as the names of the azure Cosmos locations like, 'West US', 'East US' and so on.
If all preferred locations were excluded, primary/hub location will be used.
Expand Down Expand Up @@ -498,7 +498,7 @@ async def read_items(
:keyword Literal["High", "Low"] priority: Priority based execution allows users to set a priority for each
request. Once the user has reached their provisioned throughput, low priority requests are throttled
before high priority requests start getting throttled. Feature must first be enabled at the account level.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword Union[bool, dict[str, Any]] availability_strategy: Enables an availability strategy by using cross-region request hedging.
Can be True (use client config if present, otherwise use default values: threshold_ms=500, threshold_steps_ms=100),
False (disable hedging even if client has it enabled),
Expand Down Expand Up @@ -1290,7 +1290,7 @@ async def upsert_item(
:keyword int retry_write: Indicates how many times the SDK should automatically retry this write operation, even if
the operation is not guaranteed to be idempotent. This should only be enabled if the application can
tolerate such risks or has logic to safely detect and handle duplicate operations. Default is None (no retries).
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword Sequence[str] excluded_locations: Excluded locations to be skipped from preferred locations. The locations
in this list are specified as the names of the azure Cosmos locations like, 'West US', 'East US' and so on.
If all preferred locations were excluded, primary/hub location will be used.
Expand Down Expand Up @@ -1429,7 +1429,7 @@ async def replace_item(
:keyword int retry_write: Indicates how many times the SDK should automatically retry this write operation, even if
the operation is not guaranteed to be idempotent. This should only be enabled if the application can
tolerate such risks or has logic to safely detect and handle duplicate operations. Default is None (no retries).
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword Sequence[str] excluded_locations: Excluded locations to be skipped from preferred locations. The locations
in this list are specified as the names of the azure Cosmos locations like, 'West US', 'East US' and so on.
If all preferred locations were excluded, primary/hub location will be used.
Expand Down Expand Up @@ -1530,7 +1530,7 @@ async def patch_item(
:keyword int retry_write: Indicates how many times the SDK should automatically retry this write operation, even if
the operation is not guaranteed to be idempotent. This should only be enabled if the application can
tolerate such risks or has logic to safely detect and handle duplicate operations. Default is None (no retries).
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword Sequence[str] excluded_locations: Excluded locations to be skipped from preferred locations. The locations
in this list are specified as the names of the azure Cosmos locations like, 'West US', 'East US' and so on.
If all preferred locations were excluded, primary/hub location will be used.
Expand Down Expand Up @@ -1628,7 +1628,7 @@ async def delete_item(
tolerate such risks or has logic to safely detect and handle duplicate operations. Default is None (no retries).
:keyword response_hook: A callable invoked with the response metadata.
:paramtype response_hook: Callable[[Mapping[str, str], None], None]
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword Union[bool, dict[str, Any]] availability_strategy: Enables an availability strategy by using cross-region request hedging.
Can be True (use client config if present, otherwise use default values: threshold_ms=500, threshold_steps_ms=100),
False (disable hedging even if client has it enabled),
Expand Down Expand Up @@ -1907,7 +1907,7 @@ async def delete_all_items_by_partition_key(
If all preferred locations were excluded, primary/hub location will be used.
This excluded_location will override existing excluded_locations in client level.
:keyword Callable response_hook: A callable invoked with the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:rtype: None
"""
etag = kwargs.get('etag')
Expand Down Expand Up @@ -1978,7 +1978,7 @@ async def execute_item_batch(
:keyword int retry_write: Indicates how many times the SDK should automatically retry this write operation, even if
the operation is not guaranteed to be idempotent. This should only be enabled if the application can
tolerate such risks or has logic to safely detect and handle duplicate operations. Default is None (no retries).
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:returns: A CosmosList representing the items after the batch operations went through.
:keyword Union[bool, dict[str, Any]] availability_strategy: Enables an availability strategy by using cross-region request hedging.
Can be True (use client config if present, otherwise use default values: threshold_ms=500, threshold_steps_ms=100),
Expand Down
20 changes: 10 additions & 10 deletions sdk/cosmos/azure-cosmos/azure/cosmos/aio/_cosmos_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ class CosmosClient: # pylint: disable=client-accepts-api-version-keyword
level (to log all requests) or at a single request level. Requests will be logged at INFO level.
:keyword bool no_response_on_write: Indicates whether service should be instructed to skip sending
response payloads for write operations on items by default unless specified differently per operation.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword str user_agent_suffix: Allows user agent suffix to be specified when creating client
:keyword Union[bool, dict[str, Any]] availability_strategy:
Enables an availability strategy by using cross-region request hedging.
Expand Down Expand Up @@ -300,7 +300,7 @@ async def create_database(
:keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
:keyword Callable[[dict[str, str], dict[str, Any]], None] response_hook: A callable invoked with
the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword bool return_properties: Specifies whether to return either a DatabaseProxy
or a Tuple containing a DatabaseProxy and the associated database properties.
:raises ~azure.cosmos.exceptions.CosmosResourceExistsError: Database with the given ID already exists.
Expand Down Expand Up @@ -340,7 +340,7 @@ async def create_database(
:keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
:keyword Callable[[dict[str, str], dict[str, Any]], None] response_hook: A callable invoked with
the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword bool return_properties: Specifies whether to return either a DatabaseProxy
or a Tuple containing a DatabaseProxy and the associated database properties.
:raises ~azure.cosmos.exceptions.CosmosResourceExistsError: Database with the given ID already exists.
Expand Down Expand Up @@ -375,7 +375,7 @@ async def create_database( # pylint:disable=docstring-should-be-keyword
:keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
:keyword Callable[[dict[str, str], dict[str, Any]], None] response_hook: A callable invoked with
the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword bool return_properties: Specifies whether to return either a DatabaseProxy
or a Tuple containing a DatabaseProxy and the associated database properties.
:raises ~azure.cosmos.exceptions.CosmosResourceExistsError: Database with the given ID already exists.
Expand Down Expand Up @@ -456,7 +456,7 @@ async def create_database_if_not_exists( # pylint: disable=redefined-builtin
:keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
:keyword Callable[[dict[str, str], dict[str, Any]], None] response_hook: A callable invoked with
the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword bool return_properties: Specifies whether to return either a DatabaseProxy
or a Tuple containing a DatabaseProxy and the associated database properties.
:raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The database read or creation failed.
Expand Down Expand Up @@ -492,7 +492,7 @@ async def create_database_if_not_exists( # pylint: disable=redefined-builtin
:keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
:keyword Callable[[dict[str, str], dict[str, Any]], None] response_hook: A callable invoked with
the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword bool return_properties: Specifies whether to return either a DatabaseProxy
or a Tuple containing a DatabaseProxy and the associated database properties.
:raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The database read or creation failed.
Expand Down Expand Up @@ -523,7 +523,7 @@ async def create_database_if_not_exists( # pylint:disable=docstring-should-be-ke
:keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
:keyword Callable[[dict[str, str], dict[str, Any]], None] response_hook: A callable invoked with
the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:keyword bool return_properties: Specifies whether to return either a DatabaseProxy
or a Tuple containing a DatabaseProxy and the associated database properties.
:raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The database read or creation failed.
Expand Down Expand Up @@ -605,7 +605,7 @@ def list_databases(
:keyword str session_token: Token for use with Session consistency.
:keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
:keyword response_hook: A callable invoked with the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:paramtype response_hook: Callable[[Mapping[str, Any]], None]
:returns: An AsyncItemPaged of database properties (dicts).
:rtype: AsyncItemPaged[dict[str, str]]
Expand Down Expand Up @@ -651,7 +651,7 @@ def query_databases(
:keyword str session_token: Token for use with Session consistency.
:keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
:keyword response_hook: A callable invoked with the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:paramtype response_hook: Callable[[Mapping[str, Any]], None]
:returns: An AsyncItemPaged of database properties (dicts).
:rtype: AsyncItemPaged[dict[str, str]]
Expand Down Expand Up @@ -695,7 +695,7 @@ async def delete_database(
:type database: Union[str, ~azure.cosmos.DatabaseProxy, dict[str, Any]]
:keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request.
:keyword response_hook: A callable invoked with the response metadata.
:keyword int throughput_bucket: The desired throughput bucket for the client
:keyword int throughput_bucket: The desired throughput bucket for the client.
:paramtype response_hook: Callable[[Mapping[str, Any]], None]
:raises ~azure.cosmos.exceptions.CosmosHttpResponseError: If the database couldn't be deleted.
:rtype: None
Expand Down
Loading
Loading