Apache Cassandra™ 2.0

The cassandra-shuffle utility

Shift a single-token-per-node architecture to virtual nodes (vnodes) without downtime.

The cassandra-shuffle utility splits up all the contiguous partition ranges (formerly token ranges) for each node and then randomly distributes them into virtual nodes throughout the cluster. Shuffling is a two-phase operation. The utility first schedules the range transfers and then begins transferring the scheduled ranges. You can shuffle on a per-data center basis and mix virtual node-enabled and non-virtual node data centers.

Warning: The procedure described below is no longer advised. Using the shuffle utility on a running production system may result in performance degradation and potential downtime.

Bootstrapping a new data center is a much safer way to enable vnodes. Use the procedure described in Enabling virtual nodes on an existing production cluster instead.


In a terminal window:

  1. In the cassandra.yaml file, set the num_tokens parameter.

    A good starting point for this parameter is 256.

  2. Restart the node.

    The node sleeps for RING_DELAY to make sure its view of the ring is accurate, and then splits its current range into the number of specified tokens. However, while the range is split into many tokens, the range remains contiguous; it is still equivalent to what it was before, but with more tokens.

  3. To distribute the tokens, initialize the shuffle operation:
    shuffle create
  4. Starts the transfers:
    shuffle enable
  5. To see what transfers remain at any point:
    shuffle ls