Integrate Java Apps with Azure Cosmos DB

Azure Cosmos DB SDK for Java is a skill for the azure-cosmos client library covering Cosmos DB's NoSQL API, global distribution, and reactive programming patterns. It's installed via Maven (com.azure:azure-cosmos, or through the Azure SDK BOM for managed versioning), authenticated with COSMOS_ENDPOINT/COSMOS_KEY environment variables:

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;

CosmosClient client = new CosmosClientBuilder()
    .endpoint(System.getenv("COSMOS_ENDPOINT"))
    .key(System.getenv("COSMOS_KEY"))
    .buildClient();

Use it when building on Cosmos DB's NoSQL API in Java, whether synchronously (CosmosClient) or asynchronously (CosmosAsyncClient) via reactive chaining. The client can be customized with directMode/gatewayConnectionConfig, a ConsistencyLevel, connection sharing across clients, content-response-on-write, a user-agent suffix, and preferredRegions for geo-distributed apps. The client hierarchy follows account (CosmosClient) to database (CosmosDatabase) to container/item (CosmosContainer) operations. It is not the tool for other Cosmos DB APIs (MongoDB, Cassandra, Gremlin) - this SDK targets the NoSQL API specifically.

Core workflow: createDatabaseIfNotExists sets up the database, and createContainerIfNotExists (taking a partition key path like /partitionKey) sets up the container - on the async client these chain via flatMap/map/subscribe to fetch the resulting CosmosAsyncDatabase/CosmosAsyncContainer handles once creation completes. CRUD then runs through createItem, readItem, replaceItem, and deleteItem, each scoped by a PartitionKey, and on the async client these calls are chained together (create, then read the same item back, update a field, then delete) before a final .block(). Queries use queryItems with a SQL-like string (SELECT * FROM c WHERE c.status = @status) and CosmosQueryRequestOptions, returning a CosmosPagedIterable that can be iterated directly. Every operation consumes Request Units, readable via response.getRequestCharge(). Partition keys should be chosen for high cardinality, even data/request distribution, and frequent use in queries. Cosmos DB's five consistency levels - Strong, Bounded Staleness, Session, Consistent Prefix, and Eventual - trade off linearizability guarantees against latency and cost.

Errors surface as CosmosException, exposing status code, message, and request charge; the skill specifically calls out handling HTTP 409 (item already exists) and 429 (rate limited, with a getRetryAfterDuration() for backoff, though retry policies are built in by default). Its best practices: create and reuse one CosmosClient for the application's lifetime rather than per-operation, prefer the async client for high-throughput scenarios, enable content-response-on-write for immediate access to created items, configure preferred regions for geo-distributed deployments, and use direct mode for the lowest production latency.

Java developers building on Cosmos DB's NoSQL API who need the right client configuration (sync vs async, consistency level, regions), partition-key strategy, and RU-aware error handling for production workloads.