Java SDK for Azure Cosmos DB

Welcome to the official documentation for the Azure Cosmos DB Java SDK. This SDK provides a robust and efficient way to interact with your Azure Cosmos DB databases from your Java applications.

Getting Started

Before you begin, ensure you have the following:

  • An Azure subscription.
  • An Azure Cosmos DB account.
  • Java Development Kit (JDK) version 8 or later.
  • A build tool like Maven or Gradle.

Installation

You can add the Azure Cosmos DB Java SDK to your project using Maven or Gradle.

Maven

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.46.0</version><!-- Check for the latest version -->
</dependency>

Gradle

implementation 'com.azure:azure-cosmos:4.46.0' // Check for the latest version

Core Concepts

Azure Cosmos DB is a globally distributed, multi-model database service. The Java SDK allows you to perform the following operations:

  • Create and manage databases and containers.
  • Perform CRUD (Create, Read, Update, Delete) operations on items.
  • Execute complex SQL queries.
  • Manage consistency levels for your read operations.
  • Handle high availability and failover scenarios.

Common Operations

Here's a basic example of how to connect to your Cosmos DB account and perform a simple operation:

import com.azure.cosmos.*;
import com.azure.cosmos.models.*;
import com.azure.cosmos.util.*;

public class SampleApp {

    private static final String ENDPOINT = System.getProperty("COSMOS_DB_ENDPOINT");
    private static final String PRIMARY_KEY = System.getProperty("COSMOS_DB_PRIMARY_KEY");
    private static final String DATABASE_ID = "MyDatabase";
    private static final String CONTAINER_ID = "MyContainer";

    public static void main(String[] args) {
        // Initialize Cosmos client
        CosmosClient client = new CosmosClientBuilder()
            .endpoint(ENDPOINT)
            .key(PRIMARY_KEY)
            .gatewayMode(GatewayConnectionMode.DIRECT) // Use DIRECT mode for performance
            .buildClient();

        // Get a database object
        CosmosDatabase database = client.getDatabase(DATABASE_ID);

        // Get a container object
        CosmosContainer container = database.getContainer(CONTAINER_ID);

        // Create a sample item
        SampleItem item = new SampleItem("1", "HelloWorld");
        container.createItem(item);

        System.out.println("Item created successfully!");

        // Read the item
        CosmosItemResponse response = container.readItem("1", new PartitionKey("1"), SampleItem.class);
        SampleItem retrievedItem = response.getItem();
        System.out.println("Retrieved item: " + retrievedItem);

        // Close the client
        client.close();
    }

    // Define a sample POJO class
    static class SampleItem {
        private String id;
        private String name;

        public SampleItem(String id, String name) {
            this.id = id;
            this.name = name;
        }

        public String getId() { return id; }
        public void setId(String id) { this.id = id; }
        public String getName() { return name; }
        public void setName(String name) { this.name = name; }

        @Override
        public String toString() {
            return "SampleItem{" +
                   "id='" + id + '\'' +
                   ", name='" + name + '\'' +
                   '}';
        }
    }
}

API Reference

For a comprehensive list of classes, methods, and their usage, please refer to the Java SDK API Reference.

Further Reading