Limit the total throughput provisioned on your Azure Cosmos DB account

  • Article

APPLIES TO: NoSQL MongoDB Cassandra Gremlin Table

When using an Azure Cosmos DB account in provisioned throughput mode, most of your costs usually come from the amount of throughput that you have provisioned across your account. In particular, these costs are directly influenced by:

  • The number of databases that have shared throughput.
  • The number of containers that have dedicated throughput.
  • The amount of throughput provisioned on each of these resources.
  • The number of regions where your account is available.

It can be challenging to keep track of the total amount of throughput that you have provisioned across your account, especially when you're getting started with Azure Cosmos DB. This can lead to unexpected charges when this amount ends up going over a certain budget that you didn't expect to exceed. To help you better control your costs, Azure Cosmos DB lets you limit the total throughput provisioned on your account.

Note

This feature is not available on serverless accounts.

After you've set a limit to your account's total throughput, any of the following operations that results in exceeding this limit is blocked and will explicitly fail:

  • Creating a new database with shared throughput.
  • Creating a new container with dedicated throughput.
  • Increasing the provisioned throughput on a resource configured in standard (manual) mode.
  • Increasing the maximum provisioned throughput on a resource configured in autoscale mode.
  • Adding a new region to your account.

Note

For resources configured in autoscale mode, it is the maximum throughput configured on the resource that counts towards your account's total throughput.

Important

Once a total throughput limit is enabled on your account, you must pass an explicit throughput value when creating new containers. You will currently get an error if you try to create a container with no explicit throughput.

Set the total throughput limit from the Azure portal

Note

Although there is an option to set the total throughput limit when using the portal to create an Azure Cosmos DB account, but currently that is not available via protal in Azure China, and this feature can only be accessed through Bicep/ARM.

What's more, Cost Management can't provide management of the limit via portal currently.

Set the total throughput limit programmatically

Using Azure Resource Manager templates

When creating or updating your Azure Cosmos DB account with Azure Resource Manager, you can configure the total throughput limit by setting the properties.capacity.totalThroughputLimit property:

{
  "location": "China North3",
  "kind": "DocumentDB",
  "properties": {
    "locations": [
      {
        "locationName": "China North3",
        "failoverPriority": 0,
        "isZoneRedundant": false
      }
    ],
    "databaseAccountOfferType": "Standard",
    "capacity": {
        "totalThroughputLimit": 2000
    }
  }
}

Set this property to -1 to disable the limit.

Frequently asked questions

Are there situations where the total provisioned throughput can exceed the limit?

Azure Cosmos DB enforces a minimum throughput of 1 RU/s per GB of data stored. If you're ingesting data while already being at that minimum, the throughput provisioned on your resources will automatically increase to honor 1 RU/s per GB. In this case, and this case only, your total provisioned throughput may exceed the limit you've set.

Next steps