Apache Cassandra
In plain English
Plain definition
Apache Cassandra is an open source, distributed NoSQL database that places rows on a token ring by hashing the partition key and keeps replication-factor copies on different nodes, with no primary. Cassandra never runs repair itself, so schedule nodetool repair to finish inside gc_grace_seconds, ten days by default, or deleted data can reappear.
Apache Cassandra is an open source, distributed NoSQL database that spreads rows across nodes by hashing each row’s partition key and keeps several copies of every partition, with no primary node. The constraint that catches operators: Cassandra never runs repair for you. Hints and read repair are best effort, so nodetool repair has to run on a schedule, finishing inside each table’s gc_grace_seconds (864000 seconds, ten days, by default), or deleted data can reappear.
In plain terms, a database with no primary node
Data lives in tables inside keyspaces, queried with CQL, which looks like SQL. A table’s partition key decides which nodes hold each row. Nodes share state through a peer-to-peer gossip protocol, and you grow by adding nodes, not by buying a bigger server.
How it works across the token ring
Each node owns one or more tokens on a hash ring. To place a row, Cassandra hashes the partition key to a token, then walks the ring clockwise until it has found as many distinct nodes as the keyspace’s replication factor (RF).
The keyspace sets the replication strategy. NetworkTopologyStrategy takes an RF per datacenter and tries to place replicas on different racks; the project recommends it for all production clusters, even single-datacenter ones. SimpleStrategy ignores datacenters and racks and suits test clusters only.
On each node a write goes to the commit log and an in-memory memtable, which is later flushed to an immutable SSTable on disk. Compaction merges SSTables and discards tombstones in the background. Replicas resolve conflicts by last write wins, using a timestamp on every column, so every node needs working time synchronisation such as NTP.
Where you meet it day to day
The coordinator sends every write to all replicas. The consistency level only sets how many must acknowledge before the client gets an answer: ONE, QUORUM (a majority, n/2 + 1), LOCAL_QUORUM (a majority in the coordinator’s datacenter), ALL and others. With RF 3, writing and reading at QUORUM guarantees at least one replica takes part in both, so the read sees the acknowledged write.
When a replica is down, the coordinator stores a hint on its own disk and replays it when the replica returns, but only for outages inside the hint window, three hours by default. After that the replica stays out of date until read repair or anti-entropy repair catches it up. Repair compares Merkle trees and streams only the ranges that differ.
Where it fits among Dynamo and Bigtable ideas
Cassandra pairs Amazon Dynamo’s partitioning, replication and gossip membership with a Bigtable-style storage model built on log-structured merge trees. A failed node is never removed from gossip state automatically: an operator decommissions it or bootstraps a replacement, so a short outage does not trigger a needless rebalance.
An example of reading cluster state without changing it
nodetool status on any node prints the ring as that node sees it (Host IDs shortened here):
Datacenter: us-east-1
=====================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
-- Address Load Tokens Owns Host ID Rack
UN 10.0.1.115 547 KiB 256 ? b64cb32a us-east-1b
UN 10.0.3.206 617.91 KiB 256 ? 74863177 us-east-1d
UN 10.0.2.238 670.26 KiB 256 ? 4dcdadd2 us-east-1c
Read UN against the legend: Up and Normal. In cqlsh, DESCRIBE KEYSPACE my_keyspace prints the keyspace’s DDL, including its replication settings. Neither command changes data.
A common misconception about consistency levels
A write at ONE is not a write to one node. It still goes to every replica; the coordinator answers the client after the first acknowledgement. A lower level buys lower latency and higher availability, not less write traffic.
Related terms
- Replication factor: the total number of copies of each row across the cluster.
- Hinted handoff: replaying missed writes to a replica that was briefly unavailable.
- Tombstone: a deletion marker, kept for
gc_grace_secondsbefore compaction can discard it.
Further reading in the Cassandra documentation
Start with the Dynamo architecture page, then the operating pages on repair and hints.
Before you change replication or start a repair
Confirm every node shows UN in nodetool status, and save the DESCRIBE KEYSPACE output so the current replication settings are on record. Repair is heavy on disk and network; run nodetool repair --preview first: it builds the Merkle trees and estimates the streaming without moving data. After raising a keyspace’s RF, run a full repair (nodetool repair --full) so the new replicas receive their data. For the whole cluster, run nodetool repair -pr on every node in every datacenter, well inside gc_grace_seconds.
Authoritative Sources
Technology documentation
Overview
Cassandra Basics
Dynamo
Storage Engine
Repair
Hints
nodetool status
Data Definition
cqlsh: the CQL shell
Glossary
About this page
Credited to
Dates
Published
Corrections
No corrections are listed for this page. Some review sweeps corrected pages without naming each one; those are in the corrections log.
Was this useful?
Reports go to the site owner and are used to correct pages. Corrections are listed at /corrections.