Announcing Public Preview of Distributed Transactions in Azure Cosmos DB for NoSQL

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.

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 — one that is difficult to implement, hard to test exhaustively, and expensive to operate at global scale.

Where existing approaches fall short

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 — as long as every document you’re modifying shares the same partition key inside a single container. But real systems rarely line up so neatly.

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 — patterns that are complex to implement, test, and operate.

Introducing distributed transactions in Azure Cosmos DB

Today, we’re 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 — 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’s 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.

Either every operation in the transaction commits and becomes visible together, or none of them apply. There’s 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.

What this unlocks

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 — as long as every document you’re modifying shares the same partition key inside a single container.

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 — patterns that are complex to implement, test, and operate.

Distributed transactions extend atomicity beyond a single partition; the set of operations is committed as a single atomic unit.

What you can do today

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

Cross-partition write transactions

With a single distributed write transaction, you can perform a set of write operations atomically across partitions. A cross-partition write transaction lets you:

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

Here’s an order placement — order, line item, and audit event — composed into a single atomic write across containers and databases:

// Create an order, its line item, and an audit event atomically
// — across containers and databases in the same account
DistributedTransactionResponse response = await client
    .CreateDistributedWriteTransaction()
    .CreateItem("commerce", "orders",     new PartitionKey(order.CustomerId), order)
    .CreateItem("commerce", "orderItems", new PartitionKey(item.OrderId),     item)
    .CreateItem("audit",    "events",     new PartitionKey(evt.Date),         evt)
    .CommitTransactionAsync(CancellationToken.None);

Cross-partition read transactions

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 — for example, fetching a customer’s account and their open orders — and reason about them as a snapshot, without interference from concurrent writes.

// Read the order, its line item, and the audit event as a consistent snapshot
DistributedReadTransaction txn = client.CreateDistributedReadTransaction();

txn.ReadItem("commerce", "orders",     new PartitionKey(customerId), orderId)
   .ReadItem("commerce", "orderItems", new PartitionKey(orderId),    lineItemId)
   .ReadItem("audit",    "events",     new PartitionKey(auditDate),  auditId);
DistributedTransactionResponse response = await txn.CommitTransactionAsync();

Transactional boundaries honored across failovers

Distributed transactions compose with your account’s consistency level. In public preview, Azure Cosmos DB also honors transactional boundaries through a regional failover — a capability that ensures the all-or-nothing guarantee remains intact even when the active write region changes.

Where this delivers value off

Distributed transactions are designed for workloads where correctness across partitions matters as much as throughput. A few patterns where this pays off immediately:

• Money movement and ledgers — debit one account, credit another, and write the audit row, with no possibility of a partial transfer. The accounts almost always live on different partitions.
• Order management and inventory — atomically reserve stock in one container, create the order in another, and emit an audit event — instead of a saga that has to reverse half the world on failure.
• Identity and multi-tenant state — update a user record, their tenant membership, and a permissions document together, even when those entities are partitioned by different keys.
• Idempotent business workflows — long-running workflows that must be retried safely after partial failure. The UUID v4 idempotency token makes safe retry the default, not an application-layer obligation.
• Cross-entity invariants — anywhere your domain has a “these writes must succeed together” rule that today is enforced by careful retry logic, sagas, or a separate transactional engine.

If your workload only needs atomicity across documents that share a partition key, keep using the existing Batch API — it remains the lower-latency choice. Distributed transactions are the right tool when the data that must move together doesn’t fit on a single partition.

Get started

1. Request enrollment for your accounts.
2. Install the Azure Cosmos DB .NET v3 preview (v3.62.0-preview.0) SDK
3. Read the how-to guide on Microsoft Learn for the full model, limits, and patterns.

Learn more

• How-to: Use distributed transactions in Azure Cosmos DB for NoSQL

We can’t wait to see what you build — especially as developers bring stronger correctness guarantees to the cloud-native applications, AI workflows, and globally distributed systems that increasingly define modern software.