Azure Cosmos DB SDK Reference

Welcome to the official documentation for the Azure Cosmos DB SDKs. This section provides detailed reference information for the various client libraries available to interact with Azure Cosmos DB.

Introduction

Azure Cosmos DB is a globally distributed, multi-model database service. The SDKs provide idiomatic ways to perform CRUD operations, query data, manage resources, and leverage advanced features like change feed and transactions.

Supported SDKs

We offer SDKs for multiple popular programming languages:

• .NET SDK: For applications built on the .NET framework.
• Java SDK: For applications built on the Java Virtual Machine.
• Node.js SDK: For server-side JavaScript applications.
• Python SDK: For Python applications.
• Go SDK: For Go applications.
• Spring Data Cosmos SDK: For Spring applications.

Common Operations (Example: .NET SDK)

Below are examples of common operations and their corresponding SDK methods. For specific details on each language, please navigate to the respective SDK section.

1. Creating a Container

This example demonstrates how to create a new container in Azure Cosmos DB using the .NET SDK.

// Assuming 'client' is an initialized CosmosClient instance
Database database = await client.GetDatabase("MyDatabase");
ContainerProperties containerProperties = new ContainerProperties("MyContainer", "/partitionKeyPath");
Container container = await database.CreateContainerAsync(containerProperties);
            

2. Inserting an Item

Inserting a new document (item) into a container.

public class Product
{
    public string id { get; set; }
    public string name { get; set; }
    public string category { get; set; }
    public int price { get; set; }
}

// Assuming 'container' is an initialized Container instance
var productItem = new Product { id = "1", name = "Laptop", category = "Electronics", price = 1200 };
ItemResponse<Product> createResponse = await container.CreateItemAsync<Product>(productItem, new PartitionKey(productItem.category));
            

3. Querying Items

Executing a SQL query against the container.

// Assuming 'container' is an initialized Container instance
string sqlQueryText = "SELECT * FROM c WHERE c.category = 'Electronics'";
QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);
FeedIterator<Product> queryIterator = container.GetItemQueryIterator<Product>(queryDefinition);

while (queryIterator.HasMoreResults)
{
    FeedResponse<Product> response = await queryIterator.ReadNextAsync();
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item: {item.id} - {item.name}");
    }
}
            

API Reference Overview

The following tables provide a high-level overview of common API patterns. Please refer to language-specific documentation for full signatures and overloads.

Client and Database Operations

Operation	Description	.NET Example
Initialize Client	Establishes a connection to your Cosmos DB account.	new CosmosClient(accountEndpoint, accountKey)
Get Database	Retrieves a reference to an existing database or creates a new one.	client.GetDatabase("databaseName")
Create Database	Provisions a new database in your Cosmos DB account.	client.CreateDatabaseAsync("newDatabaseName")

Container Operations

Operation	Description	.NET Example
Get Container	Retrieves a reference to an existing container.	database.GetContainer("containerName")
Create Container	Provisions a new container within a database.	database.CreateContainerAsync(containerProperties, throughput)
Delete Container	Removes a container and all its data.	container.DeleteContainerAsync()

Item Operations

Operation	Description	.NET Example
Create Item	Adds a new document to a container.	container.CreateItemAsync<T>(item, partitionKey)
Read Item	Retrieves a specific document by its ID and partition key.	container.ReadItemAsync<T>(itemId, partitionKey)
Upsert Item	Creates or replaces an existing item.	container.UpsertItemAsync<T>(item, partitionKey)
Replace Item	Updates an existing item.	container.ReplaceItemAsync<T>(itemId, item, partitionKey)
Delete Item	Removes a specific document.	container.DeleteItemAsync<T>(itemId, partitionKey)

Key Concepts in SDK Usage

• Partitioning: Understanding partition keys is crucial for performance and scalability.
• Request Units (RUs): Learn how to provision and monitor throughput.
• Consistency Levels: Choose the appropriate consistency level for your application's needs.
• Error Handling: Implement robust error handling for transient network issues and other exceptions.

For detailed API specifications, language-specific examples, and advanced scenarios, please select your preferred SDK from the navigation pane.