Microsoft Azure — Cosmos DB (Global NoSQL)

The Cosmos DB SDK is your interface to the service. Use the latest version (v3 for .NET). Key practices: use a singleton client instance (it's thread-safe and manages connections), enable Direct mode (TCP) for lower latency, and configure retry policies. The SDK retries on 429 (throttling) automatically, but you can customize MaxRetryAttemptsOnThrottledRequests and MaxRetryWaitTimeOnThrottledRequests. For production, set these to high values (e.g., 9 retries, 30 seconds wait) to handle spikes. Also, use ApplicationRegion to pin the client to the nearest region. Avoid creating a new client per request—this exhausts connections and causes failures.

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);
    }
}

Change Feed: Real-time Data Pipelines

The Change Feed is an ordered, persistent log of all changes to a container. It's the foundation for event-driven architectures, real-time analytics, and data replication. You can consume it via Azure Functions (Cosmos DB trigger), the SDK, or Azure Data Factory. The Change Feed is partitioned by physical partition, so you need to process each partition in parallel for high throughput. Important: the Change Feed is not a queue; it's a log. If you fall behind, you can catch up, but you'll pay RU to read old changes. Use a lease container to track state. In production, monitor the Change Feed lag and scale out your processor instances.

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);
    }
}

Multi-Region Deployment: Active-Active vs. Active-Passive

Cosmos DB supports two multi-region configurations: single-write region (active-passive) and multi-write regions (active-active). Active-passive is simpler: all writes go to one region, reads can go to any. Failover is manual or automatic. Active-active allows writes in any region, but requires conflict resolution. Cosmos DB provides last-writer-wins (LWW) or custom conflict resolution. In production, start with active-passive unless you need sub-second failover or local writes. Active-active increases complexity and cost. Always test failover: simulate a region outage and measure recovery time. Use Azure Traffic Manager or Front Door for global load balancing.

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)

Integrated Cache: Reduce RU Costs for Read-Heavy Workloads

The Azure Cosmos DB integrated cache is an in-memory cache that runs on the dedicated gateway, reducing RU consumption for repeated point reads and queries. Cache hits have zero RU charge — you only pay for the first read from the backend. The cache uses a Least Recently Used (LRU) eviction policy and is split into two parts: the item cache (for point reads by ID and partition key) and the query cache (for query results as key/value pairs). Key configuration: set MaxIntegratedCacheStaleness per request (default 5 minutes, max 10 years) to control how stale cached data can be. Higher values increase cache hit rates. Consistency must be session or eventual for reads to use the cache — Strong, Bounded Staleness, and Consistent Prefix bypass it. The dedicated gateway cluster size determines cache capacity. Monitor cache hit rates via IntegratedCacheItemHitRate and IntegratedCacheQueryHitRate metrics. If eviction counts (IntegratedCacheEvictedEntriesSize) are high, increase gateway size. If CPU or memory on the dedicated gateway is high, add more nodes. Use the bypass integrated cache request option for infrequent reads to avoid polluting the cache. The integrated cache is ideal for: read-heavy workloads with repeated queries on hot partitions, large items where point reads are expensive, and high-RU queries that execute frequently. It's not suitable for write-heavy workloads or rarely repeated reads. In production, always start with a small dedicated gateway and scale up based on hit rate metrics.

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

// Create client using dedicated gateway connection string
CosmosClient client = new CosmosClientBuilder("<dedicated-gateway-connection-string>")
    .WithApplicationRegion("East US")
    .WithConnectionModeGateway()
    .Build();

// Point read with MaxIntegratedCacheStaleness of 2 hours
ItemRequestOptions requestOptions = new ItemRequestOptions
{
    ConsistencyLevel = ConsistencyLevel.Session,
    MaxIntegratedCacheStaleness = TimeSpan.FromHours(2)
};

// If cached, RU charge is 0
Order order = await container.ReadItemAsync<Order>("order-123",
    new PartitionKey("customer-456"), requestOptions);

// Bypass cache for infrequent reads
ItemRequestOptions bypassCacheOptions = new ItemRequestOptions
{
    BypassIntegratedCache = true
};

Order freshOrder = await container.ReadItemAsync<Order>("order-789",
    new PartitionKey("customer-456"), bypassCacheOptions);

Global Secondary Indexes (GSI): Cross-Partition Query Optimization

