Cassandra Tokens and Ring

Cassandra distributes data across nodes using a ring of tokens. Every row of data maps to a numeric token based on the hash of its partition key. Every node owns a range of tokens on the ring. Understanding tokens and the ring explains how Cassandra balances data and how it knows exactly which node to contact for any read or write.

The Pizza Delivery Zone Analogy

A city is divided into delivery zones. Each pizza restaurant owns one zone and delivers only to addresses in that zone. A central dispatcher maps every address to the correct zone and routes orders accordingly. Cassandra's ring works the same way — the ring is the city, tokens are the zone boundaries, nodes are the restaurants, and the partitioner is the dispatcher.

What Is a Token?

A token is a number that the partitioner produces by hashing a partition key. The default partitioner (Murmur3Partitioner) produces tokens in the range from -2^63 to 2^63-1. Every partition key maps to exactly one token, and that token determines which node stores the data.

Partition key: 'user-alice'
       │
Murmur3 hash
       │
Token: -4,611,686,018,427,387,904
       │
Token belongs to Node C's range
       │
Data stored on Node C (and its replicas)

The Ring

Visualize all possible token values arranged in a circle — this is the ring. Each node owns a contiguous arc of that circle. When a write arrives, the coordinator computes the partition key's token and finds the node whose arc contains that token.

Ring with 4 nodes, token ranges:

           Node A
       (owns 0 to 2.3Q)
      /                 \
Node D                  Node B
(owns -4.6Q to 0)       (owns 2.3Q to 4.6Q)
      \                 /
           Node C
       (owns -9.2Q to -4.6Q)

(Q = quadrillion tokens approximately)

Write with token 1.5Q → Node A handles it.
Write with token 3.0Q → Node B handles it.

Manual Token Assignment (pre-vnodes)

In older Cassandra deployments (before virtual nodes), each node was assigned one token manually. The token determined exactly which arc of the ring the node owned. This required careful planning to distribute data evenly.

# cassandra.yaml (manual token, legacy approach)
initial_token: -4611686018427387904

If tokens were poorly chosen, some nodes ended up with more data than others — an imbalance called a hotspot. Virtual nodes (vnodes) solve this problem automatically.

Virtual Nodes (vnodes)

Instead of owning one large arc, each node owns many small arcs scattered around the ring. These small arcs are called virtual nodes or vnodes. Cassandra randomly assigns 256 vnodes per physical node by default, which distributes data evenly without manual token planning.

Physical node owns 256 scattered mini-ranges:

Ring: ─────────────────────────────────────────

Node A's 256 vnodes (shown as A):
  ...A...B...C...A...D...A...B...C...A...D...A...

Total ring view (4 physical nodes):
Each physical node owns roughly 1/4 of the total token space
via 256 small scattered segments.

Checking Token Distribution

# Show token ownership per node:
nodetool ring

# Show what percentage of the ring each node owns:
nodetool status

Datacenter: datacenter1
=======================
--  Address    ...  Tokens  Owns
UN  10.0.0.1   ...  256     25.1%
UN  10.0.0.2   ...  256     24.9%
UN  10.0.0.3   ...  256     25.0%
UN  10.0.0.4   ...  256     25.0%

Token and Replication

When data writes to a primary node (the node whose token range contains the partition's token), Cassandra copies that data to the next N-1 nodes clockwise on the ring, where N is the replication factor. This ensures every piece of data lives on multiple nodes.

RF = 3, token for partition P maps to Node A:

Primary replica  → Node A
Replica 2        → Node B (next clockwise)
Replica 3        → Node C (next clockwise after B)

If Node A fails, Node B or C serves reads and writes.

Partitioner Types

Partitioner              Token Range           Notes
──────────────────────────────────────────────────────────────────
Murmur3Partitioner       -2^63 to 2^63-1      Default; best even
(default)                                     distribution
RandomPartitioner        0 to 2^127           Legacy; MD5 hash
ByteOrderedPartitioner   Byte-ordered         Keys stored in order
                                              (enables range scans
                                              but causes hotspots)

Always use Murmur3Partitioner. ByteOrderedPartitioner distributes data unevenly because sequential keys all land on the same node, creating a hotspot.

Summary

Cassandra uses a ring of tokens to distribute data across nodes. The Murmur3 hash function maps each partition key to a token, and the node owning that token's range stores the data. Virtual nodes scatter 256 token ranges per physical node to achieve even distribution automatically. Replication places additional copies on the next nodes clockwise around the ring. Understanding the ring and tokens is the foundation for understanding how Cassandra adds nodes, balances load, and routes requests.