Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createRvLite
✓ import { createRvLite } from 'rvlite';
✗ const createRvLite = require('rvlite').createRvLite;
Primary factory function to initialize a new RvLite database instance. Returns a Promise and requires `dimensions` as an option.
RvLite
✓ import { RvLite } from 'rvlite';
✗ 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.
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);
rvl --version
Errors
Common errors & fixes
Error: WebAssembly module instantiation failed: CompileError: WebAssembly.instantiate(): expected a WebAssembly module
The core WebAssembly module for RvLite (`@ruvector/rvf-wasm`) failed to load or compile, often due to an incomplete or corrupted installation.
fixEnsure `@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: Database dimensions must be specified during initialization.
The `createRvLite` or `RvLite.load` function was called without providing the `dimensions` option in the configuration object.
fixInitialize your database instance with a `dimensions` property, e.g., `await createRvLite({ dimensions: 384 })`. Error: Vector dimensions mismatch. Expected X, got Y.
An attempt was made to insert or query with a vector whose dimensionality does not match the `dimensions` the database was initialized with.
fixEnsure all vectors passed to `db.insert()`, `db.insertWithId()`, or `db.search()` have the exact number of dimensions (X) that was provided during `createRvLite`.
TypeError: db.sql is not a function
Attempting to call query methods (like `.sql`, `.cypher`, `.sparql`) on an `RvLite` instance that has not been properly initialized or awaited.
fixEnsure the database instance `db` is the result of an awaited call to `createRvLite` or `RvLite.load`, e.g., `const db = await createRvLite({ dimensions: 384 });`. Audit
Dependencies
@anthropic-ai/sdkoptionalPeer dependency, likely for integrating with Anthropic AI models or embedding services, used by advanced features.
@ruvector/rvf-wasmrequiredCrucial peer dependency providing the core WebAssembly components for vector operations, graph primitives, and database functionality.