RvLite Vector Database

0.2.6 verified Thu Apr 23 auth: no javascript

RvLite is a lightweight, embeddable vector database designed for universal execution across Node.js, browsers, and Edge environments. It leverages WebAssembly for high performance and portability, resulting in a small bundle size of approximately 850KB. The current stable version is 0.2.6. It supports multiple querying paradigms, including vector search with cosine, Euclidean, or dot product distance, standard SQL with extensions for distance operations, Cypher for property graph queries (Neo4j-compatible syntax), and SPARQL for RDF triple store interactions. Persistence options include file-based storage in Node.js and IndexedDB in browsers. The package provides a comprehensive SDK for programmatic interaction and a CLI for command-line operations and an interactive REPL, making it suitable for a wide range of AI-driven applications like RAG and knowledge graphs. Its key differentiators are its multi-query language support and extreme portability across JavaScript runtimes.

Common errors

error Error: WebAssembly module instantiation failed: CompileError: WebAssembly.instantiate(): expected a WebAssembly module ↓

cause The core WebAssembly module for RvLite (`@ruvector/rvf-wasm`) failed to load or compile, often due to an incomplete or corrupted installation.

fix

Ensure @ruvector/rvf-wasm is correctly installed by running npm uninstall @ruvector/rvf-wasm && npm install @ruvector/rvf-wasm and verify Node.js version is >=18.

error Error: Database dimensions must be specified during initialization. ↓

cause The `createRvLite` or `RvLite.load` function was called without providing the `dimensions` option in the configuration object.

fix

Initialize your database instance with a dimensions property, e.g., await createRvLite({ dimensions: 384 }).

error Error: Vector dimensions mismatch. Expected X, got Y. ↓

cause An attempt was made to insert or query with a vector whose dimensionality does not match the `dimensions` the database was initialized with.

fix

Ensure all vectors passed to db.insert(), db.insertWithId(), or db.search() have the exact number of dimensions (X) that was provided during createRvLite.

error TypeError: db.sql is not a function ↓

cause Attempting to call query methods (like `.sql`, `.cypher`, `.sparql`) on an `RvLite` instance that has not been properly initialized or awaited.

fix

Ensure the database instance db is the result of an awaited call to createRvLite or RvLite.load, e.g., const db = await createRvLite({ dimensions: 384 });.

Warnings

breaking RvLite is currently at version 0.2.6. As a pre-1.0 release, the API surface may undergo breaking changes in future minor versions. ↓

fix Always review release notes when updating `rvlite` to identify and adapt to any API changes.

gotcha RvLite relies on WebAssembly (WASM) for its core functionality. Ensure your environment (Node.js, browser, Edge) supports WASM and that the `@ruvector/rvf-wasm` peer dependency is correctly installed and accessible. ↓

fix Verify that `node >= 18.0.0` is used for Node.js environments and ensure `@ruvector/rvf-wasm` is explicitly installed via `npm install @ruvector/rvf-wasm`.

gotcha The `createRvLite` and `RvLite.load` functions *require* the `dimensions` option to be provided, specifying the dimensionality of vectors stored in the database. All subsequent vector operations (insert, search) must use vectors of this exact dimension. ↓

fix Initialize the database with `createRvLite({ dimensions: YOUR_DIMENSION_NUMBER })` and ensure all vectors processed match this dimension (e.g., 384 for common embeddings).

gotcha RvLite lists `@anthropic-ai/sdk` and `@ruvector/rvf-wasm` as peer dependencies. These must be manually installed by the user alongside `rvlite` to ensure full functionality, especially `@ruvector/rvf-wasm` which is critical. ↓

fix Run `npm install rvlite @ruvector/rvf-wasm @anthropic-ai/sdk` (if Anthropic features are needed) to satisfy all peer dependencies.

Install

npm install rvlite

yarn add rvlite

pnpm add rvlite

Imports

createRvLite
wrong
```
const createRvLite = require('rvlite').createRvLite;
```
correct
```
import { createRvLite } from 'rvlite';
```
Primary factory function to initialize a new RvLite database instance. Returns a Promise and requires `dimensions` as an option.
RvLite
wrong
```
import RvLite from 'rvlite';
```
correct
```
import { RvLite } from 'rvlite';
```
The main RvLite class. Typically used for static methods such as `RvLite.load()` for persistence or for TypeScript type annotations.
RvLiteInstance
```
import type { RvLiteInstance } from 'rvlite';
```
TypeScript type definition for an initialized RvLite database instance, useful for explicit typing.

Quickstart

Demonstrates initializing a RvLite database, inserting vectors with metadata, performing semantic search, and executing SQL queries with vector distance. Includes an example of Node.js file-based persistence.

import { createRvLite } from 'rvlite';
import * as fs from 'fs'; // Required for Node.js persistence example

async function runRvLiteExample() {
  // Create a new in-memory database instance with a specified vector dimension
  const db = await createRvLite({ dimensions: 384 });
  console.log("RvLite database initialized with 384 dimensions.");

  // Insert a vector with associated metadata
  const docId1 = await db.insert([0.1, 0.2, 0.3, ...Array(381).fill(0)], { text: "The quick brown fox jumps over the lazy dog." });
  console.log(`Inserted document with ID: ${docId1}`);

  // Insert another vector with a custom ID
  const docId2 = "custom-doc-id";
  await db.insertWithId(docId2, [0.4, 0.5, 0.6, ...Array(381).fill(0)], { source: "my-blog", tags: ["nature", "animal"] });
  console.log(`Inserted document with custom ID: ${docId2}`);

  // Perform a semantic search for similar vectors, retrieving top 2 results
  const queryVector = [0.15, 0.25, 0.35, ...Array(381).fill(0)];
  const searchResults = await db.search(queryVector, 2);
  console.log("\nTop 2 search results:", searchResults);

  // Demonstrate SQL capabilities: Create a table and insert data
  await db.sql("CREATE TABLE documents (id TEXT PRIMARY KEY, content TEXT, embedding VECTOR)");
  await db.sql(`INSERT INTO documents (id, content, embedding) VALUES ('sql-doc-1', 'SQL is a powerful language.', '[0.1, 0.1, 0.1, ${Array(381).fill(0).map(() => '0.0').join(', ')}]')`);
  console.log("\nSQL table 'documents' created and data inserted.");

  // Query using SQL with vector distance function
  const sqlResults = await db.sql(`
    SELECT id, content, distance(embedding, '[0.1, 0.2, 0.3, ${Array(381).fill(0).map(() => '0.0').join(', ')}]') as dist
    FROM documents
    ORDER BY dist ASC
    LIMIT 1
  `);
  console.log("\nSQL query results with distance:", sqlResults);

  // Node.js persistence example: Export to file
  if (typeof window === 'undefined') { // Check if running in Node.js environment
    const state = await db.exportJson();
    fs.writeFileSync('rvlite_db_backup.json', JSON.stringify(state, null, 2));
    console.log("\nDatabase state exported to rvlite_db_backup.json");
  }
}

runRvLiteExample().catch(console.error);