Cassandra BATCH statements are fundamentally misunderstood, often leading to performance degradation because they don’t provide atomicity or speedups in the way most developers expect.
Let’s see it in action. Imagine you have a table users with user_id as the primary key and you want to insert a few users. A common, but often misused, approach looks like this:
BEGIN BATCH
INSERT INTO users (user_id, name, email) VALUES (1, 'Alice', 'alice@example.com');
INSERT INTO users (user_id, name, email) VALUES (2, 'Bob', 'bob@example.com');
INSERT INTO users (user_id, name, email) VALUES (3, 'Charlie', 'charlie@example.com');
APPLY BATCH;
This looks like a transaction, right? Like a single unit of work where either all inserts succeed or none do. This is where the misunderstanding begins.
Cassandra’s BATCH statement is primarily a performance optimization for reducing network round trips when you have multiple, independent mutations (inserts, updates, deletes) to send to the coordinator node. It bundles these mutations into a single request from the client to the coordinator. The coordinator then forwards these mutations to the appropriate nodes.
The crucial point is that by default, BATCH statements are unlogged. This means the coordinator does not guarantee atomicity. If a node fails during the execution of an unlogged batch, some mutations might be applied, and others might not. There’s no rollback. The coordinator simply tries its best to send all the mutations to the relevant nodes.
Think of it like this: you have a stack of postcards you want to mail. You could put each one in a separate envelope and mail them individually (single INSERT statements), which involves many trips to the mailbox. Or, you could put them all in one large envelope and mail them together (a BATCH statement), saving you trips to the mailbox. However, if the postal service loses some of the postcards within that large envelope, you won’t get them all back, and you won’t know which ones were lost without checking individually.
The problem arises when developers assume BATCH provides transactional guarantees like ACID properties (Atomicity, Consistency, Isolation, Durability) found in traditional relational databases. Cassandra’s distributed nature and tunable consistency make true ACID transactions across multiple partitions or even multiple mutations within a single partition a complex problem.
So, what can you control, and what are the real implications?
-
Network Round Trips: This is the primary benefit. For N mutations, instead of N network requests to the coordinator, you send 1. This is especially beneficial for high-throughput scenarios where latency from repeated network calls becomes a bottleneck.
-
Coordinator Load: The coordinator node receives the entire batch and is responsible for dispatching the individual mutations to the other nodes. A very large batch can put significant load on the coordinator.
-
No Atomicity (Unlogged Batches): This is the biggest pitfall. If the coordinator crashes after sending some mutations but before sending others, or if a replica node fails to apply a mutation, the batch is not atomic. Some writes will succeed, others might fail or be lost.
-
Logged Batches: Cassandra does offer
LOGGED BATCH. This provides atomicity by writing the batch to a distributed commit log before sending mutations to the individual nodes. If any node fails during the write, Cassandra can use the commit log to ensure all mutations are eventually applied or none are. However, logged batches come with a significant performance penalty:- They require a commit log write on every replica node involved in the batch, not just the coordinator.
- They increase latency.
- They are generally discouraged for anything other than very small, critical batches where atomicity is absolutely paramount.
-
Batch Size Limits: To prevent abuse and accidental denial-of-service, Cassandra has configuration settings that limit batch sizes. The most relevant is
concurrent_counter_updates(which also affects batches of counter updates) andcassandra.max_batch_size_in_bytes(an internal Java system property, not acassandra.yamlsetting, but often cited). While there isn’t a single, simplemax_batch_sizeincassandra.yaml, large batches can be throttled or rejected. A common heuristic is to keep batches under 50-100 mutations, or a few KB in size.
The most surprising truth about Cassandra BATCH is that for mutations targeting the same partition key, Cassandra often optimizes them internally without a BATCH statement. If you send multiple INSERT or UPDATE statements to the coordinator for different columns within the same row (i.e., same partition key), the coordinator can often coalesce these into a single disk write for that row, effectively giving you the benefit of a batch without you having to explicitly write BEGIN BATCH. This is why BATCH is truly only beneficial when you are writing to different partitions.
The next concept you’ll likely encounter when dealing with distributed data writes is Tombstones.