Transactional Batch

← Back to DP-420 Terminology Reference

Category: Client Connectivity & SDK

Summary: Groups multiple point operations on the same logical partition into one atomic transaction.

Overview

Transactional batch (SDK Transactional Batch) allows you to group multiple point operations (creates, reads, updates, deletes) targeting the same logical partition key into a single atomic transaction — either all operations succeed, or none do. This is useful for maintaining consistency across related items within one logical partition without writing a stored procedure.

| Feature                 | AllowBulkExecution          | TransactionalBatch                 |
| ----------------------- | --------------------------- | ---------------------------------- |
| Purpose                 | Maximum throughput          | Atomic transaction                 |
| Scope                   | Many operations             | Group of operations                |
| Same partition required | ❌ No                        | ✅ Yes                              |
| Atomic                  | ❌ No                        | ✅ Yes                              |
| Rollback                | ❌ No                        | ✅ Yes                              |
| Cross-partition support | ✅ Yes                       | ❌ No                               |
| Typical scenario        | Import 10M records          | Create Order + OrderItems together |
| SDK setting             | `AllowBulkExecution = true` | `CreateTransactionalBatch()`       |
          

using Microsoft.Azure.Cosmos;
using System.Threading.Tasks;

public async Task ExecuteBatchAsync(Container container, string targetPartitionKey)
{
    // 1. Set/initialize the batch scoped to a specific logical partition key value
    PartitionKey partitionKey = new PartitionKey(targetPartitionKey);
    TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

    // 2. Add multiple point operations that belong to that SAME partition key
    batch.CreateItem(new { id = "doc-1", category = targetPartitionKey, name = "Item One" });
    batch.ReplaceItem("doc-2", new { id = "doc-2", category = targetPartitionKey, name = "Item Two Updated" });
    batch.DeleteItem("doc-3");

    // 3. Execute the batch atomically as a single unit of work
    using TransactionalBatchResponse response = await batch.ExecuteAsync();

    if (response.IsSuccessStatusCode)
    {
        // All operations succeeded atomically
    }
}

More Info & Links

• Microsoft Learn: Transactional batch operations

DP-420 Style Practice Questions

Q1. What is a key requirement for using SDK Transactional Batch in Azure Cosmos DB?

• A. All operations in the batch must target the same logical partition key
• B. Operations can span multiple partition keys
• C. The container must have TTL enabled
• D. Multi-region writes must be enabled

Q2. What happens if one operation within a transactional batch fails?

• A. The entire batch is rolled back; none of the operations are committed
• B. Only the failed operation is skipped; the rest commit
• C. The container automatically retries indefinitely
• D. The failure is ignored and logged only

Answer Key

Answers are listed at the very end so you can attempt the questions first.

• Q1 (Transactional Batch): A. All operations in the batch must target the same logical partition key — Transactional batch operations are limited to a single logical partition key, ensuring true atomicity.
• Q2 (Transactional Batch): A. The entire batch is rolled back; none of the operations are committed — Transactional batch is all-or-nothing: if any operation fails, the entire batch is rolled back.

---

DP-420: Designing and Implementing Cloud-Native Applications Using Microsoft Azure Cosmos DB — term detail page