VctrsDatabase

vctrs / VctrsDatabase

A persistent vector database backed by an HNSW index.

Stores vectors with string IDs and optional JSON metadata. Supports cosine, euclidean (L2), and dot-product distance metrics. Uses memory-mapped I/O for fast loading and a write-ahead log for crash safety.

Example¶

// Create a new database
const db = new VctrsDatabase("./my_db", 384, "cosine");
db.add("doc1", embedding, { title: "Hello" });
const results = db.search(queryVector, 5);
db.save();

// Open an existing database (auto-detects dim and metric)
const db2 = new VctrsDatabase("./my_db");

Constructors¶

Constructor¶

new VctrsDatabase(
   path, 
   dim?, 
   metric?, 
   hnswM?, 
   efConstruction?, 
   quantize?): VctrsDatabase;

Defined in: index.d.ts:104

Open or create a database.

When opening an existing database, dim and metric are auto-detected — pass null or omit them.

Parameters¶

Parameter	Type	Description
`path`	`string`	Directory path for the database files.
`dim?`	`number`	Vector dimensionality (e.g. 384). Required for new databases.
`metric?`	`string`	Distance metric: "cosine" (default), "euclidean"/"l2", or "dot"/"dot_product".
`hnswM?`	`number`	Max edges per HNSW node (default 16). Higher improves recall at the cost of memory.
`efConstruction?`	`number`	Build-time search width (default 200). Higher improves index quality at the cost of build time.
`quantize?`	`boolean`	Enable SQ8 scalar quantization for faster search.

Returns¶

VctrsDatabase

Throws¶

If opening an existing database without dim and it doesn't exist, or if metric is invalid.

Accessors¶

deletedCount¶

Get Signature¶

get deletedCount(): number;

Defined in: index.d.ts:300

Number of deleted slots not yet reclaimed by compact().

Returns¶

number

dim¶

Get Signature¶

get dim(): number;

Defined in: index.d.ts:309

The vector dimensionality of this database.

Returns¶

number

length¶

Get Signature¶

get length(): number;

Defined in: index.d.ts:306

Number of active vectors in the database.

Returns¶

number

metric¶

Get Signature¶

get metric(): string;

Defined in: index.d.ts:312

The distance metric: "cosine", "euclidean", or "dot_product".

Returns¶

string

quantizedSearch¶

Get Signature¶

get quantizedSearch(): boolean;

Defined in: index.d.ts:297

Whether quantized search is currently enabled.

Returns¶

boolean

totalSlots¶

Get Signature¶

get totalSlots(): number;

Defined in: index.d.ts:303

Total allocated slots (active + deleted).

Returns¶

number

Methods¶

add()¶

add(
   id, 
   vector, 
   metadata?): void;

Defined in: index.d.ts:123

Add a vector with a unique string ID.

Parameters¶

Parameter	Type	Description
`id`	`string`	Unique identifier. Throws if the ID already exists (use `upsert()` to insert-or-update).
`vector`	`number`[]	The embedding vector. Must match the database's dimensionality.
`metadata?`	`Record`\<`string`, `any`>	Optional JSON-serializable metadata object.

Returns¶

void

Throws¶

If the ID already exists or dimension doesn't match.

addAsync()¶

addAsync(
   id, 
   vector, 
metadata?): Promise<void>;

Defined in: index.d.ts:317

Async version of add().

Parameters¶

Parameter	Type
`id`	`string`
`vector`	`number`[]
`metadata?`	`Record`\<`string`, `any`>

Returns¶

Promise\<void>

addMany()¶

addMany(
   ids, 
   vectors, 
   metadatas?): void;

Defined in: index.d.ts:142

Batch insert multiple vectors.

Parameters¶

Parameter	Type	Description
`ids`	`string`[]	Array of unique identifiers.
`vectors`	`number`[][]	Array of embedding vectors.
`metadatas?`	`Record`\<`string`, `any`>[]	Optional array of metadata objects.

Returns¶

void

Throws¶

If any ID already exists, lengths mismatch, or dimensions don't match.