Global Secondary Indexes (GSIs) for Azure Cosmos DB, now generally available (Build 2026), let you optimize query performance across partitions without redesigning your data model or changing application code. Traditionally, Cosmos DB queries across partitions required fan-out queries that touched every physical partition, consuming significant RU and causing higher latency. GSIs create a separate index structure that spans partitions, enabling efficient lookups on non-partition-key fields. For example, if your container is partitioned by userId but you frequently query by orderDate or status, a GSI on orderDate allows efficient querying without a cross-partition fan-out. GSIs are maintained asynchronously — there is a brief replication lag from the source container to the index. They support point lookups, range queries, and sorting on the indexed fields. Key considerations: GSIs consume additional RU/s for index maintenance (writes become more expensive), require additional storage (roughly 10-20% of source data size), and have a maximum of 5 GSIs per container. Choose GSI fields carefully — they work best for fields with high selectivity (filter to a small percentage of total data). In production, start with 1-2 GSIs on your most common query patterns. Monitor GSI storage consumption and index sync lag via Azure Monitor. For queries that can use the partition key, prefer the primary partition key over a GSI — partition-key-scoped queries are always more efficient.

using Microsoft.Azure.Cosmos;

// Define a container with a Global Secondary Index
ContainerProperties containerProperties = new ContainerProperties
{
    Id = "orders",
    PartitionKeyPath = "/userId",
    GlobalSecondaryIndexes = new List<GlobalSecondaryIndex>
    {
        new GlobalSecondaryIndex
        {
            Name = "status-index",
            IndexingPolicy = new IndexingPolicy
            {
                IncludedPaths = new List<IncludedPath>
                {
                    new IncludedPath { Path = "/status/?" }
                }
            }
        },
        new GlobalSecondaryIndex
        {
            Name = "orderDate-index",
            IndexingPolicy = new IndexingPolicy
            {
                IncludedPaths = new List<IncludedPath>
                {
                    new IncludedPath { Path = "/orderDate/?" }
                }
            }
        }
    }
};

// Query using GSI (no cross-partition fan-out)
QueryDefinition query = new QueryDefinition(
    "SELECT * FROM orders o WHERE o.status = @status");
query.WithParameter("@status", "shipped");

using FeedIterator<Order> iterator = container.GetItemQueryIterator<Order>(query);

Cosmos DB for AI: Vector Search, Semantic Reranking, and Agent Memory

At Microsoft Build 2026, Cosmos DB announced several AI-focused capabilities making it a strong choice for RAG (Retrieval-Augmented Generation) and AI agent workloads. DiskANN vector indexing (GA for MongoDB vCore) enables high-performance vector search on large-scale datasets (>1M documents) using SSD-optimized indexing with Product Quantization for compression and support for vectors up to 16,000 dimensions. Filtered Vector Search applies standard MongoDB query filters ($eq, $in, $geoWithin) before vector search, combining semantic relevance with operational filtering. Semantic Reranking (public preview) uses an AI model to re-rank initial search results based on semantic context, improving result quality for RAG applications — integrated with .NET, Python, and JavaScript SDKs with minimal code changes. The MCP (Model Context Protocol) Toolkit (GA) enables developers to expose Cosmos DB data to AI agents via the emerging MCP standard. The Agent Memory Toolkit (public preview) provides durable memory patterns for AI agents using Cosmos DB as the persistent storage layer. The Azure Cosmos DB Linux Emulator (GA) allows local development and CI/CD testing without a cloud deployment. In production, use Cosmos DB as the vector store for AI applications: store embeddings alongside operational data in the same container, use DiskANN for large-scale vector search, and apply hybrid search (vector + full-text + filters) for highest relevance. Configure Cosmos DB's integrated vector search with your preferred embedding model (OpenAI, Azure AI, or custom).

const { CosmosClient } = require('@azure/cosmos');

const client = new CosmosClient({
  endpoint: process.env.COSMOS_ENDPOINT,
  key: process.env.COSMOS_KEY
});

const container = client.database('ai-db').container('documents');

// Vector search with DiskANN (requires MongoDB vCore API)
// Equivalent MongoDB command:
// db.documents.aggregate([
//   {
//     $search: {
//       "index": "vector-index",
//       "knn": {
//         "vector": [0.1, 0.2, ...],
//         "path": "embedding",
//         "k": 10,
//         "filter": { "category": "technical" }
//       }
//     }
//   }
// ]);

// Hybrid search with semantic reranking
// Using the MCP Toolkit for AI agent integration
const searchResults = await container.items.query({
  query: `
    SELECT TOP 10 c.id, c.title, c.content,
      RERANK(c.content, @query) AS relevance_score
    FROM c
    WHERE VectorDistance(c.embedding, @embedding) < 0.5
    ORDER BY relevance_score DESC
  `,
  parameters: [
    { name: "@query", value: "how to configure Cosmos DB indexing" },
    { name: "@embedding", value: [0.1, 0.2, /* ... */] }
  ]
}).fetchAll();