| title | description | author | ms.author | ms.service | ms.subservice | ms.topic | ms.date | ms.custom |
|---|---|---|---|---|---|---|---|---|
Provision autoscale throughput in Azure Cosmos DB SQL API |
Learn how to provision autoscale throughput at the container and database level in Azure Cosmos DB SQL API using Azure portal, CLI, PowerShell, and various other SDKs. |
deborahc |
dech |
cosmos-db |
cosmosdb-sql |
how-to |
10/15/2020 |
devx-track-csharp, devx-track-azurecli |
[!INCLUDEappliesto-sql-api]
This article explains how to provision autoscale throughput on a database or container (collection, graph, or table) in Azure Cosmos DB SQL API. You can enable autoscale on a single container, or provision autoscale throughput on a database and share it among all the containers in the database.
If you are using a different API, see API for MongoDB, Cassandra API, Gremlin API articles to provision the throughput.
-
Sign in to the Azure portal or the Azure Cosmos DB explorer.
-
Navigate to your Azure Cosmos DB account and open the Data Explorer tab.
-
Select New Container. Enter a name for your database, container, and a partition key. Under Throughput, select the autoscale option, and set the maximum throughput (RU/s) that you want the database or container to scale to.
:::image type="content" source="./media/how-to-provision-autoscale-throughput/create-new-autoscale-container.png" alt-text="Creating a container and configuring autoscale provisioned throughput":::
-
Select OK.
To provision autoscale on shared throughput database, select the Provision database throughput option when creating a new database.
Important
In the current release, the Azure portal is the only way to migrate between autoscale and standard (manual) provisioned throughput.
-
Sign in to the Azure portal or the Azure Cosmos DB explorer.
-
Navigate to your Azure Cosmos DB account and open the Data Explorer tab.
-
Select Scale and Settings for your container, or Scale for your database.
-
Under Scale, select the Autoscale option and Save.
:::image type="content" source="./media/how-to-provision-autoscale-throughput/autoscale-scale-and-settings.png" alt-text="Enabling autoscale on an existing container":::
Note
When you enable autoscale on an existing database or container, the starting value for max RU/s is determined by the system, based on your current manual provisioned throughput settings and storage. After the operation completes, you can change the max RU/s if needed. Learn more.
Use version 3.9 or higher of the Azure Cosmos DB .NET SDK for SQL API to manage autoscale resources.
Important
You can use the .NET SDK to create new autoscale resources. The SDK does not support migrating between autoscale and standard (manual) throughput. The migration scenario is currently supported in only the Azure portal.
// Create instance of CosmosClient
CosmosClient cosmosClient = new CosmosClient(Endpoint, PrimaryKey);
// Autoscale throughput settings
ThroughputProperties autoscaleThroughputProperties = ThroughputProperties.CreateAutoscaleThroughput(4000); //Set autoscale max RU/s
//Create the database with autoscale enabled
database = await cosmosClient.CreateDatabaseAsync(DatabaseName, throughputProperties: autoscaleThroughputProperties);// Get reference to database that container will be created in
Database database = await cosmosClient.GetDatabase("DatabaseName");
// Container and autoscale throughput settings
ContainerProperties autoscaleContainerProperties = new ContainerProperties("ContainerName", "/partitionKey");
ThroughputProperties autoscaleThroughputProperties = ThroughputProperties.CreateAutoscaleThroughput(4000); //Set autoscale max RU/s
// Create the container with autoscale enabled
container = await database.CreateContainerAsync(autoscaleContainerProperties, autoscaleThroughputProperties);// Get a reference to the resource
Container container = cosmosClient.GetDatabase("DatabaseName").GetContainer("ContainerName");
// Read the throughput on a resource
ThroughputProperties autoscaleContainerThroughput = await container.ReadThroughputAsync(requestOptions: null);
// The autoscale max throughput (RU/s) of the resource
int? autoscaleMaxThroughput = autoscaleContainerThroughput.AutoscaleMaxThroughput;
// The throughput (RU/s) the resource is currently scaled to
int? currentThroughput = autoscaleContainerThroughput.Throughput;// Change the autoscale max throughput (RU/s)
await container.ReplaceThroughputAsync(ThroughputProperties.CreateAutoscaleThroughput(newAutoscaleMaxThroughput));You can use version 4.0 or higher of the Azure Cosmos DB Java SDK for SQL API to manage autoscale resources.
Important
You can use the Java SDK to create new autoscale resources. The SDK does not support migrating between autoscale and standard (manual) throughput. The migration scenario is currently supported in only the Azure portal.
// Create instance of CosmosClient
CosmosAsyncClient client = new CosmosClientBuilder()
.setEndpoint(HOST)
.setKey(PRIMARYKEY)
.setConnectionPolicy(CONNECTIONPOLICY)
.buildAsyncClient();
// Autoscale throughput settings
ThroughputProperties autoscaleThroughputProperties = ThroughputProperties.createAutoscaledThroughput(4000); //Set autoscale max RU/s
//Create the database with autoscale enabled
CosmosAsyncDatabase database = client.createDatabase(databaseName, autoscaleThroughputProperties).block().getDatabase();// Create instance of CosmosClient
CosmosClient client = new CosmosClientBuilder()
.setEndpoint(HOST)
.setKey(PRIMARYKEY)
.setConnectionPolicy(CONNECTIONPOLICY)
.buildClient();
// Autoscale throughput settings
ThroughputProperties autoscaleThroughputProperties = ThroughputProperties.createAutoscaledThroughput(4000); //Set autoscale max RU/s
//Create the database with autoscale enabled
CosmosDatabase database = client.createDatabase(databaseName, autoscaleThroughputProperties).getDatabase();// Get reference to database that container will be created in
CosmosAsyncDatabase database = client.createDatabase("DatabaseName").block().getDatabase();
// Container and autoscale throughput settings
CosmosContainerProperties autoscaleContainerProperties = new CosmosContainerProperties("ContainerName", "/partitionKey");
ThroughputProperties autoscaleThroughputProperties = ThroughputProperties.createAutoscaledThroughput(4000); //Set autoscale max RU/s
// Create the container with autoscale enabled
CosmosAsyncContainer container = database.createContainer(autoscaleContainerProperties, autoscaleThroughputProperties, new CosmosContainerRequestOptions())
.block()
.getContainer();// Get reference to database that container will be created in
CosmosDatabase database = client.createDatabase("DatabaseName").getDatabase();
// Container and autoscale throughput settings
CosmosContainerProperties autoscaleContainerProperties = new CosmosContainerProperties("ContainerName", "/partitionKey");
ThroughputProperties autoscaleThroughputProperties = ThroughputProperties.createAutoscaledThroughput(4000); //Set autoscale max RU/s
// Create the container with autoscale enabled
CosmosContainer container = database.createContainer(autoscaleContainerProperties, autoscaleThroughputProperties, new CosmosContainerRequestOptions())
.getContainer();// Get a reference to the resource
CosmosAsyncContainer container = client.getDatabase("DatabaseName").getContainer("ContainerName");
// Read the throughput on a resource
ThroughputProperties autoscaleContainerThroughput = container.readThroughput().block().getProperties();
// The autoscale max throughput (RU/s) of the resource
int autoscaleMaxThroughput = autoscaleContainerThroughput.getAutoscaleMaxThroughput();
// The throughput (RU/s) the resource is currently scaled to
int currentThroughput = autoscaleContainerThroughput.Throughput;// Get a reference to the resource
CosmosContainer container = client.getDatabase("DatabaseName").getContainer("ContainerName");
// Read the throughput on a resource
ThroughputProperties autoscaleContainerThroughput = container.readThroughput().getProperties();
// The autoscale max throughput (RU/s) of the resource
int autoscaleMaxThroughput = autoscaleContainerThroughput.getAutoscaleMaxThroughput();
// The throughput (RU/s) the resource is currently scaled to
int currentThroughput = autoscaleContainerThroughput.Throughput;// Change the autoscale max throughput (RU/s)
container.replaceThroughput(ThroughputProperties.createAutoscaledThroughput(newAutoscaleMaxThroughput)).block();// Change the autoscale max throughput (RU/s)
container.replaceThroughput(ThroughputProperties.createAutoscaledThroughput(newAutoscaleMaxThroughput));Azure Resource Manager templates can be used to provision autoscale throughput on database or container-level resources for all Azure Cosmos DB APIs. See Azure Resource Manager templates for Azure Cosmos DB for samples.
Azure CLI can be used to provision autoscale throughput on a database or container-level resources for all Azure Cosmos DB APIs. For samples see Azure CLI Samples for Azure Cosmos DB.
Azure PowerShell can be used to provision autoscale throughput on a database or container-level resources for all Azure Cosmos DB APIs. For samples see Azure PowerShell samples for Azure Cosmos DB.
- Learn about the benefits of provisioned throughput with autoscale.
- Learn how to choose between manual and autoscale throughput.
- Review the autoscale FAQ.