addManyAsync()¶

addManyAsync(
   ids, 
   vectors, 
metadatas?): Promise<void>;

Defined in: index.d.ts:323

Async version of addMany().

Parameters¶

Parameter	Type
`ids`	`string`[]
`vectors`	`number`[][]
`metadatas?`	`Record`\<`string`, `any`>[]

Returns¶

Promise\<void>

close()¶

close(): void;

Defined in: index.d.ts:271

Close the database and save to disk. Alias for save().

Returns¶

void

Throws¶

On I/O errors.

compact()¶

compact(): void;

Defined in: index.d.ts:282

Rebuild the index with only live vectors, reclaiming deleted slots. Call after many deletions to reduce memory and disk usage.

Returns¶

void

Throws¶

On internal errors.

contains()¶

contains(id): boolean;

Defined in: index.d.ts:251

Check if a vector ID exists in the database.

Parameters¶

Parameter	Type
`id`	`string`

Returns¶

boolean

count()¶

count(whereFilter?): number;

Defined in: index.d.ts:216

Count vectors matching a filter, or all vectors if no filter.

Uses the inverted metadata index for fast counting with equality and $in filters.

Parameters¶

Parameter	Type
`whereFilter?`	`WhereFilter`

Returns¶

number

delete()¶

delete(id): boolean;

Defined in: index.d.ts:234

Delete a vector by ID.

The slot is marked as deleted but not reclaimed until compact() is called.

Parameters¶

Parameter	Type
`id`	`string`

Returns¶

boolean

true if found and deleted, false if not found.

Throws¶

On internal errors (e.g. WAL write failure).

deleteAsync()¶

deleteAsync(id): Promise<boolean>;

Defined in: index.d.ts:358

Async version of delete().

Parameters¶

Parameter	Type
`id`	`string`

Returns¶

Promise\<boolean>

disableQuantizedSearch()¶

disableQuantizedSearch(): void;

Defined in: index.d.ts:294

Disable quantized search and use full-precision vectors.

Returns¶

void

enableQuantizedSearch()¶

enableQuantizedSearch(): void;

Defined in: index.d.ts:291

Enable SQ8 quantized search for faster HNSW traversal.

Quantized vectors use 4x less memory for distance comparisons during graph traversal, with full-precision re-ranking of final candidates.

Returns¶

void

get()¶

get(id): GetResult;

Defined in: index.d.ts:223

Retrieve a vector and its metadata by ID.

Parameters¶

Parameter	Type
`id`	`string`

Returns¶

GetResult

Throws¶

If the ID is not found.

ids()¶

ids(): string\[\];

Defined in: index.d.ts:254

Return an array of all vector IDs in the database.

Returns¶

string[]

save()¶

save(): void;

Defined in: index.d.ts:264

Persist the database to disk.

Writes the HNSW graph, metadata, and vectors, then truncates the write-ahead log.

Returns¶

void

Throws¶

On I/O errors (e.g. disk full, permission denied).

saveAsync()¶

saveAsync(): Promise<void>;

Defined in: index.d.ts:355

Async version of save().

Returns¶

Promise\<void>

search()¶

search(
   vector, 
   k?, 
   efSearch?, 
   whereFilter?, 
   maxDistance?): SearchResult\[\];

Defined in: index.d.ts:186

Find the k nearest neighbors to a query vector.

Parameters¶

Parameter	Type	Description
`vector`	`number`[]	The query embedding.
`k?`	`number`	Number of results to return (default 10).
`efSearch?`	`number`	HNSW search-time width. Higher improves recall.
`whereFilter?`	`WhereFilter`	Optional metadata filter. See WhereFilter.
`maxDistance?`	`number`	Optional distance threshold — discard results beyond this distance.

Returns¶

SearchResult[]

Array of SearchResult objects sorted by distance (ascending).

Throws¶

If the vector dimension doesn't match.

Example¶

// Basic search
const results = db.search(queryVec, 5);

// With metadata filter
const results = db.search(queryVec, 10, null, { category: "science" });

