Azure Cosmos DB SDKs

Access your Azure Cosmos DB data programmatically using our comprehensive suite of SDKs. These SDKs provide a rich and intuitive API for interacting with Azure Cosmos DB from your applications.

Azure Cosmos DB offers native SDKs for popular programming languages, allowing you to build robust applications with ease.

C# / .NET

                    
// Install the NuGet package:
// dotnet add package Microsoft.Azure.Cosmos

using System;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

public class CosmosDbExample
{
    // IMPORTANT: Replace with your actual endpoint and key
    private static readonly string EndpointUri = "YOUR_COSMOS_DB_ENDPOINT";
    private static readonly string PrimaryKey = "YOUR_COSMOS_DB_PRIMARY_KEY";
    private static readonly string DatabaseId = "YOUR_DATABASE_ID";
    private static readonly string ContainerId = "YOUR_CONTAINER_ID";

    private CosmosClient client;
    private Container container;

    public async Task InitializeAsync()
    {
        client = new CosmosClient(EndpointUri, PrimaryKey);
        Database database = await client.CreateDatabaseIfNotExistsAsync(DatabaseId);
        container = await database.CreateContainerIfNotExistsAsync(ContainerId, "/partitionKey");
    }

    public async Task CreateItemAsync(object item)
    {
        try
        {
            ItemResponse<object> createdItem = await container.CreateItemAsync(item, new PartitionKey("yourPartitionKeyValue"));
            Console.WriteLine($"Created item: {createdItem.Resource.Id}");
        }
        catch (CosmosException ex)
        {
            Console.WriteLine($"Error creating item: {ex.StatusCode}");
        }
    }

    public async Task<object> GetItemAsync(string id, string partitionKey)
    {
        try
        {
            ItemResponse<object> itemResponse = await container.ReadItemAsync<object>(id, new PartitionKey(partitionKey));
            Console.WriteLine($"Read item: {itemResponse.Resource.Id}");
            return itemResponse.Resource;
        }
        catch (CosmosException ex)
        {
            Console.WriteLine($"Error reading item: {ex.StatusCode}");
            return null;
        }
    }

    public static async Task Main(string[] args)
    {
        CosmosDbExample example = new CosmosDbExample();
        await example.InitializeAsync();

        var newItem = new { id = Guid.NewGuid().ToString(), category = "widget", name = "Super Widget", quantity = 10, partitionKey = "widget" };
        await example.CreateItemAsync(newItem);

        var retrievedItem = await example.GetItemAsync(newItem.id, "widget");
        if (retrievedItem != null)
        {
            Console.WriteLine("Successfully retrieved item.");
        }
    }
}
                    
                

Java

                    
// Maven dependency:
// <dependency>
//     <groupId>com.azure</groupId>
//     <artifactId>azure-cosmos</artifactId>
//     <version>4.17.0</version>
// </dependency>

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.CosmosDatabase;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.models.CosmosItemProperties;
import com.azure.cosmos.models.PartitionKey;
import com.azure.cosmos.util.CosmosPagedIterable;

import java.util.UUID;
import java.util.logging.Logger;

public class CosmosDbJavaExample {

    private static final Logger logger = Logger.getLogger(CosmosDbJavaExample.class.getName());

    // IMPORTANT: Replace with your actual endpoint and key
    private static final String ENDPOINT_URI = "YOUR_COSMOS_DB_ENDPOINT";
    private static final String PRIMARY_KEY = "YOUR_COSMOS_DB_PRIMARY_KEY";
    private static final String DATABASE_ID = "YOUR_DATABASE_ID";
    private static final String CONTAINER_ID = "YOUR_CONTAINER_ID";

    private CosmosClient client;
    private CosmosContainer container;

    public void initialize() {
        client = new CosmosClientBuilder()
                .endpoint(ENDPOINT_URI)
                .key(PRIMARY_KEY)
                .buildClient();

        CosmosDatabase database = client.createDatabaseIfNotExists(DATABASE_ID).getDatabase();
        container = database.createContainerIfNotExists(CONTAINER_ID, "/partitionKey").getContainer();
        logger.info("Cosmos DB initialized.");
    }

