What's changed: Created DP-420 Chapter 2 (Domain 1 second-half: SDK client connectivity (gateway vs direct/singleton/emulator/preferred regions/429-transient retries); SQL queries and data access (arrays-nesting-aggregation-subqueries-functions/point op vs query/patch/Transactional Batch/Bulk/ETag optimistic concurrency/consistency override-session token/pagination-continuation token/query metrics); server-side JS (stored procedure = ACID in one logical partition/pre-post triggers/UDF)).
2.1SDK client connectivity
Understand Azure Cosmos DB SDK connectivity modes (gateway vs direct), client singleton, offline development with the emulator, connection error handling, region selection, and SDK logging.
Apps access data via the Azure Cosmos DB SDK (.NET/Java, etc.). How you connect and handle the client directly affects latency, throughput, and cost.
2.1.1Connectivity modes and singleton
There are two connectivity modes: gateway uses HTTPS (443) through a gateway—easy through firewalls with fewer connections but slightly higher latency; direct connects over TCP straight to replicas—low latency, high throughput, recommended for production (needs more ports/connections). Reuse one CosmosClient app-wide (singleton): it caches connections/metadata; creating one per request degrades performance and wastes connections.
2.1.2Emulator, regions, and error handling
The Cosmos DB emulator simulates the service locally for offline development/testing without cloud billing. For global distribution, set preferred regions (ApplicationPreferredRegions) in the SDK to read from the nearest region and fail over to the next on failure. Handle transient errors and 429 (rate limiting) with the SDK’s built-in retries (retry policy); for 429, wait per Retry-After before retrying. Enable SDK logging to diagnose.
Cues: "low-latency, high-throughput production" = direct mode. "through firewalls, fewer connections" = gateway. Reuse CosmosClient as a singleton. Offline dev = emulator. "read nearest/failover" = preferred regions. 429/transient = SDK retries.
Watch the mix-ups: (1) Direct (performance, needs open ports) vs gateway (easy, higher latency). (2) Do not create CosmosClient per request (singleton). (3) Absorb 429 via SDK retries—do not swallow; honor Retry-After. (4) Without preferred regions, you may be pinned to the write region, increasing latency.
2.1.3Section summary
- Connectivity = direct (low latency, prod) / gateway (firewall-friendly); CosmosClient as a singleton
- Emulator for offline dev; preferred regions for nearest read/failover
- Handle 429/transient errors with SDK retries (honor Retry-After)
Sign in to track progress — Log in.
Quick check
(just a quick review)Q1. In production you want the lowest latency and highest throughput connecting to Cosmos DB. Best connectivity mode?
Q2. Which is correct for managing CosmosClient instances?
Q3. You want to simulate Cosmos DB locally without cloud billing for offline dev/test. Best?
Q4. When 429s are returned for exceeding provisioned RU, what is the correct handling in an SDK app?
Q5. In a globally distributed setup, you want the app to read from the nearest region and fail over to the next on failure. Best?