What is the Cosmos DB SDK and what are the key client configuration options?

The Azure Cosmos DB SDK is the official client library for interacting with Cosmos DB programmatically. Microsoft provides first-party SDKs for .NET, Java, Python, JavaScript/Node.js, and Go. Each SDK wraps the underlying REST API with connection pooling, retry logic, serialization, and Cosmos-specific patterns like bulk execution and change feed processing.

The root object in each SDK is the CosmosClient (or equivalent), which is expensive to initialize — it opens TCP connections to every data node and fetches the cluster routing table. CosmosClient should be created once per application lifetime and reused (singleton pattern). Creating it per request causes severe performance degradation and connection exhaustion.

Key configuration options on the client:

• Connection mode: Direct (default for .NET/Java) — SDK opens TCP connections directly to backend data nodes, bypassing the gateway for data operations. Lower latency. Gateway — All requests go through the Cosmos DB HTTPS gateway. Compatible with restrictive firewalls, slightly higher latency.
• Consistency level: Override the account-level default per client. You can only weaken (not strengthen) consistency per request.
• MaxRetryAttemptsOnRateLimitedRequests: How many times to retry on 429 before surfacing an error to the caller. Default is 9.
• RequestTimeout: Total timeout for a single operation attempt.
• PreferredLocations: For multi-region accounts, the ordered list of regions to prefer for reads (nearest first for lowest latency).
• AllowBulkExecution: Enables bulk batch optimization.

CosmosClient client = new CosmosClientBuilder(endpoint, key)
    .WithConnectionModeDirect()
    .WithApplicationPreferredRegions(new[] { "East US", "West Europe" })
    .WithBulkExecution(true)
    .WithConsistencyLevel(ConsistencyLevel.Session)
    .Build();