{"id":12240,"date":"2026-06-02T12:15:20","date_gmt":"2026-06-02T19:15:20","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=12240"},"modified":"2026-06-03T09:52:15","modified_gmt":"2026-06-03T16:52:15","slug":"announcing-public-preview-of-distributed-transactions-in-azure-cosmos-db-for-nosql","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/announcing-public-preview-of-distributed-transactions-in-azure-cosmos-db-for-nosql\/","title":{"rendered":"Announcing Public Preview of Distributed Transactions in Azure Cosmos DB for NoSQL"},"content":{"rendered":"

In modern cloud-native applications, correctness is often hardest to maintain at the exact moment a workflow crosses boundaries. A checkout flow writes an order in one place; decrements inventory in another and emits an audit event somewhere else. A money movement workflow debits one account, credits another, and records the transfer for compliance. An AI workflow updates state across multiple services while coordinating retries, handoffs, and downstream actions. Each step is individually straightforward. Keeping the entire workflow correct under partial failures, concurrent updates, retries, and regional events is where the real engineering effort begins.<\/p>\n

Developers know this pattern well. One write succeeds, another times out, and now the system has to decide whether to retry, compensate, reconcile, or wait for a background repair process. What starts as business logic quickly turns into saga orchestration, compensation logic, idempotency safeguards, conditional checks, and increasingly fragile retry behavior. Over time, maintaining cross-service consistency becomes its own subsystem \u2014 one that is difficult to implement, hard to test exhaustively, and expensive to operate at global scale.<\/p>\n

Where existing approaches fall short<\/h2>\n

This challenge is especially familiar in distributed data architectures, where the application must preserve invariants across entities that do not live in the same partition, container, or database. Azure Cosmos DB for NoSQL has long supported atomic, multi-document writes through stored procedures and the Batch API in the SDK. Those mechanisms work great \u2014 as long as every document you\u2019re modifying shares the same partition key inside a single container. But real systems rarely line up so neatly.<\/p>\n

A money transfer touches two customer entities that live on different partitions. An order placement decrements stock in one container and writes an audit row in another. A multi-tenant state change updates two related entities with different partition keys. Until now, getting this right required compensation logic, sagas, or carefully orchestrated retries \u2014 patterns that are complex to implement, test, and operate.<\/p>\n

Introducing distributed transactions in Azure Cosmos DB<\/h2>\n

Today, we\u2019re excited to announce the public preview of distributed transactions in Azure Cosmos DB for NoSQL. With a single API call, your application can now commit a set of writes atomically across partitions, containers, and databases in the same account \u2014 without giving up the scale, global distribution, and elasticity of Azure Cosmos DB. Either every operation in the transaction commits and becomes visible together, or none of them apply. There\u2019s no partial state, no half-written orders, no application-level sagas to maintain. Just one call, all or nothing. This closes a key gap for developers who previously had to implement cross-partition consistency in the application layer.<\/p>\n

Either every operation in the transaction commits and becomes visible together, or none of them apply. There\u2019s no partial state, no half-written orders, no application-level sagas to maintain. Just one call, all or nothing. This closes a key gap for developers who previously had to implement cross-partition consistency in the application layer.<\/p>\n

\"Distributed<\/a><\/p>\n

What this unlocks<\/h2>\n

Azure Cosmos DB for NoSQL has long supported atomic, multi-document writes through stored procedures and the Batch API in the .NET SDK. Those mechanisms work great \u2014 as long as every document you\u2019re modifying shares the same partition key inside a single container.<\/p>\n

Real applications rarely have that luxury. A money transfer touches two customer entities that live on different partitions. An order placement decrements stock in one container and writes an audit row in another. A multi-tenant state change updates two related entities with different partition keys. Until now, getting this right required compensation logic, sagas, or carefully orchestrated retries \u2014 patterns that are complex to implement, test, and operate.<\/p>\n

Distributed transactions extend atomicity beyond a single partition; the set of operations is committed as a single atomic unit.<\/p>\n

What you can do today<\/h2>\n

Azure Cosmos DB for NoSQL supports cross-partition read transactions and cross-partition write transactions \u2014 letting your application reason about related items together, even when they live across partitions, containers, and databases in the same account.<\/p>\n

Cross-partition write transactions<\/h3>\n

With a single distributed write transaction, you can perform a set of write operations atomically across partitions. A cross-partition write transaction lets you:<\/p>\n

    \n
  • Write to multiple items with different partition key values within a container.<\/li>\n
  • Span multiple containers across databases within the same account.<\/li>\n
  • Combine create, upsert, replace, patch, and delete operations in a single atomic unit.<\/li>\n
  • Include ETag-based conditional checks so writes commit only if the items haven\u2019t changed since you read them.<\/li>\n
  • Perform read-driven validation as part of the transaction, ensuring correctness before committing changes \u2014 for example, validating account balances, checking inventory, or enforcing state transitions.<\/li>\n<\/ul>\n

    Here\u2019s an order placement \u2014 order, line item, and audit event \u2014 composed into a single atomic write across containers and databases:<\/p>\n

    \/\/ Create an order, its line item, and an audit event atomically\r\n\/\/ \u2014 across containers and databases in the same account\r\nDistributedTransactionResponse response = await client\r\n    .CreateDistributedWriteTransaction()\r\n    .CreateItem(\"commerce\", \"orders\",     new PartitionKey(order.CustomerId), order)\r\n    .CreateItem(\"commerce\", \"orderItems\", new PartitionKey(item.OrderId),     item)\r\n    .CreateItem(\"audit\",    \"events\",     new PartitionKey(evt.Date),         evt)\r\n    .CommitTransactionAsync(CancellationToken.None);\r\n<\/code><\/pre>\n
    Cross-partition read transactions<\/h3>\n
    A cross-partition read transaction returns a consistent view of items or documents that live across partitions, containers, or databases. This is useful when your application needs to read related entities together \u2014 for example, fetching a customer\u2019s account and their open orders \u2014 and reason about them as a snapshot, without interference from concurrent writes.<\/p>\n
    \/\/ Read the order, its line item, and the audit event as a consistent snapshot\r\nDistributedReadTransaction txn = client.CreateDistributedReadTransaction();\r\n\r\ntxn.ReadItem(\"commerce\", \"orders\",     new PartitionKey(customerId), orderId)\r\n   .ReadItem(\"commerce\", \"orderItems\", new PartitionKey(orderId),    lineItemId)\r\n   .ReadItem(\"audit\",    \"events\",     new PartitionKey(auditDate),  auditId);\r\nDistributedTransactionResponse response = await txn.CommitTransactionAsync();\r\n<\/code><\/pre>\n
    Transactional boundaries honored across failovers<\/h3>\n
    Distributed transactions compose with your account\u2019s consistency level. In public preview, Azure Cosmos DB also honors transactional boundaries through a regional failover \u2014 a capability that ensures the all-or-nothing guarantee remains intact even when the active write region changes.<\/p>\n