@ruvector/node

@ruvector/node

High-performance Rust vector database for Node.js with native NAPI bindings, SIMD-optimized distance calculations, and zero-copy memory operations for maximum throughput.

Quick Command Reference

Installation

Hub install (recommended): npx ruvector@latest includes this package. Standalone: npx @ruvector/node@latest See Installation Guide for the full ecosystem.

Core API

RuVector Constructor

import { RuVector } from '@ruvector/node';

const rv = new RuVector({
  dimensions: 384,
  metric: 'cosine',       // 'cosine' | 'euclidean' | 'dot'
  efConstruction: 200,    // HNSW build quality
  m: 16,                  // HNSW max connections
  useSIMD: true,          // Enable SIMD acceleration
});

Constructor Options:

Insert Operations

// Single insert
await rv.insert('vec-1', new Float32Array([0.1, 0.2, ...]), { label: 'test' });

// Batch insert with zero-copy (highest throughput)
await rv.batchInsert([
  { id: 'v1', vector: new Float32Array([...]), metadata: { tag: 'a' } },
  { id: 'v2', vector: new Float32Array([...]), metadata: { tag: 'b' } },
]);

// Upsert
await rv.upsert('vec-1', new Float32Array([0.3, 0.4, ...]), { label: 'updated' });

Search Operations

// Basic SIMD-accelerated search
const results = await rv.search(queryVector, { topK: 10 });

// Advanced search with filters
const results = await rv.search(queryVector, {
  topK: 5,
  efSearch: 200,
  filter: { category: 'ai' },
  threshold: 0.8,
  includeMetadata: true,
});

SearchOptions:

Distance Computation (SIMD)

// Direct SIMD-accelerated distance computation
const distance = rv.distance(vectorA, vectorB);            // Uses configured metric
const cosine = rv.cosineDistance(vectorA, vectorB);         // Cosine distance
const euclidean = rv.euclideanDistance(vectorA, vectorB);   // L2 distance
const dot = rv.dotProduct(vectorA, vectorB);               // Dot product

Persistence

await rv.save('./my-database');                          // Save
const rv = await RuVector.load('./my-database');         // Load

Common Patterns

High-Throughput Ingestion Pipeline

import { RuVector } from '@ruvector/node';

const rv = new RuVector({ dimensions: 384, useSIMD: true });
const chunks = splitIntoChunks(largeDataset, 10000);
for (const chunk of chunks) {
  await rv.batchInsert(chunk); // 50k+ vectors/sec
}
await rv.buildIndex({ efConstruction: 200 });

Real-Time Similarity with SIMD

const results = await rv.search(queryVector, {
  topK: 10,
  efSearch: 100, // Balance speed vs accuracy
});
// Sub-millisecond latency with SIMD acceleration

Memory-Mapped Persistence

const rv = new RuVector({
  dimensions: 768,
  persistPath: './vectors-db',
  maxElements: 1_000_000,
});
// Data automatically memory-mapped for efficient large-scale operations

Key Options

RAN DDD Context

Bounded Context: Data Infrastructure

References

• API reference: See references/commands.md
• Full README
• npm