🗄️ 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.
sample output
cqlsh> CREATE KEYSPACE borapay ... cqlsh> USE borapay; cqlsh:borapay> CREATE TABLE payments ... cqlsh:borapay>

🔑 Primary key anatomy

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.

PRIMARY KEY ((sender_id), event_time, txn_id) sender_id PARTITION KEY event_time CLUSTERING KEY 1 txn_id CLUSTERING KEY 2 Determines which node(s) store this row Sort order within the partition (DESC)
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.
sample output
txn_id | receiver_id | amount_kes | status --------------------------------------+-------------+------------+----------- a1b2c3d4-... | ACC202 | 12500.00 | completed e5f6g7h8-... | ACC201 | 5000.00 | completed (2 rows)

🎚️ Consistency levels

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

Medium How 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.

Medium What 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.

Hard Explain 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.
Africa & India's Best AI Academy
🤖 AI-first 🎓 Placement Assistance

Build the architecture BoraPay runs on

Join the Best AI Program: The AI-Era Data Engineer — 5 months, fully online, with placement assistance. Week 1 is free.

Explore The AI-Era Data Engineer →