Skip to content
xa-xPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

Vectra DB

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

Installation

npm install vectra-db
# or
pnpm add vectra-db
# or
yarn add vectra-db

Quick Start

import { 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)
// }

Storage Backends

Memory (default)

Fast but ephemeral - data lost on process exit.

const db = new Vectra({
  dimension: 128,
  storage: 'memory',
});

IndexedDB (Browser)

Persistent storage for browser environments.

const db = new Vectra({
  dimension: 128,
  storage: 'indexeddb',
  dbName: 'my-vectors',
});

// Must call init() for IndexedDB
await db.init();

SQLite (Node.js)

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
});

File (Universal)

JSON file storage - works everywhere.

const db = new Vectra({
  dimension: 128,
  storage: 'file',
  filePath: './data/vectors.json',
});

API Reference

Constructor

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
  },
})

Methods

insert(id, vector, metadata?, options?)

Insert a vector.

await db.insert('doc-1', [0.1, 0.2, ...], { title: 'Doc' });
await db.insert('doc-1', vector, metadata, { overwrite: true });

insertBatch(items, options?)

Insert multiple vectors.

await db.insertBatch([
  { id: 'a', vector: v1, metadata: { type: 'a' } },
  { id: 'b', vector: v2, metadata: { type: 'b' } },
]);

query(vector, options?)

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
});

Filter Operators

// 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(id)

Get a vector by ID.

const record = await db.get('doc-1');

update(id, updates)

Update a vector.

await db.update('doc-1', { 
  vector: newVector,
  metadata: { updated: true } 
});

delete(id) / deleteBatch(ids)

Delete vectors.

await db.delete('doc-1');
await db.deleteBatch(['a', 'b', 'c']);

getIds()

Get all IDs.

const ids = await db.getIds();

count()

Get count of vectors.

const count = await db.count();

clear()

Remove all vectors.

await db.clear();

stats()

Get database statistics.

const stats = await db.stats();
// { count: 100, dimension: 128, metric: 'cosine', storageType: 'memory', dbName: 'vectra' }

export() / import(data)

Export/import database in portable format.

const data = await db.export();
await db.import(data);

close()

Close the database.

await db.close();

Usage Examples

With OpenAI Embeddings

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 });
}

React / Next.js

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();
}, []);

Cloudflare Workers

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));
  },
};

HNSW Algorithm

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

Tuning HNSW

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

Performance

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

Comparison

Feature Vectra Pinecone Chroma LanceDB
Runs in Browser ✅ ❌ ❌ ✅
Zero Dependencies ✅ ❌ ❌ ❌
Self-hosted ✅ ❌ ✅ ✅
Bundle Size ~30KB API ~2MB ~10MB
HNSW Index ✅ ✅ ✅ ✅
Metadata Filter ✅ ✅ ✅ ✅

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines first.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages