What is hierarchical partition keys in Cosmos DB and when do you use it?

Hierarchical partition keys (also called sub-partitioning) allow you to define up to three levels of partition key paths on a container, forming a composite key like /tenantId/userId/sessionId. This feature, introduced in GA in 2023, solves the hot partition problem for multi-tenant or hierarchical data without requiring synthetic key concatenation.

With a single-level partition key on /tenantId, all data for one tenant lands in a single logical partition capped at 20 GB. A large enterprise tenant can blow through that limit quickly. With hierarchical partition keys on [tenantId, userId], data is first grouped by tenant then sub-partitioned by user, distributing the tenant's data across multiple logical partitions while still allowing single-partition queries scoped to a tenant.

How queries interact with hierarchical keys:

• Providing all levels (e.g., tenantId = 'acme' AND userId = 'u123') routes to a single partition — cheapest.
• Providing only the first level (tenantId = 'acme') does a partial partition key query — scans only partitions belonging to that tenant, not the whole container. Much cheaper than a full cross-partition fan-out.
• Providing no partition key levels triggers a full cross-partition scan — most expensive.

This is the key difference from a flat synthetic key: with a synthetic key you would have to provide the exact concatenated value or do a full cross-partition query. Hierarchical keys let you efficiently query any prefix of the key hierarchy.

Use hierarchical partition keys when you have multi-tenant data, when a single partition key value risks hitting the 20 GB ceiling, or when you need both tenant-scoped and user-scoped query patterns to be efficient.