MSDN

Getting Started with Azure Cosmos DB SDK for Java

Welcome to the Azure Cosmos DB Java SDK getting started guide. This document will walk you through the essential steps to begin developing applications that leverage the power and scalability of Azure Cosmos DB using the official Java SDK.

Prerequisites

Before you begin, ensure you have the following installed:

• Java Development Kit (JDK): Version 8 or higher.
• Maven or Gradle: For dependency management.
• An Azure Subscription: To create and manage your Azure Cosmos DB resources.
• An Azure Cosmos DB Account: You can create one from the Azure portal.

Step 1: Set Up Your Development Environment

This guide assumes you are using Maven for dependency management. If you are using Gradle, the dependency declaration will be slightly different.

Add the Cosmos DB Dependency

Open your project's pom.xml file and add the following dependency:

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

If you are using Gradle, add this to your build.gradle file:

                    
implementation 'com.azure:azure-cosmos:4.42.0'
                    
                

Step 2: Connect to Your Azure Cosmos DB Account

To connect to your Cosmos DB account, you will need its endpoint URI and its primary key. You can find these in the Azure portal under your Cosmos DB account's "Keys" section.

Initialize the CosmosClient

You'll typically create a single instance of CosmosClient for your application's lifetime.

                    
import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;

public class CosmosDbConnection {

    // Replace with your actual endpoint and key
    private static final String ENDPOINT = "YOUR_COSMOS_DB_ENDPOINT";
    private static final String PRIMARY_KEY = "YOUR_COSMOS_DB_PRIMARY_KEY";

    public static void main(String[] args) {
        CosmosClient client = new CosmosClientBuilder()
                .endpoint(ENDPOINT)
                .key(PRIMARY_KEY)
                .buildClient();

        System.out.println("Cosmos DB client initialized successfully!");

        // ... your database and container operations will go here ...

        client.close(); // Close the client when your application exits
    }
}
                    
                

Step 3: Interact with Databases and Containers

Once connected, you can start creating and interacting with databases and containers.

Creating a Database and Container (if they don't exist)

The SDK provides fluent APIs for managing resources. This example demonstrates creating a database and a container.

                    
import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.CosmosDatabase;
import com.azure.cosmos.models.CosmosContainerResponse;
import com.azure.cosmos.models.CosmosDatabaseResponse;
import com.azure.cosmos.models.ThroughputProperties;

public class CosmosDbSetup {

    private static final String ENDPOINT = "YOUR_COSMOS_DB_ENDPOINT";
    private static final String PRIMARY_KEY = "YOUR_COSMOS_DB_PRIMARY_KEY";
    private static final String DATABASE_ID = "ToDoList";
    private static final String CONTAINER_ID = "Items";

    public static void main(String[] args) {
        CosmosClient client = new CosmosClientBuilder()
                .endpoint(ENDPOINT)
                .key(PRIMARY_KEY)
                .buildClient();

        // Create database if it doesn't exist
        CosmosDatabase database = client.createDatabaseIfNotExists(DATABASE_ID).getDatabase();
        System.out.println("Database '" + database.getId() + "' created or already exists.");

        // Create container if it doesn't exist
        // Define a partition key for your container. This is crucial for scalability.
        CosmosContainerResponse containerResponse = database.createContainerIfNotExists(
            CONTAINER_ID, "/category").block(); // Example partition key '/category'

        System.out.println("Container '" + containerResponse.getContainer().getId() + "' created or already exists.");

        client.close();
    }
}
                    
                

Next Steps

You've successfully set up your environment and established a connection. Now you're ready to:

• Explore Setup and Installation in detail.
• Learn how to perform CRUD (Create, Read, Update, Delete) operations.
• Understand how to query your data efficiently.