Frequently asked questions about Azure Cosmos DB for Apache Cassandra

Here are some key differences between the API for Cassandra service and Apache Cassandra:

• Apache Cassandra recommends a 100-MB limit on the size of a partition key. The API for Cassandra for Azure Cosmos DB allows up to 20 GB per partition.
• Apache Cassandra allows you to disable durable commits. You can skip writing to the commit log and go directly to the in-memory data structure. This can lead to data loss if the node goes down before the in-memory data structures are flushed to SSTables on disk. Azure Cosmos DB always does durable commits to help prevent data loss.
• Apache Cassandra can see diminished performance if the workload involves many replacements or deletions. The reason is tombstones that the read workload needs to skip over to fetch the latest data. The API for Cassandra won't see diminished read performance when the workload has many replacements or deletions.
• During scenarios of high replacement workloads, compaction needs to run to merge SSTables on disk. (A merge is needed because Apache Cassandra's writes are append only. Multiple updates are stored as individual SSTable entries that need to be periodically merged). This situation can also lead to lowered read performance during compaction. This performance impact doesn't happen in the API for Cassandra because the API doesn't implement compaction.
• Setting a replication factor of 1 is possible with Apache Cassandra. However, it leads to low availability if the only node with the data goes down. This isn't an issue with the API for Cassandra for Azure Cosmos DB because there's always a replication factor of 4 (quorum of 3).
• Adding or removing nodes in Apache Cassandra requires manual intervention, along with high CPU usage on the new node while existing nodes move some of their token ranges to the new node. This situation is the same when you're decommissioning an existing node. However, the API for Cassandra scales out without any issues observed in the service or application.
• There's no need to set num_tokens on each node in the cluster as in Apache Cassandra. Azure Cosmos DB fully manages nodes and token ranges.
• The API for Cassandra is fully managed. You don't need commands, such as repair and decommission that are used in Apache Cassandra.

The API for Cassandra for Azure Cosmos DB supports Cassandra Query Language (CQL) m version 3.x. Its CQL compatibility is based on the public Apache Cassandra GitHub repository. If you have feedback about supporting other protocols, send email to askcosmosdbcassandra@microsoft.com.

Azure Cosmos DB sets the default throughput for your container based on where you create the table from: Azure portal or CQL.

Azure Cosmos DB provides guarantees for performance and latency, with upper bounds on operations. These guarantees are possible when the engine can enforce governance on the tenant's operations. Setting throughput ensures that you get the guaranteed throughput and latency, because the platform reserves this capacity and guarantees operation success. You can elastically change throughput to benefit from the seasonality of your application and save costs.

The throughput concept is explained in the Request Units in Azure Cosmos DB article. The throughput for a table is equally distributed across the underlying physical partitions.

Azure Cosmos DB uses Request Units per second (RU/s) as a currency for providing throughput. Tables created through CQL have 400 RU by default. You can change the RU from the Azure portal.

CQL

CREATE TABLE keyspaceName.tablename (user_id int PRIMARY KEY, lastname text) WITH cosmosdb_provisioned_throughput=1200

.NET

int provisionedThroughput = 400;
var simpleStatement = new SimpleStatement($"CREATE TABLE {keyspaceName}.{tableName} (user_id int PRIMARY KEY, lastname text)");
var outgoingPayload = new Dictionary<string, byte[]>();
outgoingPayload["cosmosdb_provisioned_throughput"] = Encoding.UTF8.GetBytes(provisionedThroughput.ToString());
simpleStatement.SetOutgoingPayload(outgoingPayload);

Azure Cosmos DB provides guarantees for performance and latency, with upper bounds on operations. These guarantees are possible when the engine can enforce governance on the tenant's operations. Setting throughput ensures that you get the guaranteed throughput and latency, because the platform reserves this capacity and guarantees operation success.

When you go over this capacity, you get the following error message that indicates your capacity was used up:

0x1001 Overloaded: the request can't be processed because "Request Rate is large"

It's essential to see what operations (and their volume) cause this issue. You can get an idea about consumed capacity going over the provisioned capacity with metrics on the Azure portal. Then you need to ensure that capacity is consumed nearly equally across all underlying partitions. If you see that one partition is consuming most of the throughput, you have skew of workload.

Metrics are available that show you how throughput is used over hours, over days, and per seven days, across partitions or in aggregate. For more information, see Monitoring and debugging with metrics in Azure Cosmos DB.

Diagnostic logs are explained in the Azure Cosmos DB diagnostic logging article.

Yes, the partition key is used to place the entity in the right location. In Azure Cosmos DB, it's used to find the right logical partition that's stored on a physical partition. The partitioning concept is well explained in the Partition and scale in Azure Cosmos DB article. The essential takeaway here's that a logical partition shouldn't go over the 20-GB limit.

Azure Cosmos DB is a system based on service-level agreement (SLA). It provides unlimited scale, with guarantees for latency, throughput, availability, and consistency. This unlimited storage is based on horizontal scale-out of data, using partitioning as the key concept. The partitioning concept is well explained in the Partition and scale in Azure Cosmos DB article.

You should adhere to the 20-GB limit on the number of entities or items per logical partition. To ensure that your application scales well, we recommend that you not create a hot partition by storing all information in one partition and querying it. This error can come only if your data is skewed: that is, you have lot of data for one partition key (more than 20 GB). You can find the distribution of data by using the storage portal. The way to fix this error is to re-create the table and choose a granular primary (partition key), which allows better distribution of data.

Azure Cosmos DB can store unlimited data by scaling out the storage. This storage is independent of the throughput. Yes, you can always use the API for Cassandra just to store and retrieve keys and values by specifying the right primary/partition key. These individual keys get their own logical partition and sit atop a physical partition without issues.

Yes, it's possible to create more than one table with the API for Cassandra. Each of those tables is treated as unit for throughput and storage.

Azure Cosmos DB is resource-governed system for both data and control plane activities. Containers, like collections and tables, are runtime entities that are provisioned for a given throughput capacity. The creation of these containers in quick succession isn't an expected activity and might be throttled. If you have tests that drop or create tables immediately, try to space them out.

There's no physical limit on the number of tables. If you have a large number of tables (where the total steady size goes over 10 TB of data) that need to be created, not the usual tens or hundreds, send email to askcosmosdbcassandra@microsoft.com.

There's no physical limit on the number of keyspaces because they're metadata containers. If you have a large number of keyspaces, send email to askcosmosdbcassandra@microsoft.com.

Yes. Assuming uniformly distributed partitions, the storage capacity is automatically managed and increases as you push in more data. So you can confidently import as much data as you need without managing and provisioning nodes and more. But if you're anticipating numerous immediate data growth, it makes more sense to directly provision for the anticipated throughput rather than starting lower and increasing it immediately.

The API for Cassandra for Azure Cosmos DB provides protocol-level compatibility for executing operations. It hides away the complexity of management, monitoring, and configuration. As a developer/user, you don't need to worry about availability, tombstones, key cache, row cache, bloom filter, and a multitude of other settings. The API for Cassandra focuses on providing the read and write performance that you need without the overhead of configuration and management.

The API for Cassandra simplifies capacity planning and responding to the elasticity demands for throughput and storage. With Azure Cosmos DB, you provision the throughput that you need. Then you can scale it up and down any number of times through the day, without worrying about adding, deleting, or managing nodes. You don't need to use tools for node and cluster management.

Azure Cosmos DB provides global distribution out of the box for availability and low-latency reasons. You don't need to set up replicas or other things. Writes are always durably quorum committed in any region where you write, while providing performance guarantees.

Azure Cosmos DB provides performance guarantees for reads, writes, and throughput. So you don't need to worry about touching any of the configuration settings and accidentally manipulating them. Those settings include bloom filter, caching, read repair chance, gc_grace, and compression memtable_flush_period.

Yes, TTL is supported.

Azure Cosmos DB is a platform service that helps you increase productivity and not worry about managing and monitoring infrastructure. For example, you don't need to monitor node status, replica status, gc, and OS parameters earlier with various tools. You just need to take care of throughput that's available in portal metrics to see if you're getting throttled, and then increase or decrease that throughput. You can:

• Monitor SLAs
• Use metrics
• Use diagnostic logs

The Apache Cassandra SDK's client drivers that use CQLv3 were used for client programs. If you have other drivers that you use or if you're facing issues, send mail to askcosmosdbcassandra@microsoft.com.

Yes, you can use regular syntax to create composite partition keys.

No, sstableloader isn't supported.

Now, Azure Cosmos DB has an optimized experience for a cloud environment without the overhead of operations. If you require pairing, send mail to askcosmosdbcassandra@microsoft.com with a description of your scenario. We're working on an offering to help pair the on-premises or cloud Cassandra cluster with the API for Cassandra for Azure Cosmos DB.

Azure Cosmos DB provides two free full backups taken at four-hour intervals across all APIs. So you don't need to set up a backup schedule.

You can manage the backup retention and frequency yourself.

If you want to restore from backup, send email to askcosmosdbcassandra@microsoft.com or raise a support case. Information about backup capability is provided in the Automatic online backup and restore with Azure Cosmos DB article.

The API for Cassandra borrows from the globally distributed platform of Azure Cosmos DB. To ensure that your application can tolerate datacenter downtime, enable at least one more region for the account in the Azure portal. For more information, see High availability with Azure Cosmos DB.

You can add as many regions as you want for the account and control where it can fail over to by providing a failover priority. To use the database, you need to provide an application there too. When you do so, your customers won't experience downtime.

No. The API for Cassandra supports secondary indexes, which behave in a similar way to Apache Cassandra. The API doesn't index every attribute by default.

Yes, this is supported. You can find details on how to enable this in the Use the Azure Cosmos DB Emulator for local development and testing article.

You can read about migration options in the Migrate your data to API for Cassandra account in Azure Cosmos DB tutorial.

Related content

• Get started with elastically scaling an Azure Cosmos DB for Apache Cassandra account

Next step