Transactions in Practice

Transactions in the real world

Pattern 1: Order processing with TransactionalBatch

🚀 Priya’s NovaSaaS billing system needs to atomically: create an order, create a payment record, and update the customer’s subscription status — all in the same tenant partition.

// All three items share the same partition key: /tenantId = "tenant-abc"
var order = new OrderItem
{
    Id = "ord-500",
    TenantId = "tenant-abc",
    Type = "order",
    Amount = 299.00m,
    Status = "confirmed",
    CreatedAt = DateTime.UtcNow
};

var payment = new PaymentItem
{
    Id = "pay-500",
    TenantId = "tenant-abc",
    Type = "payment",
    OrderId = "ord-500",
    Method = "credit-card",
    Status = "captured"
};

TransactionalBatchResponse batch = await container
    .CreateTransactionalBatch(new PartitionKey("tenant-abc"))
    .CreateItem(order)
    .CreateItem(payment)
    .PatchItem("sub-001", new[]
    {
        PatchOperation.Set("/status", "active"),
        PatchOperation.Set("/lastPaymentDate", DateTime.UtcNow.ToString("o"))
    })
    .ExecuteAsync();

if (batch.IsSuccessStatusCode)
{
    Console.WriteLine("Order, payment, and subscription updated atomically.");
}
else
{
    // ALL operations rolled back — nothing was written
    Console.WriteLine($"Transaction failed: {batch.StatusCode}");
    TransactionalBatchOperationResult failedOp = batch[batch.Count - 1];
    Console.WriteLine($"Failed operation: {failedOp.StatusCode}");
}

Why TransactionalBatch here: All items share /tenantId, the operations are simple CRUD, and we need atomicity. No JavaScript needed.

Pattern 2: Inventory reservation with stored procedure

Jake’s GlobeCart e-commerce platform needs a stored procedure that reads the current stock, checks availability, and reserves items — all atomically:

function reserveInventory(productId, quantity) {
    var context = getContext();
    var container = context.getCollection();
    var response = context.getResponse();

    // Step 1: Read current inventory
    var query = 'SELECT * FROM c WHERE c.id = "' + productId + '" AND c.type = "inventory"';
    var accepted = container.queryDocuments(container.getSelfLink(), query,
        function (err, docs) {
            if (err) throw new Error("Query failed: " + err.message);
            if (docs.length === 0) throw new Error("Product not found: " + productId);

            var inventory = docs[0];

            // Step 2: Check availability
            if (inventory.availableStock < quantity) {
                throw new Error("Insufficient stock. Available: " + inventory.availableStock +
                    ", Requested: " + quantity);
            }

            // Step 3: Reserve (atomic — if this fails, the read is also rolled back)
            inventory.availableStock -= quantity;
            inventory.reservedStock += quantity;
            inventory.lastReservedAt = new Date().toISOString();

            var replaceAccepted = container.replaceDocument(inventory._self, inventory,
                function (err) {
                    if (err) throw new Error("Reserve failed: " + err.message);
                    response.setBody({
                        success: true,
                        remainingStock: inventory.availableStock,
                        reservedQuantity: quantity
                    });
                }
            );

            if (!replaceAccepted) throw new Error("Replace not accepted");
        }
    );

    if (!accepted) throw new Error("Query not accepted");
}

// Calling from C#
var result = await container.Scripts.ExecuteStoredProcedureAsync<dynamic>(
    "reserveInventory",
    new PartitionKey("product-laptop-001"),
    new dynamic[] { "product-laptop-001", 2 });

Console.WriteLine($"Reservation: {result.Resource}");

Why a stored procedure here: We need a read-check-write pattern — read stock, validate, then write. TransactionalBatch can’t express conditional logic (it’s a flat list of operations). The stored procedure ensures no race condition between the read and write.

Pattern 3: Cross-partition Saga

📡 Amara at SensorFlow needs to provision a new IoT device — which involves writing to three different containers with different partition keys:

1. Create device record      → devices container (pk: /deviceId)
2. Assign to fleet            → fleets container (pk: /fleetId)
3. Create monitoring config   → configs container (pk: /deviceId)

These can’t be in a single TransactionalBatch (different containers/partitions). The Saga pattern handles this:

// Saga: provision a new device with compensating transactions
string deviceId = "sensor-5001";