// With distance threshold
const results = db.search(queryVec, 10, null, null, 0.5);

searchAsync()¶

searchAsync(
   vector, 
   k?, 
   efSearch?, 
   whereFilter?, 
maxDistance?): Promise<SearchResult\[\]>;

Defined in: index.d.ts:337

Async version of search().

Parameters¶

Parameter	Type
`vector`	`number`[]
`k?`	`number`
`efSearch?`	`number`
`whereFilter?`	`WhereFilter`
`maxDistance?`	`number`

Returns¶

Promise\<SearchResult[]>

searchMany()¶

searchMany(
   vectors, 
   k?, 
   efSearch?, 
   whereFilter?, 
   maxDistance?): SearchResult\[\]\[\];

Defined in: index.d.ts:202

Search multiple queries in parallel.

Significantly faster than calling search() in a loop.

Parameters¶

Parameter	Type
`vectors`	`number`[][]
`k?`	`number`
`efSearch?`	`number`
`whereFilter?`	`WhereFilter`
`maxDistance?`	`number`

Returns¶

SearchResult[][]

Array of result arrays, one per query.

Throws¶

If any vector dimension doesn't match.

searchManyAsync()¶

searchManyAsync(
   vectors, 
   k?, 
   efSearch?, 
   whereFilter?, 
maxDistance?): Promise<SearchResult\[\]\[\]>;

Defined in: index.d.ts:346

Async version of searchMany().

Parameters¶

Parameter	Type
`vectors`	`number`[][]
`k?`	`number`
`efSearch?`	`number`
`whereFilter?`	`WhereFilter`
`maxDistance?`	`number`

Returns¶

Promise\<SearchResult[][]>

stats()¶

stats(): VctrsStats;

Defined in: index.d.ts:274

Get graph-level statistics for diagnostics.

Returns¶

VctrsStats

update()¶

update(
   id, 
   vector?, 
   metadata?): void;

Defined in: index.d.ts:244

Update a vector's embedding and/or metadata in-place.

Parameters¶

Parameter	Type	Description
`id`	`string`	The vector's unique identifier.
`vector?`	`number`[]	New embedding (or null to keep existing).
`metadata?`	`Record`\<`string`, `any`>	New metadata (or null to keep existing).

Returns¶

void

Throws¶

If the ID is not found or the vector dimension doesn't match.

upsert()¶

upsert(
   id, 
   vector, 
   metadata?): void;

Defined in: index.d.ts:132

Insert a vector, or update it if the ID already exists.

Same as add() but overwrites existing entries instead of throwing.

Parameters¶

Parameter	Type
`id`	`string`
`vector`	`number`[]
`metadata?`	`Record`\<`string`, `any`>

Returns¶

void

Throws¶

If the vector dimension doesn't match.

upsertAsync()¶

upsertAsync(
   id, 
   vector, 
metadata?): Promise<void>;

Defined in: index.d.ts:320

Async version of upsert().

Parameters¶

Parameter	Type
`id`	`string`
`vector`	`number`[]
`metadata?`	`Record`\<`string`, `any`>

Returns¶

Promise\<void>

upsertMany()¶

upsertMany(
   ids, 
   vectors, 
   metadatas?): void;

Defined in: index.d.ts:156

Batch upsert — inserts new vectors, updates existing ones.

More efficient than calling upsert() in a loop because new vectors are batch-inserted together.

Parameters¶

Parameter	Type
`ids`	`string`[]
`vectors`	`number`[][]
`metadatas?`	`Record`\<`string`, `any`>[]

Returns¶

void

Throws¶

If lengths mismatch or dimensions don't match.

upsertManyAsync()¶

upsertManyAsync(
   ids, 
   vectors, 
metadatas?): Promise<void>;

Defined in: index.d.ts:330

Async version of upsertMany().

Parameters¶

Parameter	Type
`ids`	`string`[]
`vectors`	`number`[][]
`metadatas?`	`Record`\<`string`, `any`>[]

Returns¶

Promise\<void>