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.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.