Update Cosmos DB Container Throughput


The Update Cosmos DB Container Throughput action is used to update the throughput of every container within every database within targeted Cosmos DB database accounts.

It supports scaling the throughput of Cosmos DB containers up or down as needed, based on workload demands. This can include a sudden increase in traffic to your Cosmos DB database account, when you want to ensure that your containers have enough throughput to handle the surge, or developing a new application that will use Cosmos DB, and you need to estimate the throughput that you will need for your containers reducing the amount of data that you are storing in your Cosmos DB containers, and you want to reduce the throughput of your containers to save money.

If you are developing a new application that will use Cosmos DB, and you need to estimate the throughput that you will need for your containers.


When you link GorillaStack to your Azure account, GorillaStack creates a service principal that provides access to the following permissions that are used by this action:

  • Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/read
  • Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/throughputSettings/read
  • Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/throughputSettings/write
  • Microsoft.DocumentDB/databaseAccounts/sqlDatabases/read

Getting Started

  1. Link your Azure account to your GorillaStack account if you have not done so already
  2. Create a database account in the linked Azure account
  3. Apply tags to the database account so it can be targeted in GorillaStack
  4. Create a new rule in GorillaStack
  5. In the rule’s context settings, select Azure as the platform, and then select one or more linked Azure Subscriptions to target
  6. In the rule’s trigger settings, select any available trigger — Schedule and Manual Execution are the most popular
  7. In the rule’s actions settings, select Update Cosmos DB Container Throughput as the action
  8. In this action’s Tag Targeting panel, create or select a tag group that targets the intended database account(s) and no others
  9. In this action’s Throughput Settings panel, select a throughput

Restore to Previous Throughput

Every time the Update Cosmos DB Container Throughput action runs and GorillaStack makes a change to the throughput of a targeted database container, it will remember it's previous throughput.

This allows GorillaStack users to utilize the Restore to Previous Throughput option, applying any remembered Throughput for each targeted database container.

Typically a Throughput value is used to scale down Cosmos DB containers at the end of a business day and the Restore to Previous Throughput option is utilized in a corresponding rule responsible for restoring a Cosmos DB container back to usual daytime scale at the start of a work day.


Azure sets a few limitations that affect how this action operates:

  • The throughput setting must be a multiple of 100 RU/s
  • If your database is in heavy use, Azure might set a minimum throughput that is higher than 400 RU/s, and if the target throughput in the rule is less than this minimum throughput, the rule will set the throughput to the actual minimum
  • The maximum throughput on a Cosmos DB database account is almost always 1,000,000 but a small number of customers with exceptional needs have negotiated a higher throughput directly with Microsoft; customers in this position should contact GorillaStack directly too
  • Do not enable the setting in Cosmos DB that allows you to update the throughput on an entire database account in one operation as GorillaStack updates and remembers the throughput on each container in each database in each database account individually
  • The Update Cosmos DB Container Throughput Action loops through each container in each database in a database account, and updates or restores each one individually, but it uses tags on the database account for targeting, as Cosmos DB does not allow the tagging of tables
  • You must not create your Cosmos DB database account with the Table API if you want to use this action; if you do, you will probably find your database has tables instead of containers and you will have to use GorillaStack’s Update Cosmos DB Table Throughput action instead