try
{
    // Step 1: Create device
    await devicesContainer.CreateItemAsync(device, new PartitionKey(deviceId));

    try
    {
        // Step 2: Assign to fleet
        await fleetsContainer.PatchItemAsync<FleetItem>(
            "fleet-industrial",
            new PartitionKey("fleet-industrial"),
            new[] { PatchOperation.Add("/devices/-", deviceId) });

        try
        {
            // Step 3: Create monitoring config
            await configsContainer.CreateItemAsync(config, new PartitionKey(deviceId));

            Console.WriteLine("Device provisioned successfully.");
        }
        catch
        {
            // Compensate: remove from fleet
            await fleetsContainer.PatchItemAsync<FleetItem>(
                "fleet-industrial",
                new PartitionKey("fleet-industrial"),
                new[] { PatchOperation.Remove($"/devices/{fleetDeviceIndex}") });
            throw;
        }
    }
    catch
    {
        // Compensate: delete device
        await devicesContainer.DeleteItemAsync<DeviceItem>(deviceId, new PartitionKey(deviceId));
        throw;
    }
}
catch (Exception ex)
{
    Console.WriteLine($"Provisioning failed. All changes compensated. Error: {ex.Message}");
}

Saga trade-offs:

• Not truly atomic — there’s a window where partial state is visible
• Compensating transactions can also fail — you need retry logic and dead-letter queues
• More complex — but it’s the only option for cross-partition/cross-container consistency

Comparing the three patterns

Aspect	TransactionalBatch	Stored procedure	Saga
Scope	Single partition, single container	Single partition, single container	Cross-partition, cross-container
Atomicity	✅ True ACID — all or nothing	✅ True ACID — all or nothing	⚠️ Eventual — compensating transactions
Language	C# / Java SDK	JavaScript (server-side)	C# / Java SDK (client-side orchestration)
Conditional logic	❌ No — flat list of operations	✅ Yes — read, validate, branch	✅ Yes — full client-side logic
Max operations	100 operations, 2 MB	5-second timeout	No hard limit
Complexity	Low	Medium	High
Best for	Multi-item CRUD in same partition	Read-check-write (e.g., inventory)	Cross-partition workflows

💡 Exam tip: when batch can't help

TransactionalBatch is flat — you can’t read an item, check a condition, and then decide what to write. If the question describes a read-then-decide-then-write pattern, the answer is a stored procedure (within one partition) or a Saga (across partitions). Batch is for known operations that don’t depend on reads.

💡 Exam tip: saga is not ACID

The Saga pattern provides eventual consistency, not ACID atomicity. There’s always a window where partial state is visible. Compensating transactions may also fail, requiring idempotent operations and retry logic. The exam tests this distinction — if a question requires strict ACID across partitions, the answer is “not possible with Cosmos DB” (redesign your data model to put the data in one partition).

🎬 Video walkthrough

🎬 Video coming soon

Transactions in Practice — DP-420 Module 11

Transactions in Practice — DP-420 Module 11

~12 min

Flashcards

Question

When should you use a stored procedure instead of TransactionalBatch?

Click or press Enter to reveal answer

Answer

When you need conditional logic — read a value, check a condition, then decide what to write. TransactionalBatch is a flat list with no branching. Stored procedures can read, validate, and branch within an ACID transaction.

Click to flip back

💡 Show hint

Question

Is the Saga pattern truly atomic?

Click or press Enter to reveal answer

Answer

No. Sagas provide eventual consistency through compensating transactions. There's a window where partial state is visible. Compensating transactions can also fail. Sagas are the only option for cross-partition consistency, but they're not ACID.

Click to flip back

💡 Show hint

Question

What is a compensating transaction in the Saga pattern?

Click or press Enter to reveal answer

Answer

An operation that undoes a previous step when a later step fails. For example, if step 3 fails, you run compensating transactions to undo steps 2 and 1. Compensating transactions must be idempotent (safe to retry).

Click to flip back

💡 Show hint

Knowledge check

Knowledge Check

Jake's GlobeCart needs to: (1) check product stock, (2) reserve inventory if available, (3) reject if out of stock. All data is in the same partition. Which approach is best?

ATransactionalBatch — create a reservation item and patch the inventoryBStored procedure — read stock, validate, then update atomically with conditional logicCSaga pattern — orchestrate with compensating transactionsDTwo separate SDK calls — read first, then update

Check Answer

Knowledge Check

Amara needs to write data to three different containers atomically. What's her best option?

ATransactionalBatch spanning three containersBA stored procedure that writes to three containersCThe Saga pattern with compensating transactionsDIt's not possible — Cosmos DB can't do cross-container transactions

Check Answer

Knowledge Check

During a Saga, step 2 of 3 succeeds but step 3 fails. The compensating transaction for step 2 also fails. What should happen?

AIgnore the failure — the system will eventually self-healBRetry the compensating transaction with idempotent logic, and log to a dead-letter queue if retries are exhaustedCRoll back step 1 and restart the entire sagaDThe system is now in an inconsistent state with no recovery option

Check Answer

---

Next up: Domain 2 — dive into indexing policies, consistency levels, and throughput optimisation to make your Cosmos DB data model perform at scale.