Manage multi-document transactions using SDK Transactional Batch

The Azure Cosmos DB is a globally distributed, horizontally scalable, multi-model database service provided by Microsoft. It provides the flexibility to store and query various types of data, including documents, key-value pairs, graph data, and columnar data. In this article, we will focus specifically on managing multi-document transactions using the SDK transactional batch feature of Azure Cosmos DB.

Transactional batch allows you to perform multiple operations as part of a single transaction, ensuring that they all succeed or fail together. Transactions are crucial for maintaining data integrity and consistency, especially in scenarios where multiple documents need to be updated or created atomically.

Getting Started

To get started with managing multi-document transactions using the SDK transactional batch, you need to first create an instance of TransactionalBatch.

using Microsoft.Azure.Cosmos;

Here, you need to replace the “connection-string”, “database-id”, “container-id”, and “partitionKey” with appropriate values specific to your Cosmos DB account.

Adding Operations

Once you have the TransactionalBatch instance, you can start adding operations to it. The supported operations include read operations, replace operations, upsert operations, and delete operations.

transactionalBatch.ReadItem("document-id", new PartitionKey("partition-key-value"));
transactionalBatch.ReplaceItem("document-id", document, new PartitionKey("partition-key-value"));
transactionalBatch.UpsertItem(document);
transactionalBatch.DeleteItem("document-id", new PartitionKey("partition-key-value"));

Here, “document-id” represents the unique identifier of the document you want to read, replace, or delete, and “partition-key-value” represents the partition key value of the document. The UpsertItem operation is used to either update an existing document or insert a new document if it doesn’t exist.

Executing the Transactional Batch

Once you have added all the desired operations to the transactional batch, you can execute the batch using the ExecuteAsync method.

var response = await transactionalBatch.ExecuteAsync();

The ExecuteAsync method returns a TransactionalBatchResponse object, which provides information about the success or failure of the batch operation.

Limitations and Custom Request Options

It’s important to note that the transactional batch feature has some limitations. Only a subset of operations is currently supported within a transactional batch, and the maximum number of operations allowed in a single batch is 100.

In addition to managing transactions, you can also specify custom request options for each operation within the transactional batch. For example, you can set the PreTriggers and PostTriggers options to execute triggers before or after the operation, respectively.

var requestOptions = new ItemRequestOptions
{
PreTriggers = new List { "trigger1", "trigger2" },
PostTriggers = new List { "trigger3" }
};

transactionalBatch.ReadItem("document-id", new PartitionKey("partition-key-value"), requestOptions);


By leveraging the transactional batch feature, you can ensure consistency across multiple document operations, making it easier to maintain data integrity. This can be particularly useful in scenarios where you need to perform complex operations involving multiple documents.

In conclusion, using the SDK transactional batch feature of Azure Cosmos DB allows you to manage multi-document transactions efficiently. By grouping operations within a single transactional batch, you can ensure that all operations succeed or fail as a single unit, maintaining data consistency and integrity.