Skip to content

Commit 613b587

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #1797 from richagaur/richagaur/throughput-buckets
Richagaur/throughput buckets
2 parents 9bd930f + d8a301b commit 613b587

3 files changed

Lines changed: 207 additions & 0 deletions

File tree

‎articles/cosmos-db/nosql/TOC.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -316,6 +316,12 @@
316316
href: ../priority-based-execution.md
317317
- name: Priority-based execution FAQ
318318
href: ../priority-based-execution-faq.yml
319+
- name: Throughput buckets (preview)
320+
items:
321+
- name: Throughput buckets overview
322+
href: throughput-buckets.md
323+
- name: Throughput buckets FAQ
324+
href: throughput-buckets-faq.yml
319325
- name: Change feed
320326
items:
321327
- name: Change feed overview

‎articles/cosmos-db/nosql/throughput-buckets-faq.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
### YamlMime:FAQ
2+
metadata:
3+
title: Frequently asked questions on Throughput buckets in Azure Cosmos DB
4+
titleSuffix: Azure Cosmos DB
5+
description: Frequently asked questions on Throughput buckets in Azure Cosmos DB
6+
author: richagaur
7+
ms.author: richagaur
8+
ms.service: azure-cosmos-db
9+
ms.topic: conceptual
10+
ms.date: 03/31/2025
11+
12+
title: Frequently asked questions on throughput buckets in Azure Cosmos DB
13+
14+
summary: |
15+
[!INCLUDE[NoSQL](../includes/appliesto-nosql.md)]
16+
17+
Throughput buckets in Azure Cosmos DB allow users to control the throughput available for different workloads within a container. By configuring buckets and setting a maximum throughput allocation, users can ensure workload isolation. If a bucket exceeds its assigned throughput limit, subsequent requests are throttled to prevent impact on other workloads.
18+
19+
sections:
20+
- name: General
21+
questions:
22+
- question: |
23+
How many throughput buckets can be configured per container?
24+
answer: |
25+
You can configure up to five (5) throughput buckets per container.
26+
- question: |
27+
Can I assign custom names to throughput buckets?
28+
answer: |
29+
No, throughput buckets can't be named. They're automatically assigned an ID ranging from 1 to 5.
30+
- question: |
31+
What happens if a bucket exceeds its configured maximum throughput?
32+
answer: |
33+
Subsequent requests sent to that bucket receive an HTTP 429 status code with substatus code 3212.
34+
- question: |
35+
What happens if I delete an existing bucket?
36+
answer: |
37+
Requests sent with a deleted bucket ID (1-5) won't fail, however they consume throughput from the overall container.
38+
- question: |
39+
What if I assign a bucket ID lower than 1 or higher than 5 to a request?
40+
answer: |
41+
Requests with an invalid bucket ID (less than 1 or greater than 5) results in an error, as only bucket IDs 1 to 5 are valid.
42+
- question: |
43+
Is there any minimum throughput limit for a throughput buckets?
44+
answer: |
45+
There's no minimum limit for throughput buckets. Throughput isn't reserved for any bucket, and the total throughput of the container is shared among all buckets.
46+
- question: |
47+
How often can throughput buckets be modified?
48+
answer: |
49+
Throughput bucket configurations can be changed once every 10 minutes, otherwise the request is throttled with an HTTP 429 status code and substatus code 3213.
50+
51+
additionalContent: |
52+
53+
## Next steps
54+
55+
* Learn more about [Throughput buckets](throughput-buckets.md)

