A glowing cloud database connects users, files, analytics dashboards, and data layers through digital streams.
Azure Cosmos DB throughput buckets are now generally available. They give administrators a way to stop one noisy workload from eating the whole container. It's a small feature, but it addresses a very common shared-database headache.

A glowing cloud database connects users, files, analytics dashboards, and data layers through digital streams. What Microsoft announced​

Microsoft announced general availability of throughput buckets in Azure Cosmos DB for NoSQL. The post is dated November 17, 2026. The feature sets workload-level throughput limits inside a shared container. Background work gets a boundary without a separate copy of your data.

The problem is familiar. One container often serves user-facing queries, requests from different customer tiers, and background jobs such as bulk imports, migrations or exploratory queries. Without workload-level controls they all compete for the same request units per second (RU/s). Any of them can be throttled during contention. Raising the container's RU/s adds capacity but puts no boundary around any one workload. Splitting workloads into separate containers brings data synchronization and extra application logic.

How throughput buckets work​

Requests are assigned to a bucket, and each bucket caps the percentage of container throughput it can consume. Cosmos DB enforces the limit on the bucket's combined traffic, so individual application instances don't need to limit themselves.

The key point is that these are caps, not reservations. Microsoft's documentation says throughput isn't reserved for any bucket and remains shared across all workloads. In practice:

  • An idle bucket does not hold capacity aside.
  • Capping one bucket does not guarantee the remaining capacity to another workload.
  • Buckets limit how much a workload can take. They do not promise a workload a floor.

When a bucket hits its cap, Cosmos DB throttles subsequent requests with HTTP 429 and substatus 3212. That substatus separates bucket-limit throttling from other 429 causes.

Setting it up in the Azure portal​

In the Azure portal, open the Cosmos DB account and select Data Explorer. Then select the container, open Scale & Settings, and open Throughput Buckets. Change the buckets you want from Inactive to Active. Then set each bucket's maximum throughput percentage and save.

A container supports up to five buckets, with numeric IDs 1 through 5. You can't give them custom service-side names.

Assigning requests to buckets​

Once buckets are active, you can assign a bucket per request, per SDK client, or through a container default.

  • Per request: This suits one service that handles several tenant tiers. In the .NET SDK sample, query request options carry a ThroughputBucket value. Setting it to 2 puts a query under bucket 2's cap. A null value leaves it unassigned.
  • Per client: Set ThroughputBucket in the client options when creating the client. Microsoft's example creates a bulk-ingestion client with bulk execution enabled and bucket 1. For supported non-bulk operations, an explicit request-level bucket takes precedence over the client's.
  • Container default: This applies when a request arrives with no assignment. Without an active default, unassigned requests have no bucket-specific cap.

The announcement's example is a marketplace called Contoso. Bulk jobs go in bucket 1 at a 10% cap. Standard-tier searches go in bucket 2 at 40%. Premium searches are sent without a bucket. They therefore have no bucket-specific ceiling below the container's limit. The announcement separately describes activating bucket 5 at 15% as the container default for unassigned traffic. These figures are illustrations, not recommended settings.

Where it applies, and where it doesn't​

  • API: Throughput buckets are for Azure Cosmos DB for NoSQL.
  • Unsupported: They are not supported on serverless accounts or containers using shared database throughput.
  • Change rate: Bucket configurations can be changed once every 10 minutes. More frequent updates get HTTP 429 with substatus 3213. Keep that in mind if you automate tuning.
  • Deleted buckets: Requests that use a deleted but valid bucket ID fall back to the container's overall throughput. IDs outside 1 through 5 are invalid. Check which callers use a bucket before you remove it.
  • Data Explorer: Queries run in bucket 1 when it is configured. Setting bucket 1's cap limits the impact of interactive investigations on production.
  • Change feed: For change-feed processing, source reads and destination writes are limited separately. Projection writes can go in a bucket on the destination container.

Monitoring and tuning​

In the account's Metrics pane, filter to the database and container. Then use these measures:

  1. Select Total Requests and split by ThroughputBucket to compare request counts.
  2. Select Total Request Units and split by ThroughputBucket to compare RU consumption.
  3. Filter request metrics by StatusCode = 429 to find throttled traffic.
  4. Capture substatus 3212 in application diagnostics to identify a bucket cap specifically.

Cosmos DB SDKs can retry throttled requests, so also monitor end-to-end latency and failures returned after retries. A raw 429 count may overstate or understate what users actually experience.

Analysis: what to watch for​

The practical benefit is that you can govern noisy background work without splitting data that belongs together. It is also a cheaper first step than raising container RU/s to absorb a bulk job. Three cautions apply:

  • It isn't a guarantee for uncapped traffic. Putting standard-tier users at 40% does not promise premium users any specific RU/s. If the container is under-provisioned overall, premium traffic can still suffer. This follows from the documented shared-capacity behavior. It is my inference rather than a Microsoft statement.
  • Unassigned traffic is easy to forget. Older services and ad hoc tools may not specify a bucket. A default bucket is the way to cap them.
  • Throttling shifts rather than disappears. A capped bulk job will see 429s sooner. That is the intended behavior, but job runtimes will stretch. Microsoft suggests starting with one workload, such as a supplier import or migration. Compare application latency and job progress before tuning the cap.

A documentation wrinkle​

Some Microsoft Learn pages still carry preview labels. One Learn page describes throughput buckets as preview, and a Spark connector page mentions registering for a preview feature. The dated Cosmos DB blog post says the feature is generally available. Learn pages often lag a launch, but I could not confirm from the evidence available whether any preview registration step still applies. Check the current Learn documentation for your subscription before you plan a rollout.

Bottom line​

Throughput buckets are a straightforward addition for teams running mixed workloads on provisioned NoSQL containers. If your container hosts bulk jobs, tiered tenants or exploratory queries next to live traffic, test a single capped bucket. Then watch latency and 3212 responses before you widen the approach.

 

References

  1. (Launched) Generally Available: Throughput buckets in Azure Cosmos DB Azure Updates 2026-11-17T23:44:26Z
  2. Generally available: Control shared workloads with throughput buckets in Azure Cosmos DB - Azure Cosmos DB Blog devblogs.microsoft.com
  3. Throughput Buckets (Preview) - Azure Cosmos DB learn.microsoft.com