Azure Cosmos DB SDK for Java

Client library for Azure Cosmos DB NoSQL API with global distribution and reactive patterns.

Installation

<dependency> <groupId>com.azure</groupId> <artifactId>azure-cosmos</artifactId> <version>LATEST</version> </dependency>

Or use Azure SDK BOM:

<dependencyManagement> <dependencies> <dependency> <groupId>com.azure</groupId> <artifactId>azure-sdk-bom</artifactId> <version>{bom_version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

<dependencies> <dependency> <groupId>com.azure</groupId> <artifactId>azure-cosmos</artifactId> </dependency> </dependencies>

Environment Variables

COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/ COSMOS_KEY=<your-primary-key>

Authentication

Key-based Authentication

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

Async Client

import com.azure.cosmos.CosmosAsyncClient;

CosmosAsyncClient asyncClient = new CosmosClientBuilder() .endpoint(serviceEndpoint) .key(key) .buildAsyncClient();

With Customizations

import com.azure.cosmos.ConsistencyLevel; import java.util.Arrays;

CosmosClient client = new CosmosClientBuilder() .endpoint(serviceEndpoint) .key(key) .directMode(directConnectionConfig, gatewayConnectionConfig) .consistencyLevel(ConsistencyLevel.SESSION) .connectionSharingAcrossClientsEnabled(true) .contentResponseOnWriteEnabled(true) .userAgentSuffix("my-application") .preferredRegions(Arrays.asList("West US", "East US")) .buildClient();

Client Hierarchy

Class Purpose

CosmosClient / CosmosAsyncClient

Account-level operations

CosmosDatabase / CosmosAsyncDatabase

Database operations

CosmosContainer / CosmosAsyncContainer

Container/item operations

Core Workflow

Create Database

// Sync client.createDatabaseIfNotExists("myDatabase") .map(response -> client.getDatabase(response.getProperties().getId()));

// Async with chaining asyncClient.createDatabaseIfNotExists("myDatabase") .map(response -> asyncClient.getDatabase(response.getProperties().getId())) .subscribe(database -> System.out.println("Created: " + database.getId()));

Create Container

asyncClient.createDatabaseIfNotExists("myDatabase") .flatMap(dbResponse -> { String databaseId = dbResponse.getProperties().getId(); return asyncClient.getDatabase(databaseId) .createContainerIfNotExists("myContainer", "/partitionKey") .map(containerResponse -> asyncClient.getDatabase(databaseId) .getContainer(containerResponse.getProperties().getId())); }) .subscribe(container -> System.out.println("Container: " + container.getId()));

CRUD Operations

import com.azure.cosmos.models.PartitionKey;

CosmosAsyncContainer container = asyncClient .getDatabase("myDatabase") .getContainer("myContainer");

// Create container.createItem(new User("1", "John Doe", "john@example.com")) .flatMap(response -> { System.out.println("Created: " + response.getItem()); // Read return container.readItem( response.getItem().getId(), new PartitionKey(response.getItem().getId()), User.class); }) .flatMap(response -> { System.out.println("Read: " + response.getItem()); // Update User user = response.getItem(); user.setEmail("john.doe@example.com"); return container.replaceItem( user, user.getId(), new PartitionKey(user.getId())); }) .flatMap(response -> { // Delete return container.deleteItem( response.getItem().getId(), new PartitionKey(response.getItem().getId())); }) .block();

Query Documents

import com.azure.cosmos.models.CosmosQueryRequestOptions; import com.azure.cosmos.util.CosmosPagedIterable;

CosmosContainer container = client.getDatabase("myDatabase").getContainer("myContainer");

String query = "SELECT * FROM c WHERE c.status = @status"; CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();

CosmosPagedIterable<User> results = container.queryItems( query, options, User.class );

results.forEach(user -> System.out.println("User: " + user.getName()));

Key Concepts

Partition Keys

Choose a partition key with:

• High cardinality (many distinct values)

• Even distribution of data and requests

• Frequently used in queries

Consistency Levels

Level Guarantee

Strong Linearizability

Bounded Staleness Consistent prefix with bounded lag

Session Consistent prefix within session

Consistent Prefix Reads never see out-of-order writes

Eventual No ordering guarantee

Request Units (RUs)

All operations consume RUs. Check response headers:

CosmosItemResponse<User> response = container.createItem(user); System.out.println("RU charge: " + response.getRequestCharge());

Best Practices

• Reuse CosmosClient — Create once, reuse throughout application

• Use async client for high-throughput scenarios

• Choose partition key carefully — Affects performance and scalability

• Enable content response on write for immediate access to created items

• Configure preferred regions for geo-distributed applications

• Handle 429 errors with retry policies (built-in by default)

• Use direct mode for lowest latency in production

Error Handling

import com.azure.cosmos.CosmosException;

try { container.createItem(item); } catch (CosmosException e) { System.err.println("Status: " + e.getStatusCode()); System.err.println("Message: " + e.getMessage()); System.err.println("Request charge: " + e.getRequestCharge());

if (e.getStatusCode() == 409) {
    System.err.println("Item already exists");
} else if (e.getStatusCode() == 429) {
    System.err.println("Rate limited, retry after: " + e.getRetryAfterDuration());
}

}

Reference Links

Resource URL

Maven Package https://central.sonatype.com/artifact/com.azure/azure-cosmos

API Documentation https://azuresdkdocs.z19.web.core.windows.net/java/azure-cosmos/latest/index.html

Product Docs https://learn.microsoft.com/azure/cosmos-db/

Samples https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples

Performance Guide https://learn.microsoft.com/azure/cosmos-db/performance-tips-java-sdk-v4-sql

Troubleshooting https://learn.microsoft.com/azure/cosmos-db/troubleshoot-java-sdk-v4-sql