cosmosdb-frameworks

Azure Cosmos DB Framework Patterns

.NET SDK (Microsoft.Azure.Cosmos)

Best Practices

• Use ConnectionMode.Direct for lowest latency
• Enable AllowBulkExecution for batch operations
• Use CosmosPropertyNamingPolicy.CamelCase for JSON serialization
• Always check RequestCharge on responses for RU monitoring
• Use PartitionKey explicitly — never rely on auto-extraction
• Dispose CosmosClient at application shutdown, not per request (singleton)

Container Operations

// Create database and container
await client.CreateDatabaseIfNotExistsAsync("orderdb");
await database.CreateContainerIfNotExistsAsync(
    new ContainerProperties("orders", "/customerId")
    {
        DefaultTimeToLive = -1, // TTL enabled, no default expiry
        IndexingPolicy = new IndexingPolicy
        {
            CompositeIndexes = {
                new Collection<CompositePath> {
                    new CompositePath { Path = "/status", Order = CompositePathSortOrder.Ascending },
                    new CompositePath { Path = "/createdAt", Order = CompositePathSortOrder.Descending }
                }
            }
        }
    },
    throughput: 400);

Node.js SDK (@azure/cosmos)

Best Practices

• Use environment variables for connection details
• Use parameterized queries — never string-concatenate values
• Use fetchAll() for small result sets, fetchNext() for pagination
• Monitor requestCharge on all responses

Batch Operations

const operations = orders.map(order => ({
  operationType: "Create",
  resourceBody: order,
}));

const response = await container.items.batch(operations, partitionKey);

Python SDK (azure-cosmos)

Best Practices

• Use enable_cross_partition_query=True only when necessary (expensive)
• Use partition_key parameter to scope queries to single partition
• Use max_item_count for pagination control
• Handle CosmosHttpResponseError for retry logic

Custom Migrations

Migration Runner Pattern

public class CosmosDbMigrationRunner
{
    private readonly Container _container;
    private readonly Container _migrationContainer;

    public async Task RunMigrationsAsync(IEnumerable<ICosmosDbMigration> migrations)
    {
        var applied = await GetAppliedMigrationsAsync();
        foreach (var migration in migrations.OrderBy(m => m.Version))
        {
            if (applied.Contains(migration.Version)) continue;

            await migration.UpAsync(_container);
            await RecordMigrationAsync(migration);
        }
    }
}

Infrastructure Migrations (Indexing Policy)

// Update indexing policy via SDK
var containerResponse = await container.ReadContainerAsync();
var properties = containerResponse.Resource;
properties.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/largeField/?" });
await container.ReplaceContainerAsync(properties);