How to Configure Vnodes (num_tokens) for Optimal Cassandra Cluster Balance

Set num_tokens to 16 in conf/cassandra.yaml for homogeneous clusters, or assign proportionally higher values (32–64) to more powerful nodes in heterogeneous environments to weight token ownership by hardware capacity.

Apache Cassandra distributes data across the cluster using virtual nodes (vnodes) defined by the num_tokens parameter. Properly configuring this setting in conf/cassandra.yaml ensures uniform data distribution and prevents hot spots that degrade performance. When calibrated correctly, vnodes minimize the operational impact of node failures and accelerate the bootstrapping of new nodes into the ring.

Understanding Vnodes and Token Distribution

Vnodes divide the continuous hash ring into discrete ranges, allowing each physical node to own multiple non-contiguous token ranges. The Murmur3Partitioner hashes each row’s primary key into a 64-bit token, and the allocation algorithm places virtual tokens uniformly around the ring to balance the replicated load across the cluster.

The Role of num_tokens in Load Balancing

The num_tokens setting determines how many token ranges each node manages. A higher count provides finer granularity, allowing the cluster to distribute data more precisely according to node capacity. Conversely, nodes with fewer tokens own larger contiguous ranges of the token space, which concentrates data and request traffic, creating performance bottlenecks.

Recommended num_tokens Values by Cluster Profile

Choosing the correct value depends on cluster size and hardware uniformity. According to the Apache Cassandra source code, the default configuration ships with num_tokens: 16, which serves as a pragmatic baseline that balances distribution quality against metadata overhead.

Small Clusters (3 Nodes or Fewer)

For clusters with three or fewer nodes, maintain the default value of 16 or increase modestly to 32. This provides sufficient granularity for balanced distribution without unnecessarily inflating the size of system tables that track token assignments.

Medium-to-Large Clusters (4+ Nodes)

In larger deployments, the default 16 tokens per node typically delivers optimal balance. You may increase this to 32 or 64 to further reduce the impact of a single node failure, as the workload redistributes across more, smaller token ranges. However, each additional token increases overhead for gossip communication and repair operations, so load test before deploying higher values in production.

Heterogeneous Hardware Environments

When nodes have different CPU, memory, or storage capacities, assign num_tokens proportionally to hardware strength. Configure powerful nodes with 32 or 64 tokens and weaker nodes with 16 (or lower). This weights token ownership by capacity, ensuring that high-performance nodes handle proportionally more data and traffic than resource-constrained peers.

How Cassandra Assigns Tokens at Startup

When a node starts, Cassandra checks the num_tokens setting in conf/cassandra.yaml located at lines 42–50. If the node has no initial_token defined, the auto-allocation algorithm implemented in src/java/org/apache/cassandra/allocator/TokenAllocation.java automatically computes token positions that minimize overlap with existing nodes while respecting the replication factor of each keyspace. This automatic allocation is only supported when using the Murmur3Partitioner.

If initial_token is explicitly defined, that list overrides automatic allocation, and Cassandra assigns the exact tokens specified rather than calculating an optimal distribution.

Configuring num_tokens in Production

Edit the primary configuration file to adjust virtual node counts. The following example increases the token count to 32 for a node in a large cluster:

# conf/cassandra.yaml

# Lines 42-50 contain the num_tokens definition

num_tokens: 32

To bootstrap a new node with a custom token count (for example, 64 tokens on a high-capacity server):

# Set the token count on the new host before starting Cassandra

sed -i 's/^num_tokens:.*/num_tokens: 64/' /etc/cassandra/conf/cassandra.yaml

# Start the service; TokenAllocation.java will compute 64 optimal positions

systemctl start cassandra

Verifying Token Distribution

After startup or topology changes, verify that tokens distribute evenly across the cluster:

# Display node status and ownership percentages

nodetool status

# View detailed token ranges per node (requires authentication if enabled)

nodetool ring -u username -pw password

The owns column in nodetool status should show approximately equal percentages across all nodes with identical num_tokens values. Significant deviations indicate configuration errors or uneven token assignment.

Summary

• Default choice: Use num_tokens: 16 in conf/cassandra.yaml for most production clusters with homogeneous hardware.
• Scale considerations: Increase to 32 or 64 in large clusters to improve failure isolation, but monitor gossip and repair overhead.
• Hardware weighting: Assign higher values to powerful nodes and lower values to weak nodes to balance load proportionally.
• Automatic allocation: Rely on the algorithm in TokenAllocation.java by leaving initial_token unset; manual token assignment bypasses automatic balancing.
• Verification: Always confirm distribution with nodetool status and nodetool ring after configuration changes.

Frequently Asked Questions

What is the default num_tokens value in Cassandra?

The default value is 16. This is defined in conf/cassandra.yaml and provides a practical balance between fine-grained data distribution and manageable system table overhead for most deployments.

Can I change num_tokens on an existing node?

No. Changing num_tokens on a node that has already joined the cluster requires decommissioning the node, wiping the data directory, and re-bootstrapping it with the new value. Modifying this setting live can cause token collisions and data inconsistency.

How does num_tokens affect repair operations?

Each additional token increases the metadata managed by the gossip protocol and creates more discrete token ranges that require individual repair operations. While values of 32 or 64 improve balance, they generate more repair tasks than the default 16, potentially increasing system load during maintenance windows.

Does Cassandra support automatic token allocation with all partitioners?

No. The automatic token allocation algorithm implemented in TokenAllocation.java only functions with the Murmur3Partitioner. If you use the RandomPartitioner or a custom partitioner, you must manually specify token assignments using the initial_token configuration parameter.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}