SDK CRUD Operations and Transactions

CRUD in Cosmos DB

All CRUD operations in C#

Create

var project = new ProjectItem
{
    Id = "proj-001",
    TenantId = "tenant-abc",
    Type = "project",
    Name = "Website Redesign",
    Status = "active"
};

ItemResponse<ProjectItem> response = await container.CreateItemAsync(
    project,
    new PartitionKey("tenant-abc"));

Console.WriteLine($"Created. RU charge: {response.RequestCharge}");
// Fails with 409 Conflict if proj-001 already exists in this partition

Read (point read)

ItemResponse<ProjectItem> response = await container.ReadItemAsync<ProjectItem>(
    id: "proj-001",
    partitionKey: new PartitionKey("tenant-abc"));

ProjectItem project = response.Resource;
Console.WriteLine($"Read '{project.Name}'. RU: {response.RequestCharge}");
// ~1 RU for a 1 KB item — the cheapest operation

Upsert

project.Status = "completed";

ItemResponse<ProjectItem> response = await container.UpsertItemAsync(
    project,
    new PartitionKey("tenant-abc"));
// If proj-001 exists → replaced. If not → created. No error either way.

Replace

project.Name = "Website Redesign v2";

ItemResponse<ProjectItem> response = await container.ReplaceItemAsync(
    project,
    id: "proj-001",
    partitionKey: new PartitionKey("tenant-abc"));
// Fails with 404 if the item doesn't exist

Delete

ItemResponse<ProjectItem> response = await container.DeleteItemAsync<ProjectItem>(
    id: "proj-001",
    partitionKey: new PartitionKey("tenant-abc"));
// Fails with 404 if the item doesn't exist

Patch operations

Patch lets you modify specific properties without reading and replacing the entire document:

// Patch: update status and increment a counter
ItemResponse<ProjectItem> response = await container.PatchItemAsync<ProjectItem>(
    id: "proj-001",
    partitionKey: new PartitionKey("tenant-abc"),
    patchOperations: new[]
    {
        PatchOperation.Set("/status", "in-review"),       // Set a value
        PatchOperation.Add("/tags/-", "urgent"),           // Append to array
        PatchOperation.Replace("/name", "Final Design"),   // Replace a value
        PatchOperation.Remove("/tempFlag"),                // Remove a property
        PatchOperation.Increment("/viewCount", 1)          // Increment number
    });

Patch operation	What it does
Set	Sets a property value (creates it if missing)
Add	Adds to an array (/- = append) or creates a new property
Replace	Replaces an existing property (fails if missing)
Remove	Removes a property
Increment	Increments a numeric value (atomic — no read-modify-write race)
Move	Moves a property from one path to another within the document

Why Patch matters: Without Patch, updating one field means reading the entire document, changing it in memory, and replacing it — 3 operations and a concurrency risk. Patch does it in 1 operation.

Optimistic concurrency with ETags

Every Cosmos DB item has an _etag property that changes with every update. Use it to prevent lost updates:

// Step 1: Read the item (get current ETag)
ItemResponse<ProjectItem> response = await container.ReadItemAsync<ProjectItem>(
    "proj-001", new PartitionKey("tenant-abc"));

string etag = response.ETag;

// Step 2: Replace with ETag check
try
{
    ProjectItem project = response.Resource;
    project.Status = "approved";

    await container.ReplaceItemAsync(
        project,
        "proj-001",
        new PartitionKey("tenant-abc"),
        new ItemRequestOptions { IfMatchEtag = etag });  // Only if unchanged
}
catch (CosmosException ex) when (ex.StatusCode == System.Net.HttpStatusCode.PreconditionFailed)
{
    // 412 — someone else modified the document. Re-read and retry.
    Console.WriteLine("Conflict! Document was modified by another user.");
}

How it works:

1. Read the item → get its _etag
2. Send a Replace/Upsert with IfMatchEtag = etag
3. If the ETag still matches → update succeeds
4. If someone changed the document → 412 Precondition Failed → re-read and retry

💡 Exam tip: ETag and 412

The _etag is a system-generated property that acts as a version stamp. When you pass IfMatchEtag in a request, Cosmos DB compares the ETag before writing. A mismatch means someone else modified the document, and you get a 412 Precondition Failed error. This is optimistic concurrency — no locks, just version checks. Know the 412 status code for the exam.

TransactionalBatch

TransactionalBatch provides ACID transactions for multiple operations within a single logical partition:

var project = new ProjectItem
{
    Id = "proj-002", TenantId = "tenant-abc", Type = "project",
    Name = "Mobile App"
};

var firstTask = new TaskItem
{
    Id = "task-101", TenantId = "tenant-abc", Type = "task",
    ProjectId = "proj-002", Title = "Set up CI/CD"
};

TransactionalBatchResponse batchResponse = await container
    .CreateTransactionalBatch(new PartitionKey("tenant-abc"))
    .CreateItem(project)
    .CreateItem(firstTask)
    .PatchItem("proj-001", new[]
    {
        PatchOperation.Increment("/childProjectCount", 1)
    })
    .ExecuteAsync();

if (batchResponse.IsSuccessStatusCode)
{
    Console.WriteLine("All operations succeeded atomically.");
}
else
{
    Console.WriteLine($"Batch failed: {batchResponse.StatusCode}");
    // ALL operations rolled back — nothing was written
}

TransactionalBatch rules:

