Implementation:Risingwavelabs Risingwave VnodeHelper

Metadata

Property	Value
File	java/common-utils/src/main/java/com/risingwave/java/utils/VnodeHelper.java
Language	Java
Module	common-utils
Package	com.risingwave.java.utils
Classes	VnodeHelper
Lines	45

Overview

VnodeHelper is a utility class that provides a static method for evenly distributing virtual node (vnode) indices across a specified number of groups. It partitions a range of vnode IDs (from 0 to vnodeCount - 1) into groupCount groups as evenly as possible, with any remainder vnodes distributed one per group to the first groups. A caller-provided groupBuilder function transforms each group's list of vnode IDs into a result object.

This is used in RisingWave's partitioned data processing to assign vnodes to different connector splits or workers.

Code Reference

Source Location

java/common-utils/src/main/java/com/risingwave/java/utils/VnodeHelper.java

Signature

public class VnodeHelper {
    public static <R> List<R> splitGroup(
            int groupCount, int vnodeCount, Function<List<Integer>, R> groupBuilder)
}

Imports

import java.util.ArrayList;
import java.util.List;
import java.util.function.Function;

I/O Contract

splitGroup

Parameter	Type	Description
groupCount	int	The number of groups to split the vnodes into
vnodeCount	int	The total number of virtual nodes to distribute
groupBuilder	Function<List<Integer>, R>	A function that transforms a list of vnode IDs into a result object of type R

Direction	Type	Description
Output	List<R>	A list of groupCount result objects, each built from its assigned vnode IDs

Distribution Algorithm:

• Each group receives vnodeCount / groupCount vnodes as a base allocation
• The remaining vnodeCount % groupCount vnodes are distributed one per group to the first groups
• Vnode IDs are assigned sequentially starting from 0

For example, with vnodeCount=10 and groupCount=3: group 0 gets vnodes [0,1,2,3], group 1 gets [4,5,6,7], group 2 gets [8,9].

Usage Examples

// Split 256 vnodes across 4 worker groups
List<List<Integer>> groups = VnodeHelper.splitGroup(
    4,    // groupCount
    256,  // vnodeCount
    vnodeIds -> vnodeIds  // identity function returns the list directly
);
// groups.get(0) contains [0..63], groups.get(1) contains [64..127], etc.

// Use a builder function to create custom split objects
List<MySplit> splits = VnodeHelper.splitGroup(
    3,
    256,
    vnodeIds -> new MySplit(vnodeIds)
);

Related Pages

• MetaClient - Another utility in the common-utils module for meta service communication
• SourceHandler Interface - Source handlers that may use vnode assignments for partitioned CDC