    public void createItem(Object item, String partitionKeyValue) {
        try {
            CosmosItemProperties response = container.createItem(item, new PartitionKey(partitionKeyValue), null).getItem();
            logger.info("Created item with ID: " + response.getId());
        } catch (Exception e) {
            logger.severe("Error creating item: " + e.getMessage());
        }
    }

    public Object getItem(String id, String partitionKey) {
        try {
            Object item = container.readItem(id, new PartitionKey(partitionKey), Object.class).getItem();
            logger.info("Retrieved item with ID: " + id);
            return item;
        } catch (Exception e) {
            logger.severe("Error retrieving item: " + e.getMessage());
            return null;
        }
    }

    public static void main(String[] args) {
        CosmosDbJavaExample example = new CosmosDbJavaExample();
        example.initialize();

        // Sample item
        class SampleItem {
            public String id;
            public String category;
            public String name;
            public int quantity;
            public String partitionKey;
        }

        SampleItem newItem = new SampleItem();
        newItem.id = UUID.randomUUID().toString();
        newItem.category = "gadget";
        newItem.name = "Mega Gadget";
        newItem.quantity = 25;
        newItem.partitionKey = "gadget";

        example.createItem(newItem, newItem.partitionKey);
        Object retrievedItem = example.getItem(newItem.id, newItem.partitionKey);

        if (retrievedItem != null) {
            logger.info("Successfully retrieved item.");
        }
    }
}
                    
                

Node.js

                    
// npm install @azure/cosmos

const { CosmosClient } = require("@azure/cosmos");

// IMPORTANT: Replace with your actual endpoint and key
const endpoint = "YOUR_COSMOS_DB_ENDPOINT";
const key = "YOUR_COSMOS_DB_PRIMARY_KEY";
const databaseId = "YOUR_DATABASE_ID";
const containerId = "YOUR_CONTAINER_ID";

const client = new CosmosClient({ endpoint, key });

async function initialize() {
    await client.databases.createIfNotExists({ id: databaseId });
    const { container } = await client.database(databaseId).containers.createIfNotExists({
        id: containerId,
        partitionKey: { paths: ["/partitionKey"] }
    });
    console.log(`Cosmos DB initialized. Container: ${containerId}`);
    return container;
}

async function createItem(container, item) {
    try {
        const { resource: createdItem } = await container.items.create(item);
        console.log(`Created item: ${createdItem.id}`);
    } catch (error) {
        console.error("Error creating item:", error.message);
    }
}

async function getItem(container, id, partitionKeyValue) {
    try {
        const { resource: item } = await container.item(id, partitionKeyValue).read();
        console.log(`Retrieved item: ${item.id}`);
        return item;
    } catch (error) {
        console.error("Error retrieving item:", error.message);
        return null;
    }
}

async function runExample() {
    const container = await initialize();

    const newItem = {
        id: require('uuid').v4(),
        category: "tool",
        name: "Power Wrench",
        quantity: 15,
        partitionKey: "tool"
    };

    await createItem(container, newItem);
    const retrievedItem = await getItem(container, newItem.id, newItem.partitionKey);

    if (retrievedItem) {
        console.log("Successfully retrieved item.");
    }
}

runExample().catch(console.error);
                    
                

Python

                    
# pip install azure-cosmos

import azure.cosmos.documents as documents
import azure.cosmos.cosmos_client as cosmos_client
import azure.cosmos.errors as errors
import uuid
import os

# IMPORTANT: Replace with your actual endpoint and key
ENDPOINT = "YOUR_COSMOS_DB_ENDPOINT"
PRIMARY_KEY = "YOUR_COSMOS_DB_PRIMARY_KEY"
DATABASE_ID = "YOUR_DATABASE_ID"
CONTAINER_ID = "YOUR_CONTAINER_ID"