• All operations must target the same logical partition (same partition key value)
• Maximum 100 operations per batch
• Maximum 2 MB total payload
• All-or-nothing: if any operation fails, the entire batch is rolled back
• Supports: Create, Read, Upsert, Replace, Delete, Patch

Bulk mode

Bulk mode optimises high-volume writes by batching requests behind the scenes:

CosmosClient bulkClient = new CosmosClient(
    endpoint, key,
    new CosmosClientOptions { AllowBulkExecution = true });

// Create many tasks concurrently — SDK batches them automatically
List<Task> tasks = new();
foreach (var item in itemsToInsert)
{
    tasks.Add(container.CreateItemAsync(item, new PartitionKey(item.TenantId)));
}
await Task.WhenAll(tasks);

Bulk mode is NOT transactional — items are written independently. Some may succeed while others fail. Use TransactionalBatch when you need atomicity.

Handling 429 throttling

When you exceed provisioned RU/s, Cosmos DB returns 429 Too Many Requests with a Retry-After header:

Aspect	Detail
Default retries	9 retries with exponential backoff
Retry-After header	Tells you how long to wait (in ms)
SDK behaviour	Auto-retries transparently — your code often never sees the 429
Custom config	CosmosClientOptions.MaxRetryAttemptsOnRateLimitedRequests = 15
Custom wait	CosmosClientOptions.MaxRetryWaitTimeOnRateLimitedRequests = TimeSpan.FromSeconds(60)

var options = new CosmosClientOptions
{
    MaxRetryAttemptsOnRateLimitedRequests = 15,
    MaxRetryWaitTimeOnRateLimitedRequests = TimeSpan.FromSeconds(60)
};

Ravi’s mistake: Ravi turned off retries (MaxRetryAttemptsOnRateLimitedRequests = 0) thinking it would “fail fast.” Instead, his app crashed with hundreds of 429 errors during peak load. The default 9 retries exist for a reason — they smooth out temporary spikes.

💡 Exam tip: batch vs bulk

TransactionalBatch = ACID, same partition, max 100 ops, all-or-nothing. Bulk mode = NOT transactional, optimises throughput by batching network calls, items can be in different partitions, some may succeed while others fail. The exam loves confusing these two. If the question asks about atomicity → batch. If it asks about throughput optimisation → bulk.

🎬 Video walkthrough

🎬 Video coming soon

SDK CRUD & Transactions — DP-420 Module 7

SDK CRUD & Transactions — DP-420 Module 7

~18 min

Flashcards

Question

What's the difference between Upsert and Replace?

Click or press Enter to reveal answer

Answer

Upsert: if the item exists, replace it; if not, create it — never fails with 404. Replace: overwrites an existing item; fails with 404 if the item doesn't exist. Use Upsert when you're unsure if the item exists.

Click to flip back

💡 Show hint

Question

What HTTP status code indicates an ETag mismatch in optimistic concurrency?

Click or press Enter to reveal answer

Answer

412 Precondition Failed. This means someone modified the document between your read and your write. The IfMatchEtag condition failed. Your code should re-read the document and retry.

Click to flip back

💡 Show hint

Question

What are the limits of TransactionalBatch?

Click or press Enter to reveal answer

Answer

Same logical partition (same partition key value), maximum 100 operations, maximum 2 MB total payload, all-or-nothing (ACID). Supports Create, Read, Upsert, Replace, Delete, and Patch operations.

Click to flip back

💡 Show hint

Question

Is bulk mode transactional?

Click or press Enter to reveal answer

Answer

No. Bulk mode optimises throughput by batching network calls, but each item is written independently. Some items may succeed while others fail. For atomic multi-item writes, use TransactionalBatch instead.

Click to flip back

💡 Show hint

Question

How many times does the SDK retry 429 errors by default?

Click or press Enter to reveal answer

Answer

9 times with exponential backoff. The SDK uses the Retry-After header to determine wait time. You can customise with MaxRetryAttemptsOnRateLimitedRequests and MaxRetryWaitTimeOnRateLimitedRequests.

Click to flip back

💡 Show hint

Knowledge check

Knowledge Check

Priya needs to atomically create a project and its first task in the 'workitems' container (both in the same tenant). Which approach is correct?

ACall CreateItemAsync twice — the SDK handles atomicity automaticallyBUse TransactionalBatch with both Create operations targeting the same partition keyCUse bulk mode with AllowBulkExecution = trueDUse a stored procedure — it's the only way to get ACID in Cosmos DB

Check Answer

Knowledge Check

Ravi and Sophie both read the same project document (ETag: 'abc123'). Ravi updates it first. What happens when Sophie tries to Replace with IfMatchEtag = 'abc123'?

ASophie's update overwrites Ravi's — last write winsBSophie gets a 412 Precondition Failed — the ETag changed when Ravi updatedCSophie gets a 409 Conflict — duplicate update detectedDBoth updates are merged automatically

Check Answer

Knowledge Check

Priya wants to increment a view counter on a project document without reading it first. Which operation should she use?

AReadItemAsync → modify → ReplaceItemAsyncBPatchItemAsync with PatchOperation.IncrementCUpsertItemAsync with the new counter valueDTransactionalBatch with a Read and Replace

Check Answer

---

Next up: SQL Queries — learn the Cosmos DB SQL query language, including SELECT, WHERE, JOIN (intra-document only), cross-partition queries, and composite indexes.