Best practices for the Azure Cosmos DB SDK across .NET, Java, Python, Go, and Spring Boot, plus local development and emulator tooling.
When to Apply
Reference these guidelines when configuring the Azure Cosmos DB SDK in .NET, Java, Python, Go, or Spring Boot, or setting up local development tooling.
Rules
SDK Best Practices
- sdk-async-api - Use Async APIs for Better Throughput
- sdk-availability-strategy - Configure Threshold-Based Availability Strategy (Hedging)
- sdk-circuit-breaker - Configure Partition-Level Circuit Breaker
- sdk-conditional-create-etag - Use IfNoneMatchETag("*") for conditional creates to prevent duplicates
- sdk-connection-mode - Use Direct Connection Mode for Production
- sdk-continuation-token-null-guard - Guard against empty continuation tokens before calling byPage
- sdk-diagnostics - Log Diagnostics for Troubleshooting
- sdk-dotnet-cosmos-package-id - Use Microsoft.Azure.Cosmos package, not abandoned Azure.Cosmos
- sdk-dotnet-namespace-collision - Avoid Microsoft.Azure.Cosmos namespace collisions with domain models
- sdk-emulator-ssl - Configure SSL and connection mode for Cosmos DB Emulator
- sdk-etag-concurrency - Use ETags for optimistic concurrency on read-modify-write operations
- sdk-excluded-regions - Configure Excluded Regions for Dynamic Failover
- sdk-go-partition-key-metadata - Use current Go Cosmos DB SDK versions and explicit partition-key metadata
- sdk-java-content-response - Unwrap CosmosItemResponse and enable content response in Java SDK
- sdk-java-cosmos-config - Use dependent @Bean methods for Cosmos DB initialization in Spring Boot
- sdk-java-spring-boot-versions - Spring Boot and Java version compatibility for Cosmos DB SDK
- sdk-local-dev-config - Configure local development environment to avoid cloud connection conflicts
- sdk-newtonsoft-dependency - Explicitly reference Newtonsoft.Json package
- sdk-patch-counter-increment - Use the Patch API for atomic counter increments
- sdk-preferred-regions - Configure Preferred Regions for Availability
- sdk-python-async-deps - Include aiohttp When Using Python Async SDK
- sdk-request-options-per-call - Never share a single CosmosItemRequestOptions instance across multiple createItem calls
- sdk-retry-429 - Handle 429 Errors with Retry-After
- sdk-serialization-enums - Use consistent enum serialization between Cosmos SDK and application layer
- sdk-singleton-client - Reuse CosmosClient as Singleton
- sdk-spring-data-annotations - Annotate entities for Spring Data Cosmos with @Container, @PartitionKey, and String IDs
- sdk-spring-data-repository - Use CosmosRepository correctly and handle Iterable return types
Developer Tooling
- tooling-emulator-setup - Use Azure Cosmos DB Emulator for local development and testing
- tooling-vscode-extension - Use Azure Cosmos DB VS Code extension for routine inspection and management