View source for Transactional Batch

&larr; Back to [[DP-420: Azure Cosmos DB Developer Specialty|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.

<pre>
| 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()`       |
          
</pre>

<pre>
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
    }
}
</pre>

== More Info & Links ==
* [https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/transactional-batch 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''

[[Category:DP-420 Terminology]]
[[Category:Client Connectivity & SDK]]