Frequently asked questions on hierarchical partition keys in Azure Cosmos DB (preview)

APPLIES TO: SQL API Cassandra API Gremlin API Table API Azure Cosmos DB API for MongoDB

Hierarchical partition keys, or subpartitoning, allows you to configure up to a three level hierarchy for your partition keys to further optimize data distribution and enable higher scale. This article answers commonly asked questions about Azure Cosmos DB Hierarchical partition keys.

Is there a storage limit on the size of a logical partition key?

Yes. Just like in Cosmos DB today, the logical partition size is still limited to 20 GB. However, with hierarchical partition keys, the logical partition is now the entire partition key path. For example, if you partitioned by TenantId -> UserId, an example logical partition would be "Contoso_Alice". Utilizing subpartitioning means you can have 20 GB of data where the partition key value is "Contoso_Alice". The amount of storage allowed for data in "Contoso" is effectively 20 GB * number of unique UserIds for the tenant "Contoso."

Are there any changes to storage and RU/s limits on physical partitions?

No. Just like in Cosmos DB today, a physical partition can hold 50 GB of storage and serve up to 10,000 RU/s. However, with hierarchical partition keys, if data for a particular partition key prefix - for example, TenantId - are in multiple physical partitions, subpartitioning means that the total RU/s achievable for a single TenantId can exceed 10,000 RU/s.

What happens if I query and only specify a partition key in the "middle" of the path?

Your query will still be a cross-partition query. For example, if you partition by TenantId -> UserId, and provide only the UserId in the query, this query will fan out to all physical partitions.

To have an efficiently routed query using the TenantId -> UserId example, there are two options:

  • Provide the TenantId. Queries will go to all physical partitions containing the TenantId data.
  • Provide both the TenantId and UserId. Queries will go to the single physical partition containing the TenantId and the specific UserId.

Do I have to create a new property in my documents to use this feature?

No. Specify the hierarchy of partition key paths you want to use during container creation. For example, if you partition by TenantId -> UserId, you don't need to create a new property with these values concatenated. Ensure that each document has a property TenantId and a property UserId. For more information, see subpartitioning code examples.

Next steps