Imagine your application is processing customer checkouts in real-time, while a background process synchronizes data for reporting. Suddenly, the seamless user experience falters because the sync job consumes more RU/s than anticipated. 

Many teams face a common challenge: multiple workloads share the same container resources, yet each has different performance requirements. 

We’re excited to introduce the public preview of Throughput Buckets in Azure Cosmos DB for NoSQL—a new solution designed to address this challenge. 

Introducing Throughput Buckets 

Throughput Buckets allow you to set a maximum RU/s cap for specific workloads, giving you precise control over how different operations consume the throughput of a shared container. 

Here’s how it works: 

• You define buckets numbered from one to five for different workloads (e.g., “checkout”, “reporting”, “sync”). 

• You assign these buckets a maximum RU/s limit—expressed as a percentage of the container’s total provisioned throughput 

• You tag requests with a bucket name using a SDK property RequestOptions or ClientOptions. 

• Cosmos DB enforces the RU/s cap on a bucket when the usage increased beyond the configured limit. 

This means high-throughput background tasks like data analytics or scheduled updates can’t unintentionally starve your critical user-facing requests. 

And notably, buckets do not reserve RU/s. There are no hard partitions. It’s all about maximum usage caps, not minimum guarantees. 

And the best part? You don’t have to restructure your data model. There’s no need to split workloads across containers. Just tag your requests and go. 

How to Use Throughput Buckets 

Using buckets is simple. You apply the bucket at the request level: 

using Microsoft.Azure.Cosmos;using Microsoft.Azure.Cosmos;

String itemId = "<id>";
PartitionKey partitionKey = new PartitionKey("<pkey>");

// Define request options with Throughput Bucket 1 for read operation
ItemRequestOptions readRequestOptions = new ItemRequestOptions{ThroughputBucket = 1};

// Send read request using Bucket ID 1
ItemResponse<Product> readResponse = await container.ReadItemAsync<Product>(itemId,partitionKey,readRequestOptions);

Observability 

Request Volume 

You can monitor the request volume of each bucket using “Total Request (preview)” metric in Azure portal. 

Throughput Consumption

 You can monitor the throughput consumption of each bucket using “Total Request Units (preview)” metric in Azure portal. 

When Should You Use This? 

Throughput Buckets are ideal for: 

• Keep critical APIs responsive during high load period. 

• Isolating workloads in a shared container. 

• Preventing noisy neighbor issues. 

• Support differentiated service tiers in multi-tenant apps. 

• Run batch workloads safely alongside real-time ones. 

Whether you’re running an e-commerce app, analytics platform, or a SaaS offering with varying customer profiles, throughput buckets give you the flexibility to protect what matters—without adding operational complexity. 

Getting Started 

To try Throughput Buckets during public preview: 

1. Go to the Azure Portal 

1. Navigate to your subscription 

1. Under Preview Features, search for “Throughput buckets” 

1. Register the feature for your subscription 

Once registered, you can start using buckets on provisioned throughput containers in Azure Cosmos DB for NoSQL using supported SDKs or REST API. 

Next Steps 

Visit our official documentation for more information. 

If you have feedback or scenarios to share, please create an issue in this repository to reach out to us.  

We want to know how you are using it, what works well, and what can be improved. Your feedback will help with future enhancements. We look forward to seeing how you use Throughput Buckets to optimize your workloads and build more resilient, responsive apps with Azure Cosmos DB. 

Leave a review 

Tell us about your Azure Cosmos DB experience! Leave a review on PeerSpot and we’ll gift you $50. Get started here. 

About Azure Cosmos DB 

Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data. 

To stay in the loop on Azure Cosmos DB updates, follow us on X, YouTube, and LinkedIn.