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

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.