ruvector/npm/packages/diskann

@ruvector/diskann

DiskANN / Vamana approximate-nearest-neighbor (ANN) search for Node.js — a Rust core compiled to native .node addons via NAPI-RS for Linux x64/arm64, macOS x64/arm64, and Windows x64.

DiskANN is the SSD-friendly graph index from Microsoft Research that powers billion-scale vector search on a single machine. This package implements the Vamana graph construction with α-robust pruning (NeurIPS 2019) plus optional Product Quantization (PQ) and mmap persistence so working set ≪ dataset size.

Why DiskANN

	HNSW (in-memory)	DiskANN (this package)
Scale	<1M vectors, fully resident in RAM	1M – 1B+ vectors, SSD-backed
Memory	full vectors in RAM	only graph + optional PQ codes in RAM
Insert	incremental	batch (build once after inserts)
Search	sub-ms	~55µs (5K · 128d · k=10, M-series)
Best for	real-time routing, small corpora	large-corpus RAG, retrieval, embeddings store

Capabilities

• Vamana graph with two-pass construction (α=1.0 then α=1.2) and α-robust pruning — the published DiskANN algorithm, not a clone of HNSW.
• Optional Product Quantization (M subspaces × 256 centroids, trained with k-means++ / Lloyd's) for compressed in-memory codes + fast distance tables.
• Memory-mapped persistence — save() writes a flat slab + graph + (optional) PQ codes; load() mmaps so the OS pages in only touched vectors.
• Async builds and searches that off-load to a blocking thread pool so the Node event loop stays responsive.
• Batch insert API for high-throughput ingestion of millions of vectors.
• Delete support (tombstoned then re-pruned at build).
• Cache-friendly internals — contiguous FlatVectors, generation-counter VisitedSet (O(1) per-query reset), flat PQ distance tables, 4-accumulator ILP for L2.
• Optional SimSIMD acceleration (NEON / AVX2 / AVX-512) in the Rust crate; Node bindings ship with the portable build.
• TypeScript types included.
• Cross-platform prebuilds for linux-x64-gnu, linux-arm64-gnu, darwin-x64, darwin-arm64, win32-x64-msvc — no toolchain or node-gyp required at install time.

Install

npm install @ruvector/diskann
# or
pnpm add @ruvector/diskann
# or
yarn add @ruvector/diskann

Requires Node ≥ 18. The matching platform binary (@ruvector/diskann-<platform>) is pulled in automatically as an optional dependency — there is no install-time compilation.

Quick Start

const { DiskAnn } = require('@ruvector/diskann');

// 1. Create the index
const index = new DiskAnn({ dim: 128 });

// 2. Insert vectors (string id + Float32Array)
for (let i = 0; i < 10_000; i++) {
  const vec = new Float32Array(128);
  for (let d = 0; d < 128; d++) vec[d] = Math.random();
  index.insert(`vec-${i}`, vec);
}

// 3. Build the Vamana graph (one-time, required before search)
await index.buildAsync();

// 4. Search
const query = new Float32Array(128).fill(0.5);
const results = await index.searchAsync(query, 10);
//   [ { id: 'vec-42', distance: 0.123 }, ... ]

// 5. Persist + reload
index.save('./my-index');
const loaded = DiskAnn.load('./my-index');

With Product Quantization

Trade a small recall hit for far smaller in-memory footprint and faster candidate scoring on millions of vectors:

const index = new DiskAnn({
  dim: 768,
  pqSubspaces: 96,     // 96 bytes per vector instead of 768 × 4 = 3072 B
  pqIterations: 12,
  maxDegree: 64,
  buildBeam: 128,
  searchBeam: 96,
  alpha: 1.2,
});

TypeScript

import { DiskAnn, DiskAnnOptions, DiskAnnSearchResult } from '@ruvector/diskann';

const opts: DiskAnnOptions = { dim: 384, searchBeam: 96 };
const index = new DiskAnn(opts);

const hits: DiskAnnSearchResult[] = index.search(query, 10);

API

new DiskAnn(options)

Option	Type	Default	Meaning
dim	number	— (required)	Vector dimensionality
maxDegree	number	64	Vamana graph out-degree R
buildBeam	number	128	Beam width during construction (L_build)
searchBeam	number	64	Beam width at query time (L_search)
alpha	number	1.2	α-robust pruning factor (≥ 1.0)
pqSubspaces	number	0	PQ subspaces M (0 disables PQ)
pqIterations	number	10	k-means iterations for PQ training
storagePath	string	—	Optional path used by the mmap layer

Methods

Method	Description
insert(id: string, vector: Float32Array): void	Insert a single vector
insertBatch(ids: string[], vectors: Float32Array, dim: number): void	Insert N vectors packed as a flat Float32Array of length N · dim
build(): void	Build the Vamana graph (and train PQ if enabled)
buildAsync(): Promise<void>	Same, off-loaded to a blocking thread pool
search(query: Float32Array, k: number): DiskAnnSearchResult[]	k-NN search
searchAsync(query, k): Promise<DiskAnnSearchResult[]>	Async k-NN search
delete(id: string): boolean	Tombstone a vector (effective after next build)
count(): number	Number of vectors currently in the index
save(dir: string): void	Persist index files into dir
static load(dir: string): DiskAnn	Load and mmap an index from dir

Search results are { id: string, distance: number }, where distance is squared-L2.

Benchmarks

Reference measurements on an Apple-silicon M-series laptop, release build, single-thread search. PQ is off unless noted.

Dataset	Dim	Vectors	Build	Search (k=10)	Recall@10
Synthetic	64	2,000	~1.4 s	~22 µs	1.000
Synthetic	128	5,000	~6.2 s	~55 µs	0.998
Synthetic, 50 queries	64	2,000	—	—	0.998 avg

Validated by the in-tree Rust test suite (17 tests across distance, PQ, Vamana, and end-to-end index) plus the Node integration test that ships with the package (npm test).

When NOT to use this

• You have fewer than ~10K vectors and don't need persistence → a brute-force scan is faster and simpler.
• You need real-time incremental inserts with immediate searchability → use HNSW (see @ruvector/router). DiskANN requires a build pass.
• You're operating in a browser → this is a native Node addon; use the WASM-based packages in the ruvector family instead.

Algorithm notes (one paragraph)

Insertion appends vectors to a contiguous FlatVectors buffer. build() computes the medoid (point nearest the centroid, parallel via rayon), initializes a bounded-degree random graph, then runs two passes of greedy-search-from-medoid → α-robust-prune → bidirectional-edge-update: pass 1 with α=1.0 (accuracy), pass 2 with α=1.2 (navigability). If pqSubspaces > 0, a Product Quantizer is trained with k-means++ initialization and Lloyd's iterations; per-query, a distance table is precomputed so PQ distance is a sum of M table lookups. Search is greedy beam-search from the medoid with a top-L candidate pool; with PQ enabled, top results are re-ranked with exact L2.

For the full design — including persistence layout, optimization rationale, and trade-off analysis — see ADR-146: DiskANN/Vamana Implementation.

Related packages

• @ruvector/router — in-memory HNSW router (sub-millisecond, small/medium corpora)
• ruvector — umbrella package; lazily wraps DiskANN when this addon is installed
• Rust crate: ruvector-diskann

Links

• Repository: https://github.com/ruvnet/ruvector
• Issues: https://github.com/ruvnet/ruvector/issues
• DiskANN paper (NeurIPS 2019): https://proceedings.neurips.cc/paper/2019/hash/09853c7fb1d3f8ee67a61b6bf4a7f8e6-Abstract.html

License

MIT