Microsoft Azure — Cosmos DB (Global NoSQL)

Azure is Microsoft's cloud computing platform offering over 200 services. This article covers cosmos db (global nosql) with production-ready configurations, best practices, and hands-on examples.

Why Cosmos DB? The Global NoSQL Bet

Cosmos DB is Microsoft's answer to globally distributed, multi-model NoSQL. It's not just a database; it's a platform for planetary-scale applications. The core value proposition is turnkey global distribution with multi-region writes and five consistency models. But this power comes with sharp edges. You pay for throughput (RU/s) and storage, and misconfiguring either can bankrupt your project. The key insight: Cosmos DB is ideal for applications that need single-digit-millisecond reads at any scale, but it's terrible for ad-hoc analytics or complex joins. If you need those, use a different tool. This article assumes you've already decided Cosmos DB is the right fit and focuses on making it work in production.

#!/bin/bash
# Create Cosmos DB account with multi-region writes enabled
az cosmosdb create \
  --name mycosmosdb \
  --resource-group myrg \
  --kind GlobalDocumentDB \
  --locations regionName=eastus failoverPriority=0 isZoneRedundant=false \
  --locations regionName=westus failoverPriority=1 isZoneRedundant=false \
  --enable-multiple-write-locations true \
  --default-consistency-level Session

Partitioning: The Single Most Important Decision

Partitioning in Cosmos DB is not optional. Every container must have a partition key, and choosing the wrong one is the #1 cause of production failures. The partition key determines how data is distributed across physical partitions. A good partition key has high cardinality (many distinct values) and even request distribution. Avoid keys that cause hot partitions: timestamps, monotonically increasing IDs, or low-cardinality fields like status. The physical partition limit is 50 GB of storage and 10k RU/s throughput. If you exceed either, Cosmos DB splits the partition automatically, but splits are disruptive. Design for this upfront. Use a synthetic key if needed, like userId + date concatenated.

using Microsoft.Azure.Cosmos;
using System;

public class Order
{
    public string id { get; set; }
    public string CustomerId { get; set; }
    public DateTime OrderDate { get; set; }
    public string PartitionKey => $"{CustomerId}-{OrderDate:yyyyMM}";
}

// Container creation with partition key
ContainerProperties containerProperties = new ContainerProperties
{
    Id = "orders",
    PartitionKeyPath = "/PartitionKey"
};

// Throughput at container level (recommended for production)
ThroughputProperties throughput = ThroughputProperties.CreateManualThroughput(10000);
Container container = await database.CreateContainerIfNotExistsAsync(containerProperties, throughput);

Consistency Models: The Performance vs. Correctness Trade-off

Cosmos DB offers five consistency levels: Strong, Bounded Staleness, Session, Consistent Prefix, and Eventual. Each has different performance and availability characteristics. Strong consistency guarantees linearizability but requires quorum reads across regions, increasing latency and reducing availability during failures. Session consistency is the sweet spot for most applications: it guarantees monotonic reads and writes within a single client session. Bounded Staleness allows a configurable lag (time or operations) before reads are consistent. Eventual is fastest but offers no ordering guarantees. In production, start with Session and only move to Strong if your application requires it (e.g., financial transactions).

using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Fluent;

// Create client with Session consistency
CosmosClient client = new CosmosClientBuilder("<connection-string>")
    .WithConsistencyLevel(ConsistencyLevel.Session)
    .WithApplicationRegion("East US")
    .Build();

// For a specific request, override to Strong if needed
ItemRequestOptions requestOptions = new ItemRequestOptions
{
    ConsistencyLevel = ConsistencyLevel.Strong
};

Order order = await container.ReadItemAsync<Order>("order-123", new PartitionKey("customer-456"), requestOptions);

Request Units (RU/s): Capacity Planning and Cost Control

RU/s is the currency of Cosmos DB. Every operation consumes RU: a point read (1 KB item) costs 1 RU, a 1 KB write costs ~5 RU, and a cross-partition query can cost hundreds. You must provision RU/s at the container or database level. Autoscale is available but can cause throttling if you exceed max RU/s. In production, use manual throughput with monitoring to adjust. The biggest mistake is under-provisioning: throttling causes retries and increased latency. Over-provisioning wastes money. Use Azure Monitor to track Normalized RU Consumption metric; if it consistently exceeds 80%, increase RU/s. Also consider using reserved capacity for 1- or 3-year terms to save up to 65%.

using Microsoft.Azure.Cosmos;
using System.Threading.Tasks;

// Get current throughput
ThroughputResponse throughputResponse = await container.ReadThroughputAsync();
int? currentThroughput = throughputResponse.Resource?.Throughput;

// Update throughput (scale up)
ThroughputProperties newThroughput = ThroughputProperties.CreateManualThroughput(20000);
ThroughputResponse updateResponse = await container.ReplaceThroughputAsync(newThroughput);

// Check normalized RU consumption via Azure Monitor (pseudo-code)
// Metric: "Normalized RU Consumption" > 80% triggers alert

Indexing Policies: Tuning for Query Performance

Cosmos DB automatically indexes all properties by default. This is convenient but wasteful. In production, you should customize the indexing policy to exclude paths you never query and include only those you need. This reduces RU consumption and storage. The indexing policy supports three modes: consistent (default), lazy (eventually consistent, rarely used), and none (for write-heavy workloads). You can also set composite indexes for ORDER BY queries on multiple properties. A common mistake is leaving the default policy on a container with large documents or many properties. Always test your queries with the Azure Portal's Query Metrics to see the RU cost and adjust indexing accordingly.

using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Fluent;

public class CosmosService
{
    private static readonly CosmosClient _client;

    static CosmosService()
    {
        _client = new CosmosClientBuilder("<connection-string>")
            .WithApplicationRegion("West US")
            .WithConnectionModeDirect()
            .WithThrottlingRetryOptions(
                maxRetryAttemptsOnThrottledRequests: 9,
                maxRetryWaitTimeOnThrottledRequests: TimeSpan.FromSeconds(30))
            .Build();
    }

    public Container GetContainer(string databaseId, string containerId)
    {
        return _client.GetDatabase(databaseId).GetContainer(containerId);
    }
}

using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.ChangeFeed;

// Set up Change Feed processor
Container leaseContainer = database.GetContainer("leases");
Container monitoredContainer = database.GetContainer("orders");

ChangeFeedProcessor changeFeedProcessor = monitoredContainer
    .GetChangeFeedProcessorBuilder<Order>("orderProcessor", HandleChangesAsync)
    .WithInstanceName("instance1")
    .WithLeaseContainer(leaseContainer)
    .WithStartTime(DateTime.UtcNow)
    .Build();

await changeFeedProcessor.StartAsync();

async Task HandleChangesAsync(IReadOnlyCollection<Order> changes, CancellationToken cancellationToken)
{
    foreach (var order in changes)
    {
        // Process each change (e.g., send to Event Hub)
        await ProcessOrderAsync(order);
    }
}

using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Fluent;

// Client with preferred regions for reads
CosmosClient client = new CosmosClientBuilder("<connection-string>")
    .WithApplicationPreferredRegions(new List<string> { "West US", "East US" })
    .Build();

// Read from nearest region
Order order = await container.ReadItemAsync<Order>("order-123", new PartitionKey("customer-456"));

// Write always goes to primary region (single-write mode)