Azure Cosmos Java

1---
2name: azure-cosmos-java
3description: |
4  Azure Cosmos DB SDK for Java. NoSQL database operations with global distribution, multi-model support, and reactive patterns.
5  Triggers: "CosmosClient java", "CosmosAsyncClient", "cosmos database java", "cosmosdb java", "document database java".
6package: azure-cosmos
7---
8 
9# Azure Cosmos DB SDK for Java
10 
11Client library for Azure Cosmos DB NoSQL API with global distribution and reactive patterns.
12 
13## Installation
14 
15```xml
16<dependency>
17    <groupId>com.azure</groupId>
18    <artifactId>azure-cosmos</artifactId>
19    <version>LATEST</version>
20</dependency>
21```
22 
23Or use Azure SDK BOM:
24 
25```xml
26<dependencyManagement>
27    <dependencies>
28        <dependency>
29            <groupId>com.azure</groupId>
30            <artifactId>azure-sdk-bom</artifactId>
31            <version>{bom_version}</version>
32            <type>pom</type>
33            <scope>import</scope>
34        </dependency>
35    </dependencies>
36</dependencyManagement>
37 
38<dependencies>
39    <dependency>
40        <groupId>com.azure</groupId>
41        <artifactId>azure-cosmos</artifactId>
42    </dependency>
43</dependencies>
44```
45 
46## Environment Variables
47 
48```bash
49COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/
50COSMOS_KEY=<your-primary-key>
51```
52 
53## Authentication
54 
55### Key-based Authentication
56 
57```java
58import com.azure.cosmos.CosmosClient;
59import com.azure.cosmos.CosmosClientBuilder;
60 
61CosmosClient client = new CosmosClientBuilder()
62    .endpoint(System.getenv("COSMOS_ENDPOINT"))
63    .key(System.getenv("COSMOS_KEY"))
64    .buildClient();
65```
66 
67### Async Client
68 
69```java
70import com.azure.cosmos.CosmosAsyncClient;
71 
72CosmosAsyncClient asyncClient = new CosmosClientBuilder()
73    .endpoint(serviceEndpoint)
74    .key(key)
75    .buildAsyncClient();
76```
77 
78### With Customizations
79 
80```java
81import com.azure.cosmos.ConsistencyLevel;
82import java.util.Arrays;
83 
84CosmosClient client = new CosmosClientBuilder()
85    .endpoint(serviceEndpoint)
86    .key(key)
87    .directMode(directConnectionConfig, gatewayConnectionConfig)
88    .consistencyLevel(ConsistencyLevel.SESSION)
89    .connectionSharingAcrossClientsEnabled(true)
90    .contentResponseOnWriteEnabled(true)
91    .userAgentSuffix("my-application")
92    .preferredRegions(Arrays.asList("West US", "East US"))
93    .buildClient();
94```
95 
96## Client Hierarchy
97 
98| Class | Purpose |
99|-------|---------|
100| `CosmosClient` / `CosmosAsyncClient` | Account-level operations |
101| `CosmosDatabase` / `CosmosAsyncDatabase` | Database operations |
102| `CosmosContainer` / `CosmosAsyncContainer` | Container/item operations |
103 
104## Core Workflow
105 
106### Create Database
107 
108```java
109// Sync
110client.createDatabaseIfNotExists("myDatabase")
111    .map(response -> client.getDatabase(response.getProperties().getId()));
112 
113// Async with chaining
114asyncClient.createDatabaseIfNotExists("myDatabase")
115    .map(response -> asyncClient.getDatabase(response.getProperties().getId()))
116    .subscribe(database -> System.out.println("Created: " + database.getId()));
117```
118 
119### Create Container
120 
121```java
122asyncClient.createDatabaseIfNotExists("myDatabase")
123    .flatMap(dbResponse -> {
124        String databaseId = dbResponse.getProperties().getId();
125        return asyncClient.getDatabase(databaseId)
126            .createContainerIfNotExists("myContainer", "/partitionKey")
127            .map(containerResponse -> asyncClient.getDatabase(databaseId)
128                .getContainer(containerResponse.getProperties().getId()));
129    })
130    .subscribe(container -> System.out.println("Container: " + container.getId()));
131```
132 
133### CRUD Operations
134 
135```java
136import com.azure.cosmos.models.PartitionKey;
137 
138CosmosAsyncContainer container = asyncClient
139    .getDatabase("myDatabase")
140    .getContainer("myContainer");
141 
142// Create
143container.createItem(new User("1", "John Doe", "john@example.com"))
144    .flatMap(response -> {
145        System.out.println("Created: " + response.getItem());
146        // Read
147        return container.readItem(
148            response.getItem().getId(),
149            new PartitionKey(response.getItem().getId()),
150            User.class);
151    })
152    .flatMap(response -> {
153        System.out.println("Read: " + response.getItem());
154        // Update
155        User user = response.getItem();
156        user.setEmail("john.doe@example.com");
157        return container.replaceItem(
158            user,
159            user.getId(),
160            new PartitionKey(user.getId()));
161    })
162    .flatMap(response -> {
163        // Delete
164        return container.deleteItem(
165            response.getItem().getId(),
166            new PartitionKey(response.getItem().getId()));
167    })
168    .block();
169```
170 
171### Query Documents
172 
173```java
174import com.azure.cosmos.models.CosmosQueryRequestOptions;
175import com.azure.cosmos.util.CosmosPagedIterable;
176 
177CosmosContainer container = client.getDatabase("myDatabase").getContainer("myContainer");
178 
179String query = "SELECT * FROM c WHERE c.status = @status";
180CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
181 
182CosmosPagedIterable<User> results = container.queryItems(
183    query,
184    options,
185    User.class
186);
187 
188results.forEach(user -> System.out.println("User: " + user.getName()));
189```
190 
191## Key Concepts
192 
193### Partition Keys
194 
195Choose a partition key with:
196- High cardinality (many distinct values)
197- Even distribution of data and requests
198- Frequently used in queries
199 
200### Consistency Levels
201 
202| Level | Guarantee |
203|-------|-----------|
204| Strong | Linearizability |
205| Bounded Staleness | Consistent prefix with bounded lag |
206| Session | Consistent prefix within session |
207| Consistent Prefix | Reads never see out-of-order writes |
208| Eventual | No ordering guarantee |
209 
210### Request Units (RUs)
211 
212All operations consume RUs. Check response headers:
213 
214```java
215CosmosItemResponse<User> response = container.createItem(user);
216System.out.println("RU charge: " + response.getRequestCharge());
217```
218 
219## Best Practices
220 
2211. **Reuse CosmosClient** — Create once, reuse throughout application
2222. **Use async client** for high-throughput scenarios
2233. **Choose partition key carefully** — Affects performance and scalability
2244. **Enable content response on write** for immediate access to created items
2255. **Configure preferred regions** for geo-distributed applications
2266. **Handle 429 errors** with retry policies (built-in by default)
2277. **Use direct mode** for lowest latency in production
228 
229## Error Handling
230 
231```java
232import com.azure.cosmos.CosmosException;
233 
234try {
235    container.createItem(item);
236} catch (CosmosException e) {
237    System.err.println("Status: " + e.getStatusCode());
238    System.err.println("Message: " + e.getMessage());
239    System.err.println("Request charge: " + e.getRequestCharge());
240    
241    if (e.getStatusCode() == 409) {
242        System.err.println("Item already exists");
243    } else if (e.getStatusCode() == 429) {
244        System.err.println("Rate limited, retry after: " + e.getRetryAfterDuration());
245    }
246}
247```
248 
249## Reference Links
250 
251| Resource | URL |
252|----------|-----|
253| Maven Package | https://central.sonatype.com/artifact/com.azure/azure-cosmos |
254| API Documentation | https://azuresdkdocs.z19.web.core.windows.net/java/azure-cosmos/latest/index.html |
255| Product Docs | https://learn.microsoft.com/azure/cosmos-db/ |
256| Samples | https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples |
257| Performance Guide | https://learn.microsoft.com/azure/cosmos-db/performance-tips-java-sdk-v4-sql |
258| Troubleshooting | https://learn.microsoft.com/azure/cosmos-db/troubleshoot-java-sdk-v4-sql |
259