A cross-platform vector database that runs everywhere - Node.js, Browser, Edge runtimes, Deno, Bun.
- 🔥 Zero dependencies (core)
- ⚡ HNSW algorithm for fast ANN search
- 📦 ~30KB gzipped
- 💾 Multiple storage backends (Memory, IndexedDB, SQLite, File)
- 🔍 Metadata filtering
- 📤 Portable export/import
npm install vectra-db
# or
pnpm add vectra-db
# or
yarn add vectra-dbimport { Vectra } from 'vectra-db';
// Create a vector database
const db = new Vectra({
dimension: 1536, // OpenAI embeddings dimension
metric: 'cosine', // 'cosine' | 'euclidean' | 'dot'
});
// Insert vectors
await db.insert('doc-1', embedding1, { title: 'Hello World', tags: ['ai'] });
await db.insert('doc-2', embedding2, { title: 'Vector Search', tags: ['search'] });
// Search for similar vectors
const results = await db.query(queryEmbedding, { k: 10 });
console.log(results[0]);
// {
// record: { id: 'doc-1', metadata: { title: 'Hello World', tags: ['ai'] } },
// score: 0.023 // Lower = more similar (for cosine)
// }Fast but ephemeral - data lost on process exit.
const db = new Vectra({
dimension: 128,
storage: 'memory',
});Persistent storage for browser environments.
const db = new Vectra({
dimension: 128,
storage: 'indexeddb',
dbName: 'my-vectors',
});
// Must call init() for IndexedDB
await db.init();Persistent storage for Node.js. Falls back to JSON file if better-sqlite3 not installed.
const db = new Vectra({
dimension: 128,
storage: 'sqlite',
dbName: 'vectors', // Creates vectors.db
});JSON file storage - works everywhere.
const db = new Vectra({
dimension: 128,
storage: 'file',
filePath: './data/vectors.json',
});new Vectra({
dimension: number, // Required: vector dimensions
metric?: 'cosine' | 'euclidean' | 'dot', // Default: 'cosine'
storage?: 'memory' | 'indexeddb' | 'sqlite' | 'file', // Default: auto-detect
dbName?: string, // Database name
filePath?: string, // File path for file/sqlite storage
hnsw?: { // HNSW algorithm tuning
maxConnections?: number, // Default: 16
efConstruction?: number, // Default: 200
efSearch?: number, // Default: 50
},
})Insert a vector.
await db.insert('doc-1', [0.1, 0.2, ...], { title: 'Doc' });
await db.insert('doc-1', vector, metadata, { overwrite: true });Insert multiple vectors.
await db.insertBatch([
{ id: 'a', vector: v1, metadata: { type: 'a' } },
{ id: 'b', vector: v2, metadata: { type: 'b' } },
]);Search for similar vectors.
const results = await db.query(queryVector, {
k: 10, // Number of results
filter: { type: 'a' }, // Metadata filter
minScore: 0.8, // Minimum similarity (0-1)
includeVector: false, // Include vector in results
});// Simple equality
filter: { status: 'active' }
// Comparison operators
filter: {
score: { $gt: 0.5 },
count: { $gte: 10, $lte: 100 },
type: { $in: ['a', 'b', 'c'] },
status: { $ne: 'deleted' }
}Get a vector by ID.
const record = await db.get('doc-1');Update a vector.
await db.update('doc-1', {
vector: newVector,
metadata: { updated: true }
});Delete vectors.
await db.delete('doc-1');
await db.deleteBatch(['a', 'b', 'c']);Get all IDs.
const ids = await db.getIds();Get count of vectors.
const count = await db.count();Remove all vectors.
await db.clear();Get database statistics.
const stats = await db.stats();
// { count: 100, dimension: 128, metric: 'cosine', storageType: 'memory', dbName: 'vectra' }Export/import database in portable format.
const data = await db.export();
await db.import(data);Close the database.
await db.close();import { Vectra } from 'vectra-db';
import OpenAI from 'openai';
const openai = new OpenAI();
const db = new Vectra({ dimension: 1536 });
async function addDocument(text: string, id: string) {
const response = await openai.embeddings.create({
model: 'text-embedding-3-small',
input: text,
});
await db.insert(id, response.data[0].embedding, { text });
}
async function search(query: string) {
const response = await openai.embeddings.create({
model: 'text-embedding-3-small',
input: query,
});
return db.query(response.data[0].embedding, { k: 5 });
}import { Vectra } from 'vectra-db';
// Create database with IndexedDB persistence
const db = new Vectra({
dimension: 384,
storage: 'indexeddb',
dbName: 'my-app-vectors',
});
// Initialize on mount
useEffect(() => {
db.init();
}, []);import { Vectra } from 'vectra-db';
export default {
async fetch(request: Request) {
const db = new Vectra({
dimension: 128,
storage: 'memory', // Workers are stateless
});
// ... use database
return new Response(JSON.stringify(results));
},
};Vectra uses the HNSW (Hierarchical Navigable Small World) algorithm for approximate nearest neighbor search. This provides:
- O(log n) search complexity
- High recall (>95% for typical use cases)
- Scalability to millions of vectors
const db = new Vectra({
dimension: 128,
hnsw: {
maxConnections: 24, // More = better recall, more memory
efConstruction: 300, // More = better index quality, slower build
efSearch: 100, // More = better recall, slower search
},
});| Parameter | Default | Trade-off |
|---|---|---|
maxConnections |
16 | Higher = better recall, more memory |
efConstruction |
200 | Higher = better index, slower insert |
efSearch |
50 | Higher = better recall, slower search |
Benchmarks on MacBook Pro M1:
| Operation | Time |
|---|---|
| Insert 1000 vectors (128d) | ~200ms |
| Insert 1000 vectors (1536d) | ~400ms |
| Search (k=10) | ~2-5ms |
| Search with filter | ~3-8ms |
| Feature | Vectra | Pinecone | Chroma | LanceDB |
|---|---|---|---|---|
| Runs in Browser | ✅ | ❌ | ❌ | ✅ |
| Zero Dependencies | ✅ | ❌ | ❌ | ❌ |
| Self-hosted | ✅ | ❌ | ✅ | ✅ |
| Bundle Size | ~30KB | API | ~2MB | ~10MB |
| HNSW Index | ✅ | ✅ | ✅ | ✅ |
| Metadata Filter | ✅ | ✅ | ✅ | ✅ |
MIT
Contributions welcome! Please read the contributing guidelines first.