azure-cosmos-java
Azure Cosmos DB SDK for Java. NoSQL database operations with global distribution, multi-model support, and reactive patterns. Triggers: "CosmosClient java", "CosmosAsyncClient", "cosmos database java", "cosmosdb java", "document database java".
Install
npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-java/skills/azure-cosmos-java
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
git clone https://github.com/microsoft/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 |
Files (skills)
-
references
-
examples.md 11.7 KB
Loading…
-
-
SKILL.md 7.3 KB
--- name: azure-cosmos-java description: | Azure Cosmos DB SDK for Java. NoSQL database operations with global distribution, multi-model support, and reactive patterns. Triggers: "CosmosClient java", "CosmosAsyncClient", "cosmos database java", "cosmosdb java", "document database java". license: MIT metadata: author: Microsoft version: "1.0.0" package: azure-cosmos --- # Azure Cosmos DB SDK for Java Client library for Azure Cosmos DB NoSQL API with global distribution and reactive patterns. ## Installation ```xml <dependency> <groupId>com.azure</groupId> <artifactId>azure-cosmos</artifactId> <version>LATEST</version> </dependency> ``` Or use Azure SDK BOM: ```xml <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 ```bash COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/ COSMOS_KEY=<your-primary-key> ``` ## Authentication ### Key-based Authentication ```java 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 ```java import com.azure.cosmos.CosmosAsyncClient; CosmosAsyncClient asyncClient = new CosmosClientBuilder() .endpoint(serviceEndpoint) .key(key) .buildAsyncClient(); ``` ### With Customizations ```java 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 ```java // 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 ```java 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 ```java 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 ```java 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: ```java CosmosItemResponse<User> response = container.createItem(user); System.out.println("RU charge: " + response.getRequestCharge()); ``` ## Best Practices 1. **Reuse CosmosClient** — Create once, reuse throughout application 2. **Use async client** for high-throughput scenarios 3. **Choose partition key carefully** — Affects performance and scalability 4. **Enable content response on write** for immediate access to created items 5. **Configure preferred regions** for geo-distributed applications 6. **Handle 429 errors** with retry policies (built-in by default) 7. **Use direct mode** for lowest latency in production ## Error Handling ```java 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 |
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.