GitHub Copilot ChatGPT Claude Codex CLI Cursor opencode Skill Text

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".

Ciza · 0 points · 21 views 0 listing impressions 0 install-command copies
Download microsoft-skills-.github_plugins_azure-sdk-java_skills_azure-cosmos-java-e58528d.zip · 5 KB

Install

skills CLI npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-java/skills/azure-cosmos-java
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
Git 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

  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

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.

No comments yet.

Reviews (0)

No reviews yet.