Understanding and Using Partition Keys in Azure Cosmos DB with C#

Partition keys are fundamental to the performance and scalability of your Azure Cosmos DB database. This section provides practical C# code samples to help you understand, implement, and optimize the use of partition keys.

Why Partition Keys Matter

A well-chosen partition key distributes your data evenly across logical partitions, ensuring efficient query execution and optimal request unit (RU) consumption. Poor partitioning can lead to "hot partitions," bottlenecks, and increased costs.

Key Concepts

  • Partitioning Strategy: How to select a partition key that balances data distribution.
  • High-Throughput Operations: Optimizing CRUD operations with appropriate partition key choices.
  • Querying with Partition Keys: Leveraging partition keys in your queries for faster data retrieval.
  • Cross-Partition Queries: Understanding when and how these queries are executed and their performance implications.

C# Code Samples

1. Creating a Container with a Partition Key

Demonstrates how to define a partition key path when creating a new container.


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

public class PartitionKeySamples
{
    private readonly CosmosClient _client;
    private readonly string _databaseId = "MyDatabase";
    private readonly string _containerId = "MyContainer";

    public PartitionKeySamples(string connectionString)
    {
        _client = new CosmosClient(connectionString);
    }

    public async Task CreateContainerWithPartitionKeyAsync()
    {
        var database = _client.GetDatabase(_databaseId);

        var containerProperties = new ContainerProperties(_containerId, "/partitionKeyPath");
        
        await database.CreateContainerAsync(containerProperties, throughput: 400);
        Console.WriteLine($"Container '{_containerId}' created with partition key path '/partitionKeyPath'.");
    }
}
View Full Example

2. Inserting Items with a Partition Key

Shows how to include the partition key value when inserting new items.


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

public class PartitionKeySamples
{
    // ... (previous code) ...

    public async Task InsertItemAsync(dynamic item, string partitionKeyValue)
    {
        var container = _client.GetContainer(_databaseId, _containerId);
        var partitionKey = new PartitionKey(partitionKeyValue);

        await container.CreateItemAsync(item, partitionKey);
        Console.WriteLine($"Item inserted with partition key value: {partitionKeyValue}");
    }
}
View Full Example

3. Querying Items by Partition Key

Illustrates efficient querying using the partition key to narrow down the search.


using Azure.Cosmos;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class PartitionKeySamples
{
    // ... (previous code) ...

    public async Task<IEnumerable<dynamic>> QueryItemsByPartitionKeyAsync(string partitionKeyValue)
    {
        var container = _client.GetContainer(_databaseId, _containerId);
        var partitionKey = new PartitionKey(partitionKeyValue);

        var queryDefinition = new QueryDefinition("SELECT * FROM c WHERE c.status = 'Active'");

        var results = container.GetItemQueryIterator<dynamic>(queryDefinition, requestOptions: new QueryRequestOptions { PartitionKey = partitionKey });

        var itemList = new List<dynamic>();
        while (results.HasMoreResults)
        {
            var response = await results.ReadNextAsync();
            itemList.AddRange(response);
        }
        Console.WriteLine($"Found {itemList.Count} items for partition key: {partitionKeyValue}");
        return itemList;
    }
}
View Full Example