@ruvector/core

@ruvector/core

High-performance vector database core with HNSW indexing delivering 50k+ inserts/sec, built in Rust with Node.js NAPI bindings for AI/ML similarity search workloads.

Quick Command Reference

Installation

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

Core API

VectorDB Constructor

import { VectorDB } from '@ruvector/core';

const db = new VectorDB({
  dimensions: 384,           // Required: vector dimensionality
  metric: 'cosine',          // 'cosine' | 'euclidean' | 'dot'
  efConstruction: 200,       // HNSW build quality
  m: 16,                     // HNSW max connections per layer
  persistPath: './data',     // Optional: persistence directory
});

Constructor Options:

Insert Methods

// Single insert
await db.insert(id: string, vector: Float32Array | number[], metadata?: Record<string, any>);

// Batch insert (50k+ inserts/sec)
await db.batchInsert(items: Array<{ id: string; vector: number[]; metadata?: object }>);

// Upsert (insert or update)
await db.upsert(id: string, vector: number[], metadata?: object);

Parameters:

Search Methods

// Basic search
const results = await db.search(queryVector: number[], options?: SearchOptions);

// Search with filter
const results = await db.search(queryVector, {
  topK: 10,
  efSearch: 100,
  filter: { category: 'science' },
  includeMetadata: true,
  includeVectors: false,
  threshold: 0.7,
});

SearchOptions:

Returns: SearchResult[]

interface SearchResult {
  id: string;
  score: number;         // Similarity score
  metadata?: object;     // If includeMetadata
  vector?: number[];     // If includeVectors
}

Index Management

// Build HNSW index
await db.buildIndex({ efConstruction: 200, m: 16 });

// Optimize for recall target
await db.optimizeIndex({ targetRecall: 0.99 });

// Get index info
const info = await db.indexInfo();
// { built: true, elements: 50000, efConstruction: 200, m: 16 }

Persistence

// Save to disk
await db.save('./data');

// Load from disk
const db = await VectorDB.load('./data');

// Auto-persist on changes
const db = new VectorDB({ dimensions: 384, persistPath: './data' });

Delete and Update

// Delete single vector
await db.delete(id: string);

// Delete multiple vectors
await db.deleteMany(ids: string[]);

// Update metadata only
await db.updateMetadata(id: string, metadata: object);

Statistics

const stats = await db.stats();
// { count: 50000, dimensions: 384, metric: 'cosine', indexBuilt: true, memoryUsageMB: 128 }

Common Patterns

RAG Pipeline Integration

import { VectorDB } from '@ruvector/core';
import { embed } from './embeddings';

const db = new VectorDB({ dimensions: 384 });
// Index documents
for (const doc of documents) {
  const vector = await embed(doc.text);
  await db.insert(doc.id, vector, { text: doc.text, source: doc.source });
}
await db.buildIndex();
// Query
const queryVec = await embed("What is HNSW?");
const results = await db.search(queryVec, { topK: 5 });

Streaming Batch Insert

const items = largeDataset.map(d => ({
  id: d.id,
  vector: d.embedding,
  metadata: { label: d.label }
}));
await db.batchInsert(items); // 50k+/sec with Rust NAPI

Filtered Similarity Search

const results = await db.search(queryVector, {
  topK: 10,
  filter: { category: 'science', year: { $gte: 2023 } },
  threshold: 0.8,
});

Key Options

RAN DDD Context

Bounded Context: Data Infrastructure

References

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