Token Ranges

The hash function computes a token for a given partition key, and the token determines the placement of the data in the cluster . Starting with ScyllaDB 2025.1, new keyspaces use tablets by default. Each table is split into tablets, and each tablet covers a range of tokens. A tablet map records which nodes and shards hold the replicas of each tablet. ScyllaDB moves tablets between nodes and shards in the background to keep the load balanced, for example when nodes are added or removed, and splits a tablet when it grows too large.

Older versions of ScyllaDB use Vnodes (virtual nodes) instead: each node owns many fixed, non-contiguous token ranges (256 by default) for all the tables in a keyspace. You can read more about Vnodes in ScyllaDB Docs , and about tablets in this lesson . With tablets, token ranges belong to each table, so let’s first create a table in the scyllau keyspace that we created on the multi-DC cluster:

docker exec -it scylla-node1 cqlsh -e "CREATE TABLE scyllau.users ( user_id int, fname text, lname text, PRIMARY KEY((user_id)));"

To see the token ranges of the table, we use the nodetool ring command with the keyspace and table names:

docker exec -it scylla-node1 nodetool ring scyllau users

The output is grouped by datacenter. The value in the Token column is the end of a token range, up to (and including) the value listed, and the Address column shows one of the nodes holding a replica of that range, not all of them. The Owns column shows how much of the table’s data each node holds a replica of: in DC1, with three nodes and a replication factor of 3, every node holds all of it (100%). Another way to show the token ranges is the describering command, which lists every token range of the table with all its replicas:

docker exec -it scylla-node1 nodetool describering scyllau users

In this lab, the table starts with 16 tablets, so there are 16 token ranges. Each one has five endpoints: three in DC1 and two in DC2, matching the replication factor of the keyspace. Without the table name, both commands fail with an error, because a keyspace that uses tablets has no token ranges of its own.