client = cosmos_client.CosmosClient(ENDPOINT, {'masterKey': PRIMARY_KEY})

def initialize():
    try:
        database = client.CreateDatabase(body={'id': DATABASE_ID})
        print(f"Database '{DATABASE_ID}' created.")
    except errors.Conflict as e:
        print(f"Database '{DATABASE_ID}' already exists.")
        database = client.QueryDatabases().filter(lambda d: d['id'] == DATABASE_ID).first()

    try:
        container = database.CreateContainer(body={'id': CONTAINER_ID, 'partitionKey': {'paths': ['/partitionKey']}})
        print(f"Container '{CONTAINER_ID}' created.")
    except errors.Conflict as e:
        print(f"Container '{CONTAINER_ID}' already exists.")
        container = database.QueryContainers().filter(lambda c: c['id'] == CONTAINER_ID).first()
    return container

def create_item(container, item):
    try:
        created_item = container.CreateItem(body=item)
        print(f"Created item: {created_item['id']}")
    except errors.Conflict as e:
        print(f"Item with ID {item['id']} already exists.")
    except Exception as e:
        print(f"Error creating item: {e}")

def get_item(container, id, partition_key_value):
    try:
        item = container.ReadItem(id, {'partitionKey': partition_key_value})
        print(f"Retrieved item: {item['id']}")
        return item
    except errors.CosmosResourceNotFoundError:
        print(f"Item with ID {id} not found.")
        return None
    except Exception as e:
        print(f"Error retrieving item: {e}")
        return None

if __name__ == "__main__":
    container = initialize()

    new_item = {
        'id': str(uuid.uuid4()),
        'category': 'hardware',
        'name': 'CPU Cooler',
        'quantity': 30,
        'partitionKey': 'hardware'
    }

    create_item(container, new_item)
    retrieved_item = get_item(container, new_item['id'], new_item['partitionKey'])

    if retrieved_item:
        print("Successfully retrieved item.")
                    
                

JavaScript (Browser)

                    
// Include the Azure Cosmos DB SDK script in your HTML
// <script src="https://unpkg.com/@azure/cosmos@3.19.1/dist/umd/index.js"></script>

// IMPORTANT: Replace with your actual endpoint and key (for demonstration, ideally use a backend proxy)
const endpoint = "YOUR_COSMOS_DB_ENDPOINT";
const key = "YOUR_COSMOS_DB_PRIMARY_KEY";
const databaseId = "YOUR_DATABASE_ID";
const containerId = "YOUR_CONTAINER_ID";

const { CosmosClient } = require("@azure/cosmos"); // For Node.js, use above
const client = new CosmosClient({ endpoint, key });

async function initialize() {
    await client.databases.createIfNotExists({ id: databaseId });
    const { container } = await client.database(databaseId).containers.createIfNotExists({
        id: containerId,
        partitionKey: { paths: ["/partitionKey"] }
    });
    console.log(`Cosmos DB initialized. Container: ${containerId}`);
    return container;
}

async function createItem(container, item) {
    try {
        const { resource: createdItem } = await container.items.create(item);
        console.log(`Created item: ${createdItem.id}`);
        return createdItem;
    } catch (error) {
        console.error("Error creating item:", error.message);
        return null;
    }
}

async function getItem(container, id, partitionKeyValue) {
    try {
        const { resource: item } = await container.item(id, partitionKeyValue).read();
        console.log(`Retrieved item: ${item.id}`);
        return item;
    } catch (error) {
        console.error("Error retrieving item:", error.message);
        return null;
    }
}

// Example usage within a browser context
async function runBrowserExample() {
    const container = await initialize();

    const newItem = {
        id: Math.random().toString(36).substring(2, 15), // Simple unique ID
        category: "accessory",
        name: "Ergonomic Mousepad",
        quantity: 50,
        partitionKey: "accessory"
    };

    await createItem(container, newItem);
    const retrievedItem = await getItem(container, newItem.id, newItem.partitionKey);

    if (retrievedItem) {
        console.log("Successfully retrieved item from browser.");
    }
}

