Ruvector Cluster

@ruvector/cluster

Distributed clustering layer for RuVector that provides automatic sharding, Raft consensus-based leader election, node discovery, and transparent rebalancing across a fleet of vector database nodes.

Quick Reference

Installation

npx @ruvector/cluster@latest

Quick Start

import { ClusterManager, ClusterConfig } from '@ruvector/cluster';

const config: ClusterConfig = {
  nodeId: 'node-1',
  listenPort: 9100,
  seedNodes: ['localhost:9101', 'localhost:9102'],
  shardCount: 8,
  replicationFactor: 2,
  consensus: 'raft',
};

const cluster = new ClusterManager(config);
await cluster.start();

// Insert vectors - automatically routed to correct shard
await cluster.insert([
  { id: 'vec-1', vector: new Float32Array([0.1, 0.2, 0.3]), metadata: { label: 'a' } },
  { id: 'vec-2', vector: new Float32Array([0.4, 0.5, 0.6]), metadata: { label: 'b' } },
]);

// Search across all shards with automatic scatter-gather
const results = await cluster.search(new Float32Array([0.1, 0.2, 0.3]), 10);
console.log(results); // Top-10 nearest neighbors from all shards

// Check cluster health
const status = await cluster.status();
console.log(status.activeNodes, status.shardDistribution);

Core API

ClusterManager

Main entry point for distributed vector operations.

const cluster = new ClusterManager(config: ClusterConfig);

ClusterConfig:

cluster.start()

Initialize the node and join the cluster.

await cluster.start(): Promise<void>

cluster.addNode(nodeConfig)

Dynamically add a node to the cluster.

await cluster.addNode({
  nodeId: 'node-3',
  address: 'host3:9100',
  weight: 1.0,  // Relative capacity weight
}): Promise<void>

cluster.removeNode(nodeId)

Remove a node and trigger rebalancing.

await cluster.removeNode('node-3'): Promise<void>

cluster.insert(vectors)

Insert vectors with automatic shard routing based on consistent hashing.

await cluster.insert(vectors: VectorRecord[]): Promise<InsertResult>

VectorRecord:

cluster.search(query, k, options?)

Scatter-gather search across all shards.

const results = await cluster.search(
  query: Float32Array,
  k: number,
  options?: SearchOptions
): Promise<SearchResult[]>

SearchOptions:

cluster.rebalance()

Manually trigger shard rebalancing across nodes.

await cluster.rebalance(): Promise<RebalanceResult>

cluster.status()

Get cluster health and shard distribution.

const status = await cluster.status(): Promise<ClusterStatus>
// { activeNodes: 3, totalShards: 8, leader: 'node-1', shardDistribution: {...} }

Common Patterns

Multi-Region Cluster

const cluster = new ClusterManager({
  nodeId: 'us-east-1',
  seedNodes: ['eu-west-1:9100', 'ap-south-1:9100'],
  shardCount: 16,
  replicationFactor: 3,
  consensus: 'raft',
});

Filtered Distributed Search

const results = await cluster.search(queryVec, 20, {
  filter: { field: 'category', op: 'eq', value: 'electronics' },
  consistency: 'quorum',
});

Monitoring with Events

cluster.on('node:joined', (nodeId) => console.log(`Node ${nodeId} joined`));
cluster.on('node:left', (nodeId) => console.log(`Node ${nodeId} left`));
cluster.on('shard:rebalanced', (info) => console.log('Rebalance complete', info));
cluster.on('leader:elected', (leaderId) => console.log(`New leader: ${leaderId}`));

References

• API Reference
• npm