cosmosdb-coding

Azure Cosmos DB Coding Standards

Container Design

Single-Container Pattern

// Multiple entity types in one container, discriminated by "type"
{ "id": "order-001", "type": "order", "customerId": "c1", "total": 100.00 }
{ "id": "item-001", "type": "orderItem", "orderId": "order-001", "customerId": "c1", "productName": "Widget" }

Partition Key Selection Checklist

1. What is the most common query filter? → Use that as partition key
2. Is cardinality high enough? (>1000 distinct values) → Good
3. Is distribution even? (no single key >5% of data) → Good
4. Does the key support transactions? (all related docs in same partition) → Good

RU Estimation

Operation	Approximate RU Cost
Point read (1KB doc)	~1 RU
Point read (10KB doc)	~10 RU
Query (single partition, 10 results)	~5-10 RU
Query (cross-partition, 10 results)	~50-100 RU
Create (1KB doc)	~5 RU
Replace (1KB doc)	~10 RU
Delete (1KB doc)	~5 RU

TTL (Time-to-Live)

// Container-level TTL (seconds)
{ "defaultTtl": 86400 }

// Document-level TTL override
{ "id": "session-001", "ttl": 3600 }

// Disable TTL for specific document
{ "id": "important-001", "ttl": -1 }

Change Feed Pattern

// Use change feed for:
// - Materialized views (denormalized read models)
// - Event-driven processing
// - Real-time analytics
// - Cross-container data synchronization

Stored Procedures (JavaScript)

• Execute within a single logical partition
• Use for atomic multi-document operations
• Handle continuation for large datasets
• Keep business logic in application code

function bulkCreateItems(items) {
    var context = getContext();
    var container = context.getCollection();
    var response = context.getResponse();
    var created = 0;

    if (!items || items.length === 0) {
        response.setBody({ created: 0 });
        return;
    }

    createNext(0);

    function createNext(index) {
        if (index >= items.length) {
            response.setBody({ created: created });
            return;
        }
        var accepted = container.createDocument(
            container.getSelfLink(), items[index],
            function(err, doc) {
                if (err) throw new Error("Error: " + err.message);
                created++;
                createNext(index + 1);
            });
        if (!accepted) {
            response.setBody({ created: created, continuation: true });
        }
    }
}

Hierarchical Partition Keys

// Multi-level partition key for multi-tenant scenarios
var containerProperties = new ContainerProperties
{
    Id = "orders",
    PartitionKeyPaths = new Collection<string> { "/tenantId", "/customerId" }
};

Optimistic Concurrency

try
{
    var response = await container.ReplaceItemAsync(
        order, order.Id,
        new PartitionKey(order.CustomerId),
        new ItemRequestOptions { IfMatchEtag = order.ETag });
}
catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.PreconditionFailed)
{
    // Document was modified by another process — handle conflict
}