faysilalshareef/partition-strategy

Partition Strategy — Hierarchical Partition Keys

Core Principles

• Partition keys determine data distribution and query efficiency
• Cosmos supports hierarchical partition keys (up to 3 levels)
• Queries within a single partition are fast and cheap (RU-efficient)
• Cross-partition queries fan out to all partitions (expensive)
• Choose keys based on query patterns, not data structure
• Avoid hot partitions — distribute writes evenly

Key Patterns

Hierarchical Partition Key Definition

// Container definition with 3-level partition key
var containerProperties = new ContainerProperties
{
    Id = "invoices",
    PartitionKeyPaths = new Collection<string>
    {
        "/merchantId",    // Level 1: tenant/merchant isolation
        "/reportMonth",   // Level 2: time-based partitioning
        "/discriminator"  // Level 3: entity type
    }
};

Building Partition Keys

// Full 3-level key for point reads/writes
public PartitionKey PartitionKeys => new PartitionKeyBuilder()
    .Add(MerchantId)           // Level 1
    .Add(ReportMonth)          // Level 2
    .Add(Discriminator)        // Level 3
    .Build();

// Partial key for scoped queries (Level 1 only)
public static PartitionKey ForMerchant(string merchantId) =>
    new PartitionKeyBuilder()
        .Add(merchantId)
        .Build();

// Partial key for time-scoped queries (Level 1 + 2)
public static PartitionKey ForMerchantMonth(string merchantId, string month) =>
    new PartitionKeyBuilder()
        .Add(merchantId)
        .Add(month)
        .Build();

Query Patterns by Partition Scope

// Fastest: Point read with full partition key
var invoice = await container.ReadItemAsync<SaleInvoice>(
    id, SaleInvoice.ForMerchantMonth("M001", "2025-03"));

// Fast: Query within full partition
var invoices = await repo.QueryAsync(
    i => i.TotalAmount > 1000,
    SaleInvoice.ForMerchantMonth("M001", "2025-03"));

// Medium: Query with partial partition key (fan-out within merchant)
var allInvoices = await repo.QueryAsync(
    i => i.TotalAmount > 1000,
    SaleInvoice.ForMerchant("M001"));

// Slow: Cross-partition query (avoid in production hot paths)
var report = await repo.QueryAsync(
    i => i.TotalAmount > 10000);

Strategy Decision Guide

Query Pattern                    | Recommended Partition Key
-------------------------------- | -------------------------
Single tenant, time-series       | TenantId / Year-Month / EntityType
Multi-tenant, per-user data      | TenantId / UserId / EntityType
Geographic data                  | Region / City / EntityType
Order processing                 | CustomerId / OrderDate / EntityType
IoT telemetry                    | DeviceId / Date / EntityType

Container Design Patterns

Pattern 1: Entity-per-container
  - invoices container → SaleInvoice documents
  - reports container → MerchantSalesReport documents
  - Simple, clear boundaries
  - Best for independent entity lifecycles

Pattern 2: Polymorphic container
  - sales container → SaleInvoice + SoldItem + SalesReport
  - Uses Discriminator for filtering
  - Enables TransactionalBatch across types
  - Best when entities share partition key and need atomic operations

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Using entity Id as partition key | Choose keys based on query patterns | | Single-value partition key | Use hierarchical keys for flexibility | | Timestamp as only partition key | Causes hot partitions on recent data | | Cross-partition queries in hot paths | Design partitions around common queries | | Ignoring RU costs | Monitor and optimize partition strategy |

Detect Existing Patterns

# Find partition key definitions
grep -r "PartitionKeyBuilder\|PartitionKeyPaths" --include="*.cs" src/

# Find container properties
grep -r "ContainerProperties\|ContainerName" --include="*.cs" src/

# Find cross-partition queries
grep -r "ToListWithoutPartitionFilter\|EnableCrossPartition" --include="*.cs" src/

Adding to Existing Project

1. Map existing partition key strategy before adding new entities
2. New entities in same container must use the same partition key hierarchy
3. Add partial key helper methods for scoped queries
4. Monitor RU consumption when changing query patterns
5. Test with realistic data volumes — partition strategy matters at scale