Azure Cosmos DB SDK Documentation

Key Information

Introduction

Azure Cosmos DB is a globally distributed, multi-model database service that enables you to build highly scalable and available applications. The Azure Cosmos DB SDKs provide a convenient and efficient way to interact with your Cosmos DB accounts from your preferred programming language.

These SDKs offer features such as:

• Data modeling and manipulation (CRUD operations)
• Querying data using SQL, MongoDB query language, Gremlin, or Cassandra Query Language
• Managing resources (databases, containers, users, permissions)
• Configuring consistency levels and partitioning
• Handling errors and retries
• Monitoring performance and diagnostics

Supported SDKs

Azure Cosmos DB offers official SDKs for the following popular programming languages:

Getting Started with the .NET SDK

This section provides a quick start guide for the .NET SDK.

1. Installation

Install the `Microsoft.Azure.Cosmos` NuGet package using the .NET CLI:

dotnet add package Microsoft.Azure.Cosmos
                

2. Initialization

Initialize the Cosmos DB client with your connection string or endpoint and key.

using Microsoft.Azure.Cosmos;

// Replace with your actual endpoint and key
string cosmosDbEndpoint = "YOUR_COSMOS_DB_ENDPOINT";
string cosmosDbKey = "YOUR_COSMOS_DB_PRIMARY_KEY";

CosmosClient client = new CosmosClient(cosmosDbEndpoint, cosmosDbKey);
Database database = await client.CreateDatabaseIfNotExistsAsync("MyDatabase");
Container container = await database.CreateContainerIfNotExistsAsync("MyContainer", "/partitionKey");
                

3. Performing Operations

Perform basic operations like creating, reading, updating, and deleting items.

// Create an item
var newItem = new { id = "item1", name = "Example Item", category = "Test" };
ItemResponse<dynamic> createResponse = await container.CreateItemAsync(newItem, new PartitionKey(newItem.category));
Console.WriteLine($"Created item: {createResponse.Resource.id}");

// Read an item
ItemResponse<dynamic> readResponse = await container.ReadItemAsync<dynamic>(createResponse.Resource.id, new PartitionKey(createResponse.Resource.category));
Console.WriteLine($"Read item: {readResponse.Resource.name}");

// Query items
var queryDefinition = new QueryDefinition("SELECT * FROM c WHERE c.category = 'Test'");
FeedIterator<dynamic> feedIterator = container.GetItemQueryIterator<dynamic>(queryDefinition);
while (feedIterator.HasMoreResults)
{
    FeedResponse<dynamic> response = await feedIterator.ReadNextAsync();
    foreach (var item in response)
    {
        Console.WriteLine($"Queried item: {item.id}");
    }
}
                

Key Concepts and Best Practices

• Partitioning: Understand and choose an appropriate partition key for optimal performance and scalability.
• Indexing: Configure indexing policies to balance query performance and storage costs.
• Consistency Levels: Select the right consistency level based on your application's requirements for latency and data freshness.
• Request Units (RUs): Monitor and manage RU consumption to control costs and ensure performance.
• Error Handling: Implement robust error handling, including retry mechanisms for transient errors.

Resources