Bulk Support
← Back to DP-420 Terminology Reference
Category: Client Connectivity & SDK
Summary: SDK feature optimized for loading/updating large volumes of items across many partitions.
Overview
Bulk support (Bulk executor / SDK bulk mode) is an SDK feature optimized for efficiently loading or updating large volumes of items across many different partition keys, by automatically grouping and parallelizing requests to maximize throughput utilization, rather than sending items one at a time. It has largely superseded the older bulkImport stored procedure pattern (which returned a BulkImportResponse per invocation) for most modern bulk-loading scenarios.
The benefit is primarily: !!! RU is same !!!
- fewer network round trips
- better client-side efficiency
- higher throughput
- faster completion of large batches
| Scenario | Bulk OFF | Bulk ON | | -------------------- | ----------------- | --------------- | | Single document CRUD | Same | Same | | 100 documents | Small difference | Slightly faster | | 100,000 documents | Noticeably slower | Much faster | | ETL / Migration | Not optimal | Recommended | | RU consumption | Similar | Similar | | Throughput achieved | Lower | Higher |
//Old
//client.ConnectionPolicy.RetryOptions.MaxRetryWaitTimeInSeconds = 0;
//client.ConnectionPolicy.RetryOptions.MaxRetryAttemptsOnThrottledRequests = 0;
//New
//new CosmosClient(
// connectionString,
// new CosmosClientOptions
// {
// AllowBulkExecution = true
// });
| Feature | Retry owner |
| ------------------------- | ------------------------------ |
| BulkExecutor library | BulkExecutor (SDK retries = 0) |
| AllowBulkExecution = true | Cosmos SDK |
| Normal operations | Cosmos SDK |
public CosmosDbService(string connectionString, CosmosClientOptions? options = null)
{
var clientOptions = options ?? new CosmosClientOptions
{
ApplicationName = "EmailConsoleApp",
ConnectionMode = ConnectionMode.Direct,
MaxRetryAttemptsOnRateLimitedRequests = 30, // Default is 9
MaxRetryWaitTimeOnRateLimitedRequests = TimeSpan.FromSeconds(60), // Default is 30s
AllowBulkExecution = true, // Optimizes bulk operations and internal micro-batching
SerializerOptions = new CosmosSerializationOptions
{
PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
}
};
...
var tasks = emailList.Select(async email =>
{
await semaphore.WaitAsync();
try
{
....
await Task.WhenAll(tasks);
return (successCount, failedCount, totalRu, transferredItems.ToList());
}
More Info & Links
DP-420 Style Practice Questions
Q1. What is bulk support in the Azure Cosmos DB SDK primarily optimized for?
- A. Efficiently loading or updating large volumes of items across many partition keys
- B. Executing a single atomic transaction within one logical partition
- C. Reducing the number of containers needed
- D. Enabling multi-region writes
Q2. How does bulk mode typically achieve higher throughput than sending requests one at a time?
- A. By automatically grouping and parallelizing requests across partitions
- B. By disabling indexing on the container
- C. By using only gateway mode
- D. By reducing the RU/s available to other operations
Answer Key
Answers are listed at the very end so you can attempt the questions first.
- Q1 (Bulk Support): A. Efficiently loading or updating large volumes of items across many partition keys — Bulk support is designed for high-throughput ingestion/updates across many partitions, unlike transactional batch which targets one partition.
- Q2 (Bulk Support): A. By automatically grouping and parallelizing requests across partitions — Bulk support groups and parallelizes requests behind the scenes to make the most efficient use of available throughput.
DP-420: Designing and Implementing Cloud-Native Applications Using Microsoft Azure Cosmos DB — term detail page
