Elastically scale an Azure Cosmos DB for Apache Cassandra account

APPLIES TO: Cassandra

Azure Cosmos DB for Apache Cassandra offers a variety of options for elastic scale. To understand how to scale effectively in Azure Cosmos DB, you need to know how to provision the right amount of request units (RU/s). To learn more about request units, see the request units article.

For the API for Cassandra, you can retrieve the request unit charge for individual queries using the .NET and Java SDKs. This information helps you determine the amount of RU/s you need to provision in the service.

Handling rate limiting (429 errors)

Azure Cosmos DB returns rate-limited (429) errors if clients consume more resources (RU/s) than the amount that you have provisioned. The API for Cassandra in Azure Cosmos DB translates these exceptions to overloaded errors on the Cassandra native protocol.

If your system isn't sensitive to latency, it might be sufficient to handle the throughput rate-limiting by using retries. See Java code samples for version 3 and version 4 of the Apache Cassandra Java drivers for how to handle rate limiting transparently. These samples implement a custom version of the default Cassandra retry policy in Java. You can also use the Spark extension to handle rate-limiting. When using Spark, ensure you follow our guidance on Optimizing Spark connector throughput configuration.

Manage scaling

If you need to minimize latency, there are various options for managing scale and provisioning throughput (RUs) in the API for Cassandra:

• Manually by using the Azure portal
• Programmatically by using the control plane features
• Programmatically by using CQL commands with a specific SDK
• Dynamically by using autoscale

The following sections explain the advantages and disadvantages of each approach. You can then decide on the best strategy to balance the scaling needs of your system, the overall cost, and efficiency needs for your solution.

Use the Azure portal

You can scale the resources in an Azure Cosmos DB for Apache Cassandra account by using the Azure portal. To learn more, see Provision throughput on containers and databases. This article explains the relative benefits of setting throughput at either database or container level in the Azure portal. The terms "database" and "container" mentioned in these articles map to "keyspace" and "table" respectively for the API for Cassandra.

The advantage of this method is that it's a straightforward turnkey way to manage throughput capacity on the database. However, the disadvantage is that in many cases, your approach to scaling might require certain levels of automation to be both cost-effective and high performing. The next sections explain the relevant scenarios and methods.

Use the control plane

The Azure Cosmos DB API for Cassandra provides the capability to adjust throughput programmatically by using various control-plane features. For guidance and samples, see the Azure Resource Manager, PowerShell, and Azure CLI articles.

The advantage of this method is that you can automate the scaling up or down of resources based on a timer to account for peak activity, or periods of low activity. To learn how to accomplish this by using Azure Functions and PowerShell, see the sample on GitHub.

A disadvantage of this approach might be that you can't respond to unpredictable changing scale needs in real-time. Instead, you might need to use the application context in your system, at the client/SDK level, or by using Autoscale.

Use CQL queries with a specific SDK

You can scale the system dynamically with code by executing the CQL ALTER commands for the given database or container.

The advantage of this approach is that it allows you to respond to scale needs dynamically and in a custom way that suits your application. When you use this approach, you can still use the standard RU/s charges and rates. If your system's scale needs are mostly predictable (around 70% or more), using SDK with CQL might be a more cost-effective method of auto-scaling than using autoscale. The disadvantage of this approach is that it can be quite complex to implement retries while rate limiting might increase latency.

Use autoscale provisioned throughput

In addition to standard (manual) or programmatic ways of provisioning throughput, you can also configure Azure Cosmos DB containers in autoscale provisioned throughput. Autoscale automatically and instantly scales to your consumption needs within specified RU ranges without compromising SLAs. To learn more, see Create Azure Cosmos DB containers and databases in autoscale.

The advantage of this approach is that it's the easiest way to manage the scaling needs in your system. It doesn't apply rate-limiting within the configured RU ranges. The disadvantage is that, if the scaling needs in your system are predictable, autoscale might be a less cost-effective way of handling your scaling needs than using the bespoke control plane or SDK level approaches mentioned earlier.

To set or alter max throughput (RUs) for autoscale by using CQL, use the following code. Replace the keyspace and table names with the appropriate values.

# to set max throughput (RUs) for autoscale at keyspace level:
create keyspace <keyspace name> WITH cosmosdb_autoscale_max_throughput=5000;

# to alter max throughput (RUs) for autoscale at keyspace level:
alter keyspace <keyspace name> WITH cosmosdb_autoscale_max_throughput=4000;

# to set max throughput (RUs) for autoscale at table level:
create table <keyspace name>.<table name> (pk int PRIMARY KEY, ck int) WITH cosmosdb_autoscale_max_throughput=5000;

# to alter max throughput (RUs) for autoscale at table level:
alter table <keyspace name>.<table name> WITH cosmosdb_autoscale_max_throughput=4000;

Next step

• Get started with creating an API for Cassandra account, database, and a table by using a Java application