// Call this function when your page is ready
// runBrowserExample().catch(console.error);
                    
                

Go

                    
// go get github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

// IMPORTANT: Replace with your actual endpoint
const endpoint = "YOUR_COSMOS_DB_ENDPOINT"
const databaseID = "YOUR_DATABASE_ID"
const containerID = "YOUR_CONTAINER_ID"

func main() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}

	client, err := azcosmos.NewClient(endpoint, cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}

	ctx := context.Background()

	// Ensure database and container exist
	_, err = ensureResources(ctx, client)
	if err != nil {
		log.Fatalf("failed to ensure resources: %v", err)
	}

	container, err := client.NewContainer(databaseID, containerID)
	if err != nil {
		log.Fatalf("failed to get container client: %v", err)
	}

	// Create item example
	newItem := map[string]interface{}{
		"id":         "my-go-item-" + fmt.Sprint(time.Now().UnixNano()),
		"category":   "electronics",
		"name":       "Smart Speaker",
		"quantity":   5,
		"partitionKey": "electronics",
	}
	partitionKeyVal := azcosmos.NewPartitionKeyString("electronics")

	resp, err := container.CreateItem(ctx, partitionKeyVal, newItem, nil)
	if err != nil {
		log.Fatalf("failed to create item: %v", err)
	}
	log.Printf("Created item with ID: %s", resp.Item.ID)

	// Read item example
	retrievedItem, err := container.Item(resp.Item.ID, partitionKeyVal).Read(ctx, nil)
	if err != nil {
		log.Fatalf("failed to read item: %v", err)
	}
	log.Printf("Retrieved item successfully.")
	fmt.Printf("Retrieved item content: %+v\n", retrievedItem.Item)
}

func ensureResources(ctx context.Context, client *azcosmos.Client) (*azcosmos.Database, *azcosmos.Container, error) {
	db, err := client.NewDatabase(databaseID)
	if err != nil {
		// Attempt to create if it doesn't exist
		_, err = client.CreateDatabase(ctx, azcosmos.DatabaseProperties{ID: databaseID}, nil)
		if err != nil {
			return nil, nil, fmt.Errorf("failed to create or get database %s: %w", databaseID, err)
		}
		log.Printf("Database '%s' created.", databaseID)
	} else {
		log.Printf("Database '%s' already exists.", databaseID)
	}

	container, err := db.NewContainer(containerID)
	if err != nil {
		// Attempt to create if it doesn't exist
		_, err = db.CreateContainer(ctx, azcosmos.ContainerProperties{
			ID: containerID,
			PartitionKey: azcosmos.PartitionKeyProperties{
				Paths: []string{"/partitionKey"},
			},
		}, nil)
		if err != nil {
			return db, nil, fmt.Errorf("failed to create or get container %s: %w", containerID, err)
		}
		log.Printf("Container '%s' created.", containerID)
	} else {
		log.Printf("Container '%s' already exists.", containerID)
	}
	return db, container, nil
}
                    
                

Important: Always manage your connection strings and keys securely. Avoid hardcoding them directly in client-side code. Consider using Azure Key Vault or environment variables. For browser-based JavaScript, it is highly recommended to use a backend proxy to handle authentication.

Key Features of Cosmos DB SDKs

High Performance: Optimized for low latency and high throughput.
Consistency Options: Support for various consistency levels (Strong, Bounded Staleness, Session, Consistent Prefix, Eventual).
Querying: Powerful SQL query capabilities.
Change Feed: Real-time data stream processing.
Multi-Region Writes: Global distribution and low-latency writes.
Cross-Platform: Available for major operating systems and platforms.

Choosing the Right SDK

Select the SDK that best matches your application's programming language and environment. Each SDK provides a consistent interface for interacting with Azure Cosmos DB, abstracting away the complexities of HTTP requests and responses.

For direct interaction with the database without an SDK, you can also use the Azure Cosmos DB REST API.