‎articles/cosmos-db/nosql/throughput-buckets.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: 'Azure Cosmos DB: Throughput buckets'
3+
description: Learn how you can control throughput usage for different workloads by creating buckets in Azure Cosmos DB.
4+
author: richagaur
5+
ms.service: azure-cosmos-db
6+
ms.subservice: nosql
7+
ms.topic: conceptual
8+
ms.author: richagaur
9+
ms.date: 03/31/2025
10+
---
11+
12+
# Throughput buckets in Azure Cosmos DB
13+
14+
[!INCLUDE[NoSQL](../includes/appliesto-nosql.md)]
15+
16+
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, ensuring better isolation and governance of resource usage for multiple workloads.
17+
18+
#### Common Use Cases
19+
20+
- Multitenant workloads managed by Independent Software Vendors (ISVs)
21+
- Bulk execution in ETL jobs
22+
- Data ingestion and migration processes
23+
- Execution of stored procedures
24+
- Change feed processing
25+
26+
### How Throughput buckets Work
27+
28+
Throughput buckets 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.
29+
30+
- Each bucket has a maximum throughput percentage, capping the fraction of the container’s total throughput that it can consume.
31+
- Requests assigned to a bucket can consume throughput only up to this limit.
32+
- If the bucket exceeds its configured limit, subsequent requests are throttled.
33+
- This mechanism helps in preventing resource contention, ensuring that no single workload consumes excessive throughput and impacts others.
34+
35+
> [!Note]
36+
> Requests not assigned to a bucket will consume throughput from the container without restrictions.
37+
38+
### Configuring Throughput buckets
39+
40+
To set up throughput buckets in the Azure portal:
41+
42+
1. Open **Data Explorer** and navigate to the **Scale & Settings** pane of your container.
43+
2. Locate the **Throughput Buckets** tab.
44+
3. Enable the desired throughput bucket by toggling it from "Inactive" to "Active."
45+
4. Set the desired maximum throughput percentage for enabled buckets (up to five buckets per container).
46+
47+
### Using Throughput buckets in SDK requests
48+
49+
To assign a request to a specific bucket, use RequestOptions in the SDK.
50+
51+
#### [.NET SDK v3](#tab/net-v3)
52+
53+
```csharp
54+
using Microsoft.Azure.Cosmos;
55+
56+
string itemId = "<id>";
57+
PartitionKey partitionKey = new PartitionKey("<pkey>");
58+
59+
// Define request options with Throughput Bucket 1 for read operation
60+
ItemRequestOptions readRequestOptions = new ItemRequestOptions{ThroughputBucket = 1};
61+
62+
// Send read request using Bucket ID 1
63+
ItemResponse<Product> readResponse = await container.ReadItemAsync<Product>(
64+
itemId,
65+
partitionKey,
66+
readRequestOptions);
67+
68+
Product product = readResponse.Resource;
69+
70+
// Define request options with Throughput Bucket 2 for update operation
71+
ItemRequestOptions updateRequestOptions = new ItemRequestOptions{ThroughputBucket = 2};
72+
73+
// Send update request using Bucket ID 2
74+
ItemResponse<Product> updateResponse = await container.ReplaceItemAsync(
75+
product,
76+
itemId,
77+
partitionKey,
78+
updateRequestOptions);
79+
```
80+
81+
To apply a throughput bucket to all requests from a client application, use ClientOptions in the SDK.
82+
83+
#### [.NET SDK v3](#tab/net-v3-bulk)
84+
85+
```csharp
86+
using Microsoft.Azure.Cosmos;
87+
using Azure.Identity;
88+
89+
var credential = new DefaultAzureCredential();
90+
91+
// Create CosmosClient with Bulk Execution and Throughput Bucket 1
92+
CosmosClient cosmosClient = new CosmosClientBuilder("<endpointUri>", credential)
93+
.WithBulkExecution(true) // Enable bulk execution
94+
.WithThroughputBucket(1) // Assign throughput bucket 1 to all requests
95+
.Build();
96+
97+
// Get container reference
98+
Container container = cosmosClient.GetContainer("<DatabaseId>", "<ContainerId>");
99+
100+
// Prepare bulk operations
101+
List<Task> tasks = new List<Task>();
102+
for (int i = 1; i <= 10; i++)
103+
{
104+
var item = new
105+
{
106+
id = Guid.NewGuid().ToString(),
107+
partitionKey = $"pkey-{i}",
108+
name = $"Item-{i}",
109+
timestamp = DateTime.UtcNow
110+
};
111+
112+
tasks.Add(container.CreateItemAsync(item, new PartitionKey(item.partitionKey)));
113+
}
114+
115+
// Execute bulk insertions with throughput bucket 1
116+
await Task.WhenAll(tasks);
117+
118+
//Read item with throughput bucket 1
119+
ItemResponse<Product> response = await container.ReadItemAsync<Product>(partitionKey: new PartitionKey("pkey1"), id: "id1");
120+
121+
```
122+
123+
> [!Note]
124+
> If bulk execution is enabled, a throughput bucket can't be assigned to an individual request using the RequestOptions.
125+
126+
### Bucket behavior in Data Explorer
127+
128+
- If **Bucket 1** is configured, all requests from Data Explorer use this bucket and adhere to its throughput limits.
129+
- If **Bucket 1** isn't configured, requests utilize the container’s full available throughput.
130+
131+
### Monitoring Throughput buckets
132+
133+
You can track bucket usage in the Azure portal:
134+
135+
- **Total Requests (preview)**: View the number of requests per bucket by splitting the metric by ThroughputBucket.
136+
137+
- **Total Request Units (preview)**: Monitor RU/s consumption per bucket by splitting the metric by ThroughputBucket.
138+
139+
### Limitations
140+
141+
- Not supported for containers in a Shared Throughput Database.
142+
- Not available for Serverless Cosmos DB accounts.
143+
- Requests assigned to a bucket can't utilize Burst Capacity.
144+
145+
### Next Steps
146+
- Read the [Frequently asked questions](throughput-buckets-faq.yml) on Throughput buckets.

0 commit comments

Comments
 (0)