{"id":17936,"library":"rvlite","title":"RvLite Vector Database","description":"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.","status":"active","version":"0.2.6","language":"javascript","source_language":"en","source_url":"https://github.com/ruvnet/ruvector","tags":["javascript","vector-database","embeddings","semantic-search","sql","sparql","cypher","graph-database","wasm","typescript"],"install":[{"cmd":"npm install rvlite","lang":"bash","label":"npm"},{"cmd":"yarn add rvlite","lang":"bash","label":"yarn"},{"cmd":"pnpm add rvlite","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, likely for integrating with Anthropic AI models or embedding services, used by advanced features.","package":"@anthropic-ai/sdk","optional":true},{"reason":"Crucial peer dependency providing the core WebAssembly components for vector operations, graph primitives, and database functionality.","package":"@ruvector/rvf-wasm","optional":false}],"imports":[{"note":"Primary factory function to initialize a new RvLite database instance. Returns a Promise and requires `dimensions` as an option.","wrong":"const createRvLite = require('rvlite').createRvLite;","symbol":"createRvLite","correct":"import { createRvLite } from 'rvlite';"},{"note":"The main RvLite class. Typically used for static methods such as `RvLite.load()` for persistence or for TypeScript type annotations.","wrong":"import RvLite from 'rvlite';","symbol":"RvLite","correct":"import { RvLite } from 'rvlite';"},{"note":"TypeScript type definition for an initialized RvLite database instance, useful for explicit typing.","symbol":"RvLiteInstance","correct":"import type { RvLiteInstance } from 'rvlite';"}],"quickstart":{"code":"import { createRvLite } from 'rvlite';\nimport * as fs from 'fs'; // Required for Node.js persistence example\n\nasync function runRvLiteExample() {\n  // Create a new in-memory database instance with a specified vector dimension\n  const db = await createRvLite({ dimensions: 384 });\n  console.log(\"RvLite database initialized with 384 dimensions.\");\n\n  // Insert a vector with associated metadata\n  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.\" });\n  console.log(`Inserted document with ID: ${docId1}`);\n\n  // Insert another vector with a custom ID\n  const docId2 = \"custom-doc-id\";\n  await db.insertWithId(docId2, [0.4, 0.5, 0.6, ...Array(381).fill(0)], { source: \"my-blog\", tags: [\"nature\", \"animal\"] });\n  console.log(`Inserted document with custom ID: ${docId2}`);\n\n  // Perform a semantic search for similar vectors, retrieving top 2 results\n  const queryVector = [0.15, 0.25, 0.35, ...Array(381).fill(0)];\n  const searchResults = await db.search(queryVector, 2);\n  console.log(\"\\nTop 2 search results:\", searchResults);\n\n  // Demonstrate SQL capabilities: Create a table and insert data\n  await db.sql(\"CREATE TABLE documents (id TEXT PRIMARY KEY, content TEXT, embedding VECTOR)\");\n  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(', ')}]')`);\n  console.log(\"\\nSQL table 'documents' created and data inserted.\");\n\n  // Query using SQL with vector distance function\n  const sqlResults = await db.sql(`\n    SELECT id, content, distance(embedding, '[0.1, 0.2, 0.3, ${Array(381).fill(0).map(() => '0.0').join(', ')}]') as dist\n    FROM documents\n    ORDER BY dist ASC\n    LIMIT 1\n  `);\n  console.log(\"\\nSQL query results with distance:\", sqlResults);\n\n  // Node.js persistence example: Export to file\n  if (typeof window === 'undefined') { // Check if running in Node.js environment\n    const state = await db.exportJson();\n    fs.writeFileSync('rvlite_db_backup.json', JSON.stringify(state, null, 2));\n    console.log(\"\\nDatabase state exported to rvlite_db_backup.json\");\n  }\n}\n\nrunRvLiteExample().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"fix":"Always review release notes when updating `rvlite` to identify and adapt to any API changes.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Initialize the database with `createRvLite({ dimensions: YOUR_DIMENSION_NUMBER })` and ensure all vectors processed match this dimension (e.g., 384 for common embeddings).","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Run `npm install rvlite @ruvector/rvf-wasm @anthropic-ai/sdk` (if Anthropic features are needed) to satisfy all peer dependencies.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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`.","cause":"The core WebAssembly module for RvLite (`@ruvector/rvf-wasm`) failed to load or compile, often due to an incomplete or corrupted installation.","error":"Error: WebAssembly module instantiation failed: CompileError: WebAssembly.instantiate(): expected a WebAssembly module"},{"fix":"Initialize your database instance with a `dimensions` property, e.g., `await createRvLite({ dimensions: 384 })`.","cause":"The `createRvLite` or `RvLite.load` function was called without providing the `dimensions` option in the configuration object.","error":"Error: Database dimensions must be specified during initialization."},{"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`.","cause":"An attempt was made to insert or query with a vector whose dimensionality does not match the `dimensions` the database was initialized with.","error":"Error: Vector dimensions mismatch. Expected X, got Y."},{"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 });`.","cause":"Attempting to call query methods (like `.sql`, `.cypher`, `.sparql`) on an `RvLite` instance that has not been properly initialized or awaited.","error":"TypeError: db.sql is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}