Cassandra Fundamentals — Partition Keys and Consistency
Cassandra is built for write-heavy workloads at massive scale. The data model is designed around queries — not the other way around.
🗄️ Cassandra 5CQLPartition KeysConsistency LevelsBoraPay⏱ 20 min
Lesson 25 of Big Data TrackIntermediate
🗄️ What is Cassandra?
Apache Cassandra is a NoSQL wide-column database designed for high-availability, write-heavy workloads. It is the engine behind some of the world's largest real-time data platforms — used by companies running social feeds, payment ledgers, IoT sensor streams, and messaging systems.
Why Cassandra?
Cassandra has no single point of failure. Every node in the cluster is equal — there is no master. Reads and writes are distributed across nodes using a partition key hash. You scale by adding nodes, not by buying a bigger machine. Major platforms use it for exactly this reason: it keeps writing fast even as data volume grows into the petabytes.
Key characteristics: masterless peer-to-peer architecture, linear horizontal scalability, tunable consistency, and an append-only write path that makes writes extremely fast.
⚖️ Cassandra vs RDBMS
Understanding what Cassandra trades away — and what it gains — is the foundation of good data modelling with it.
Dimension
RDBMS (Postgres / MySQL)
Cassandra
Schema
Rigid — ALTER TABLE is disruptive in production
Flexible — you can add columns to an existing table online
Joins
Native, any column can be joined
Not supported — query-first design instead
Consistency
Strong (ACID transactions)
Tunable — from eventual to strong, per query
Write performance
Limited by B-tree index updates on every write
Extremely fast — append-only log, no in-place updates
Scale
Vertical — buy a bigger machine
Horizontal — add nodes to the ring
Best for
OLTP, reporting, complex ad-hoc queries
Time-series, IoT, write-heavy, known query patterns
Wanjiku's rule of thumb at BoraPay: "If the question is 'give me all payments by this sender in the last 24 hours', use Cassandra. If the question is 'give me the total revenue grouped by city this quarter', use DuckDB or Postgres."
📐 The Cassandra data model
In a relational database, you design tables to represent entities and their relationships, then write queries to join them. In Cassandra, you do it backwards: start with the query, then design the table.
This means you often have multiple tables storing the same underlying data — each table optimised for one specific query pattern. This redundancy is intentional and expected. Cassandra has no query planner that can dynamically reorder or join data; it routes each read to the exact partition where the data lives.
The golden rule of Cassandra modelling
Every query must start with WHERE partition_key = ?. If you cannot specify the partition key in your query, Cassandra must scan the entire table — which is the ALLOW FILTERING anti-pattern. Design your tables so every query you need has a matching partition key.
🛠️ Keyspace and table creation
Connect to Cassandra via CQLSH and create the BoraPay keyspace and payments table. The PRIMARY KEY definition is the most important decision you will make.
Cassandra must be running (docker compose up cassandra). Output will vary.
CQL
Lesson 25 · keyspace and table creation
Sample output — Cassandra must be running (docker compose up cassandra). Output will vary.
The primary key declaration is the most important line in any Cassandra table. It controls both where data is stored and how it is sorted within that location.
What this means in practice
All rows with the same sender_id live on the same node(s). A query WHERE sender_id = 'ACC101' goes to exactly one node — no scatter-gather across the cluster. Within that partition, rows are sorted by event_time DESC then txn_id, which is why LIMIT 10 returns the 10 most recent transactions efficiently without sorting.
✍️ Insert and query
Insert two payment events for sender ACC101, then query the most recent 10 payments for that sender. Cassandra returns them in reverse-chronological order because of the CLUSTERING ORDER BY (event_time DESC) definition.
Cassandra must be running (docker compose up cassandra). Output will vary.
CQL
Lesson 25 · insert and query
Sample output — Cassandra must be running (docker compose up cassandra). Output will vary.
Cassandra's tunable consistency is one of its most powerful features. You choose the trade-off between durability and latency per query, not as a global database setting.
With a replication factor of 3, Cassandra stores each row on 3 nodes. The consistency level controls how many of those 3 nodes must acknowledge before the operation is considered complete.
Level
Reads/Writes from
Durability
Latency
ONE
1 replica
Lowest — one node down loses the write
Fastest
QUORUM
Majority (N/2 + 1 replicas)
Strong — survives minority node failure
Medium
ALL
All replicas
Highest — any node down = write fails
Slowest
LOCAL_QUORUM
Majority in the local data centre
DC-strong — survives local minority failure
Low cross-DC latency
Wanjiku's consistency choice at BoraPay
"At BoraPay we use LOCAL_QUORUM for payment writes — durability matters because a missing transaction costs us real money and customer trust. For read-heavy notification lookups, we use ONE — latency matters more than perfect consistency there. A notification appearing one second late is fine. A payment that disappears is not. This is Cassandra's tunable consistency in practice."
⚠️ Common Cassandra anti-patterns
The most dangerous anti-pattern in Cassandra is ALLOW FILTERING. When Cassandra cannot route a query to a specific partition using the partition key, it performs a full table scan — reading every row in the cluster. At scale this kills throughput for every other query running simultaneously.
CQL
Lesson 25 · ALLOW FILTERING trap vs correct design
Kwame's note from the BoraPay incident retrospective: "We had an ALLOW FILTERING query in our nightly reconciliation job. As the payments table grew past 200 million rows, that one query started timing out and causing read pressure on every node. Fixing it meant creating a failed_payments table — 2 hours of work — and the nightly job went from 40 minutes to 8 seconds."
❌ Common mistakes
Designing by entities, not queries
Relational thinking — modelling "users", "accounts", "transactions" and joining them — does not work in Cassandra. Without join support, every query must be answered by a single table. Start with the query, then design the table around it.
Unbounded partition growth
If one partition key has millions of rows (e.g. a single account with a huge transaction history), that partition becomes a hotspot. That single node handles all reads and writes for that key. Use a compound partition key or time-bucket prefix to spread the load.
ALLOW FILTERING in production
Cassandra lets you add ALLOW FILTERING to make a query work without the partition key. This performs a full table scan that degrades cluster performance for every concurrent operation. Treat it as a schema design signal, not a solution.
UUID as partition key without thought
A UUID as the sole partition key spreads data perfectly but makes range queries impossible — you can only query by exact UUID. If you need "all events for user X", the partition key must include the user identifier, not just a random UUID.
🧠 Quiz — 3 questions
Question 1 of 3
In Cassandra, the partition key determines:
Question 2 of 3
ALLOW FILTERING in a Cassandra query means:
Question 3 of 3
LOCAL_QUORUM consistency means:
0
/ 3
Cassandra fundamentals complete.
Next: wire Kafka to Cassandra in the mini-build.
🎤 Interview Q&A
MediumHow is Cassandra's data model different from a relational database?
+
In a relational database, you design tables around entities (users, orders, products) and write queries to join them at read time. The query planner figures out how to satisfy any query you throw at it. In Cassandra, there is no join support and no query planner that can dynamically reorder operations. Instead, you design each table around a specific query pattern — the table structure encodes how you will access the data. This means a single logical entity often lives in multiple denormalised tables, one per access pattern. The payoff is that every query hits a single partition on a single node: no cross-node coordination, no join overhead, and predictable low-latency reads at any scale.
MediumWhat is a partition key and why does partition size matter?
+
The partition key is the part of the primary key that Cassandra hashes to determine which node(s) store a row. All rows with the same partition key value live on the same physical node (and its replicas). Partition size matters because Cassandra recommends keeping partitions under 100 MB (roughly hundreds of thousands of rows). A partition that grows too large — for example, a single user ID with millions of rows — becomes a hotspot: all reads and writes for that key go to one node, which can't be load-balanced. The fix is a composite partition key: for example, adding a time-bucket prefix ((sender_id, month)) so that each month's data for a sender is a separate, bounded partition.
HardExplain tunable consistency in Cassandra.
+
Cassandra stores N copies of every row (where N = replication factor). Tunable consistency lets you specify, per query, how many of those N replicas must acknowledge before the operation succeeds. The options range from ONE (only 1 replica must respond — fastest, weakest durability) through QUORUM (majority of replicas — balanced) to ALL (every replica must respond — strongest durability, highest latency). The key insight is that strong consistency is achieved when write consistency + read consistency > replication factor. For example, with RF=3, writing at QUORUM (2 nodes) and reading at QUORUM (2 nodes) guarantees the reader will always see the latest write — because at least one of the 2 read nodes must overlap with the 2 write nodes. This flexibility lets you tune each operation to its business requirement: payment writes at LOCAL_QUORUM for durability, notification reads at ONE for speed.
✅ Key takeaways
Cassandra is a masterless, horizontally scalable NoSQL database designed for write-heavy workloads — you scale by adding nodes, not by buying bigger hardware.
The partition key determines which node stores a row. Every efficient query must start with WHERE partition_key = ?. Design tables around queries, not entities.
Clustering keys define the sort order within a partition. CLUSTERING ORDER BY (event_time DESC) means your most recent payments come back first with no runtime sort.
Consistency is tunable per query. Use LOCAL_QUORUM for writes that require durability and ONE for reads where latency matters more than perfect consistency.