Configuring and using virtual nodes (vnodes)

A description of virtual nodes (vnodes) and using them in different types of datacenters. Also steps for disabling vnodes.

Virtual nodes simplify many tasks in Cassandra, such as eliminating the need to determine the partition range (calculate and assign tokens), rebalancing the cluster when adding or removing nodes, and replacing dead nodes. For a complete description of virtual nodes and how they work, see About virtual nodes, and the Virtual nodes in Cassandra 1.2 blog.

Attention: DataStax Enterprise turns off virtual nodes (vnodes) by default. DataStax does not recommend turning on vnodes for DSE Hadoop or BYOH nodes. Before turning vnodes on for Hadoop, understand the implications. DataStax Enterprise does support turning on vnodes for Spark nodes.

Guidelines for using virtual nodes

In the cassandra.yaml file, uncomment num_tokens and leave the initial_token parameter unset. Guidelines for using virtual nodes include:

  • Determining the num_tokens value:

    The recommended initial value for num_tokens is 256. For more guidance, see Setting up virtual nodes.

  • Migrating existing clusters:

    To upgrade existing clusters to vnodes, see Enabling virtual nodes on an existing production cluster.

  • Using vnodes in a mixed architecture deployment:
    Cassandra supports using virtual node-enabled and non-virtual node datacenters. For example, a single cluster with:
    • A cassandra-only datacenter running OLTP.
    • A analytics datacenter without vnodes
    • A search datacenter with vnodes.

Disabling vnodes

Important: If you do not use vnodes, you must make sure that each node is responsible for roughly an equal amount of data. To ensure that each node is responsible for an equal amount of data, assign each node an initial-token value and calculate the tokens for each datacenter as described in Generating tokens. You can also use the default Murmur3Partitioner and calculate the tokens as described in Generating tokens.


  1. In the cassandra.yaml file, set num_tokens to 1.
    num_tokens: 1
    The location of the cassandra.yaml file depends on the type of installation:
    Package installations /etc/dse/cassandra/cassandra.yaml
    Tarball installations install_location/resources/cassandra/conf/cassandra.yaml
  2. Uncomment the initial_token property and set it to 1 or to the value of a generated token for a multi-node cluster.