VectoriaDB

2.2.0 · active · verified Wed Apr 22

VectoriaDB is a lightweight, production-ready, in-memory vector database designed for efficient semantic search in JavaScript and TypeScript environments. It is currently at stable version 2.2.0, with frequent minor releases in the 2.x line addressing performance, security, and new features like geospatial support. The library differentiates itself by providing a complete, privacy-first solution for vector search within a single Node.js process, leveraging `transformers.js` to generate embeddings locally using a default `Xenova/all-MiniLM-L6-v2` model. It features optimized HNSW indexing for sub-millisecond search on 100k+ documents, robust TypeScript support, and minimal dependencies, making it ideal for embedded search in applications, CLIs, or desktop environments where external vector database services are undesirable or unnecessary. Unlike distributed vector databases, VectoriaDB focuses on performance and simplicity for in-memory, single-node deployments.

Common errors

```
Error: Cannot find module 'vectoriadb'
```
cause CommonJS environment attempting to import an ES module-first package, or incorrect module resolution setup.

fix Ensure your project is configured for ES modules (e.g., add `"type": "module"` to `package.json`) or use dynamic `import()` for CommonJS contexts.
```
TypeError: VectoriaDB is not a constructor
```
cause Attempting to instantiate `VectoriaDB` incorrectly, often due to a default import when a named import is required, or CJS `require()` syntax in an ESM context.

fix Use the named import syntax: `import { VectoriaDB } from 'vectoriadb';`
```
ONNX runtime warnings regarding 'dtype'
```
cause Older versions of VectoriaDB (prior to v2.2.0) implicitly handling `dtype` for ONNX runtime, leading to warning messages.

fix Upgrade to VectoriaDB v2.2.0 or newer, which explicitly sets `dtype` to 'fp32' in `EmbeddingService` to suppress these warnings.
```
Error: Node.js version X.X.X is not supported. Please upgrade to Node.js 18 or higher.
```
cause Running VectoriaDB on an unsupported Node.js version, which is a dependency requirement for `transformers.js`.

fix Upgrade your Node.js environment to version 18 or newer.

Warnings

gotcha VectoriaDB requires Node.js version 18 or higher and TypeScript 5.0+ (if using TypeScript). Running with older versions may lead to compatibility issues or errors, particularly due to `transformers.js` dependencies.
Fix: Ensure your development and production environments use Node.js 18+ and TypeScript 5.0+.
breaking Versions prior to 2.2.0 might not properly release native ONNX resources, potentially leading to resource leaks or native mutex crashes during application shutdown, especially if `EmbeddingService` was used directly.
Fix: Upgrade to VectoriaDB v2.2.0 or newer. Ensure `db.close()` is called on your `VectoriaDB` instance to trigger proper resource disposal via the new `dispose` method in `EmbeddingService`.
security Version 2.1.3 included a patch for a vulnerability in the authentication mechanism. Older versions might be susceptible to security risks if authentication features were used.
Fix: Upgrade to VectoriaDB v2.1.3 or newer to benefit from the patched authentication vulnerability.
gotcha VectoriaDB is designed for in-memory use cases and embedded search. It is not suitable for persistent storage (without external adapters), distributed architectures, or multi-million document scales requiring specialized distributed vector databases.
Fix: Evaluate your use case carefully. For distributed, persistent, or extremely large-scale vector search, consider alternatives like Pinecone, Weaviate, or Milvus.

Install

npm install vectoriadb npm
yarn add vectoriadb yarn
pnpm add vectoriadb pnpm

Imports

VectoriaDB
wrong:
```
const VectoriaDB = require('vectoriadb')
```
correct:
```
import { VectoriaDB } from 'vectoriadb'
```
VectoriaDB is ESM-first and primarily used with ES module imports. Avoid CommonJS `require()` unless using dynamic imports.
SearchOptions
wrong:
```
import { SearchOptions } from 'vectoriadb'
```
correct:
```
import type { SearchOptions } from 'vectoriadb'
```
Type import for specifying parameters when performing searches. Use `import type` for type-only imports to prevent bundling issues.
Document
```
import type { Document } from 'vectoriadb'
```
Type definition for the structure of documents stored in VectoriaDB, typically used with generics for metadata.

Quickstart

This quickstart demonstrates how to initialize VectoriaDB, add new text documents with associated metadata, and perform a semantic search query.

import { VectoriaDB } from 'vectoriadb';

// Create and initialize the database
const db = new VectoriaDB();
await db.initialize();

// Add documents
await db.add('doc-1', 'How to create a user account', {
  id: 'doc-1',
  category: 'auth',
  author: 'Alice'
});

await db.add('doc-2', 'Send email notifications to users', {
  id: 'doc-2',
  category: 'notifications',
  author: 'Bob'
});

// Search
const results = await db.search('creating new accounts');
console.log(results[0].metadata); // { id: 'doc-1', category: 'auth', ... }
console.log(results[0].score); // 0.87

view raw JSON →