Selecting the right partition key in Azure Cosmos DB is one of the most critical decisions you will make when designing your database schema. Pick the wrong key, and you will hit performance bottlenecks due to unbalanced workload distribution across logical partitions.

What Makes a Good Partition Key?

A strong partition key distributes reads and writes evenly across physical storage partitions. Ideally, your chosen key should have high cardinality—meaning it has thousands or millions of distinct values—and distribute Request Units (RU) evenly across your workload.

• High Cardinality: Choose properties like userId, deviceId, or orderId rather than low-cardinality fields like gender or status.
• Balanced Read/Write Pattern: Ensure that no single partition key value absorbs 80% of your total request volume, which causes hot partitions.
• Synthetic Keys: Combine multiple properties (e.g., tenantId_date) when no single field meets cardinality requirements.

Configuring Partition Keys via the .NET SDK

Here is how you define container settings and write items with explicit partition key specifications using C#:

// Initialize container properties specifying the partition key JSON path
ContainerProperties containerProperties = new ContainerProperties(
    id: "Orders",
    partitionKeyPath: "/customerId"
);

// Create the container if it does not already exist with provisioned throughput
Container container = await database.CreateContainerIfNotExistsAsync(containerProperties, throughput: 400);

// Define a record object to persist
var order = new Order
{
    id = Guid.NewGuid().ToString(),
    customerId = "CUST_98234",
    totalAmount = 149.99m
};

// Perform point write operation by supplying item and partition key value
ItemResponse<Order> response = await container.CreateItemAsync<Order>(
    item: order,
    partitionKey: new PartitionKey(order.customerId)
);

By ensuring point operations use the exact partition key value, Cosmos DB routes the request directly to the target partition without querying across physical boundaries.