Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 30 ยท The Two Architectures

Cassandra architecture in one picture

See how Cassandra spreads data over a peer-to-peer ring of nodes, how token ranges decide ownership and how the replication factor keeps copies.

Most databases you have met have a boss: one primary server takes the writes, and replicas copy from it. Apache Cassandra has no boss. Every node in a cluster is equal, any node can accept any request, and the data is spread over the nodes by a simple rule based on a hash of the key. That one design choice explains almost everything else about Cassandra: why it scales by adding machines, why it survives a node dying without a failover drama, and why you have to think about your queries before you create your tables.

This lesson draws the whole architecture in one picture and then explains each part: nodes, the token ring, token ranges, the replication factor and the coordinator. The real Cassandra needs a cluster of servers, so the diagrams and cluster commands here are read-only. The JavaScript stand-ins implement the ring idea with a tiny hash function so you can place keys and add a node yourself. They are teaching models: real Cassandra uses a different hash (Murmur3, with 64-bit tokens) and much more machinery.

The picture

flowchart TD
    C["Client driver"] --> N1
    subgraph Ring["Cassandra cluster (a ring of equal nodes)"]
        N1["Node 1<br/>token range 1"]
        N2["Node 2<br/>token range 2"]
        N3["Node 3<br/>token range 3"]
        N4["Node 4<br/>token range 4"]
        N1 --- N2
        N2 --- N3
        N3 --- N4
        N4 --- N1
    end
    N1 -. "forwards to replicas" .-> N3
    N1 -. "forwards to replicas" .-> N4

A client contacts any node, which becomes the coordinator and forwards the request to the nodes that own the data.

Read it from the top. The client (through a driver library) connects to the cluster and sends a query to one node. That node is the coordinator for this request: it works out which nodes hold the data and talks to them. A different request can use a different coordinator. There is no special node that every request must pass through.

Nodes and the peer-to-peer design

A node is one running Cassandra process with its own disk. A group of nodes that work together is a cluster. Nodes learn about each other through a gossip protocol: every second or so each node chats with a few others and exchanges what it knows about who is up, who is down and who owns what. Nobody is in charge of that knowledge, so there is no central place that can fail.

The consequences are practical:

  • No single point of failure. If a node dies, the others carry on.
  • No failover step. A replica-based setup with a primary must promote a new primary; in Cassandra the other replicas already accept writes.
  • Linear scaling. Adding a node adds capacity for both storage and traffic.

The token ring

Cassandra turns every partition key into a number called a token, using a hash function. A good hash scatters keys evenly: alice and alicf land far apart. All possible tokens form a circle, the ring, because the largest token wraps around to the smallest.

Each node is assigned one or more tokens. A node owns the token range that ends at its token and starts just after the previous node's token. To find the home of a key you hash it, find the place on the ring and use the node that owns that range.

Because the placement depends only on the key and the current list of tokens, any node can compute it. That is why any node can be a coordinator.

Virtual nodes

If every machine owned a single big range, a cluster could be badly unbalanced, and adding a machine would take data from only one neighbour. Cassandra therefore gives each machine many small ranges, called virtual nodes (vnodes). A machine with, for example, 16 tokens owns 16 little slices scattered around the ring, so its load averages out and a new machine takes a little from everybody.

Replication factor

One copy of the data on one node would be lost with that node. The replication factor (RF) says how many nodes keep a copy of each partition. With RF = 3, after finding the owner of the token, Cassandra also stores the data on the next nodes around the ring until three different nodes hold it. These copies are all equal replicas: there is no "primary replica" that is more important than the others.

RF is a property of a keyspace (the Cassandra word for a database, covered in CQL: keyspaces, tables and basic queries). This is the read-only statement that sets it:

SQL
CREATE KEYSPACE shop
  WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3};

SimpleStrategy is fine for a single-datacenter learning setup. Production clusters spread over several datacenters use NetworkTopologyStrategy, which you will meet in Multi-datacenter setups and security.

Stand-in 1: placing keys on a ring

The code below builds a ring of four nodes with a tiny hash (FNV-1a, reduced to the numbers 0 to 999 so the output is easy to read). It then shows which nodes would store each key with RF = 1 and with RF = 3. With RF = 3 the replicas are always consecutive nodes around the ring, and a key owned by the last node continues with the first nodes, which is the wrap-around of the circle.

JS A four-node token ring

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With RF = 3 on four nodes, every key lives on three of the four nodes, so any single node can disappear without losing data. In the real system you would then lean on tunable consistency to decide how many of those replicas must answer a request.

Why hashing instead of sorting?

You might wonder why Cassandra hashes keys instead of splitting the key space alphabetically. Sorted ranges make range scans easy, but they create hot spots: if all new keys start with the current date, one node gets all the writes. Hashing destroys the order of keys on purpose, which spreads load evenly. The price is that you cannot ask the cluster for "all partitions between alice and carol" in key order. Ordering is something Cassandra gives you only inside a partition, which you will explore in Partition keys and clustering keys.

If hashing and rings sound familiar, they are the same idea as consistent hashing from the data-structures track.

Stand-in 2: adding a node, and why vnodes help

This second program uses 2,000 keys. It adds a fifth node to the ring and counts how many keys had to move. It compares that to a naive hash % number_of_nodes rule, where changing the node count reshuffles almost everything. Finally it compares one token per node to sixteen tokens per node to show how more tokens even out the load.

JS Adding a node to the ring

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Look at the results. Adding node-E moved only the keys in one range (248 of 2,000), and those keys moved from node-B to the new node, so everyone else was untouched. The naive modulo rule moved 1,606 keys. And with one token per node the busiest node holds several times more than the quietest (a ratio of 8.60 here), while sixteen tokens each narrows the gap to 2.38. The exact numbers belong to this toy hash and these node names; the shape of the result is what real clusters rely on.

What is real and what is the stand-in

Idea Real Cassandra In the stand-in
Hash Murmur3, 64-bit tokens FNV-1a, 0 to 999
Token assignment Random vnodes or allocated tokens Chosen by hand or from node names
Replica choice Strategy-aware, can avoid racks and datacenters Next nodes clockwise
Cluster knowledge Gossip between nodes One shared array

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does it mean that Cassandra is peer-to-peer?

    There is no primary. Any node can receive a request and act as its coordinator, so no single machine is a bottleneck or a single point of failure.
  2. 2. How does Cassandra decide which node owns a partition?

    The token comes from a hash of the partition key. Anyone who knows the token ranges can work out the owners without asking a central server.
  3. 3. With a replication factor of 3, how many nodes store a copy of each partition?

    RF is the number of nodes that hold a copy. All replicas are equal; no replica is the special one.
  4. 4. Why do virtual nodes help?

    Many small ranges per machine smooth out the distribution and spread the data movement when nodes join or leave.

Summary

  • A Cassandra cluster is a ring of equal nodes with no primary; any node can be the coordinator of a request.
  • A hash of the partition key gives a token; each node owns token ranges; vnodes give each machine many small ranges.
  • The replication factor sets how many nodes keep a copy; replicas are placed on the next nodes around the ring.
  • Hashing spreads load evenly but gives up ordering across partitions, which is why Cassandra only sorts rows inside a partition.
  • The stand-ins use a toy hash to show the placement idea; real Cassandra uses Murmur3 and a lot more machinery.

Next: Neo4j and the property graph model.