Frequently asked questions on distributing throughput across partitions in Azure Cosmos DB (preview)

The throughput redistribution feature of Azure Cosmos DB gives you the ability to redistribute your provisioned throughput across physical partitions. This article answers commonly asked questions about Azure Cosmos DB throughput redistribution across partitions.

What resources can I use this feature on?

The feature is only supported for SQL and API for MongoDB accounts. It is supported for shared throughput databases and containers/collections with dedicated throughput (either manual or autoscale). The feature doesn't apply to serverless accounts.

How do I enroll in the preview feature?

You don't have to enroll in the preview. To use the feature, just use the relevant commands in the Azure PowerShell or Azure CLI to redistribute throughput across your resources' physical partitions.

Which version of the Azure Cosmos DB functionality in Azure PowerShell and Azure CLI supports this feature?

The ability to redistribute RU/s across physical partitions is only supported in the preview version of Azure PowerShell (version 2.0.2-preview or higher)[https://www.powershellgallery.com/packages/Az.CosmosDB/2.0.2-preview] and latest preview version of the Azure CLI.

What is the maximum number of physical partitions I can change in one request?

  • The maximum number of source and physical partitions that can be included in a single request is 20 each.
  • You must provide at least one source and one target physical partition in each request. The source partition(s) must have enough RU/s to redistribute to the target partition(s).
  • The desired RU/s for each target physical partition can't exceed 10,000 RU/s or the total RU/s of the overall resource. If your desired RU/s is greater than the RU/s of the overall resource, increase your overall RU/s first before redistributing the RU/s.

Is there a limit on how frequently I can make a call to redistribute throughput across partitions?

You can make a maximum of five requests per minute to redistribute throughput across partitions.

What happens to my RU/s distribution when I change the overall RU/s?

  • If you lower your RU/s, each physical partition gets the equivalent fraction of the new RU/s (current throughput fraction * new RU/s). For example, suppose you have a collection with 6000 RU/s and 3 physical partitions. You scale it down to 3000 RU/s.

    Before scale-down (6000 RU/s) After scale down (3000 RU/s) Fraction of total RU/s
    P0: 1000 RU/s P0: 500 RU/s 1/6
    P1: 4000 RU/s P1: 2000 RU/s 2/3
    P2: 1000 RU/s P2: 500 RU/s 1/6
  • If you increase your RU/s, each physical partition will have RU/s = MIN(current throughput fraction * new RU/s, 10,000 RU/s). The RU/s on a physical partition can never exceed 10,000 RU/s.

    For example, suppose you have a collection with 6000 RU/s and 3 physical partitions. You scale it up to 12,000 RU/s:

    Before scale-up (6000 RU/s) After scale up (12,000 RU/s) Fraction of total RU/s
    P0: 1000 RU/s P0: 2000 RU/s 1/6
    P1: 4000 RU/s P1: 8000 RU/s 2/3
    P2: 1000 RU/s P2: 2000 RU/s 1/6

Why am I seeing a discrepancy between the overall RU/s on my container and the sum of the RU/s across all physical partitions?

  • This discrepancy can happen when you scale up your overall RU/s for any single partition, (current RU/s per partition * new container RU/s)/(old container RU/s) is greater than 10,000 RU/s. This discrepancy occurs when you trigger a partition split by increasing RU/s beyond currentNumberOfPartitions * 10,000 RU/s or increase RU/s without triggering a partition split.

  • It's recommended to redistribute your throughput equally after the scale-up. Otherwise, it's possible that you won't be able to use all the RU/s you've provisioned (and are being billed for).

  • To check if this scenario applies to your resource use Azure Monitor metrics. Compare the value of the ProvisionedThroughput (when using manual throughput) or AutoscaleMaxThroughput (when using autoscale) metric to the value of the PhysicalPartitionThroughput metric. If the value of PhysicalPartitionThroughput is less than the respective ProvisionedThroughput or AutoscaleMaxThroughput, then reset your RU/s to an even distribution before redistributing, or lower your resource's throughput to the value of PhysicalPartitionThroughput.

    For example, suppose you have a collection with 6000 RU/s and 3 physical partitions. You scale it up to 24,000 RU/s. After the scale-up, the total throughput across all partitions is only 18,000 RU/s. This distribution means that while we're being billed for 24,000 RU/s, we're only able to get 18,000 RU/s of effective throughput. Each partition will get 8000 RU/s, as RU/s are redistributed equally, and we can redistribute RU/s again as needed. We could also choose to lower our overall RU/s to 18,000 RU/s.

    Before scale-up (6000 RU/s) After scale up to 24,000 RU/s (effective RU/s = 18,000 RU/s) Fraction of total RU/s
    P0: 1000 RU/s P0: 4000 RU/s 1/6
    P1: 4000 RU/s P1: 10000 RU/s (partition can't exceed 10,000 RU/s) 2/3
    P2: 1000 RU/s P2: 4000 RU/s 1/6