vectorlite

library0.2.0jsnpmunverified

Vectorlite v0.2.0 is a fast and tunable vector search extension for SQLite, enabling approximate nearest neighbor (ANN) search within SQLite databases. It provides virtual table syntax for creating vector indexes (e.g., with HNSW) and supports storing vectors as JSON or raw float32 buffers. Key differentiators include high performance, tunable parameters, and simple integration with node.js via better-sqlite3 or other SQLite bindings. The release cadence is currently unknown; check GitHub for updates.

database

npm install vectorlite

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VECTORLITE

vectorlite

databasejavascriptv0.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

vectorlitePath

✓ import { vectorlitePath } from 'vectorlite'

✗ const vectorlitePath = require('vectorlite').vectorlitePath

ESM import is standard; the library may also support require(). The path is used with db.loadExtension().

vectorlite (default)

✓ import vectorlite from 'vectorlite'

✗ const vectorlite = require('vectorlite')

The default export provides vectorlitePath() and possibly other utilities. In CJS, require works fine.

vector_from_json

✓ SELECT vector_from_json(json_string)

✗ SELECT vector_from_json(JSON.stringify(array))

vector_from_json expects a JSON string; you can pass it directly in SQL as a parameter or literal.

Creates an in-memory SQLite database with a vector virtual table using better-sqlite3, inserts two vectors, and performs a k-nearest neighbor search for the top 2 results.

import Database from 'better-sqlite3'; import { vectorlitePath } from 'vectorlite'; const db = new Database(':memory:'); db.loadExtension(vectorlitePath()); db.exec(`CREATE VIRTUAL TABLE vec_test USING vectorlite(vec float32[3], hnsw(max_elements=100));`); db.prepare('INSERT INTO vec_test(rowid, vec) VALUES (?, vector_from_json(?))').run(1, JSON.stringify([0.1, 0.2, 0.3])); db.prepare('INSERT INTO vec_test(rowid, vec) VALUES (?, vector_from_json(?))').run(2, JSON.stringify([0.4, 0.5, 0.6])); const query = Float32Array.from([0.15, 0.25, 0.35]).buffer; const results = db.prepare('SELECT rowid FROM vec_test WHERE knn_search(vec, knn_param(?, 2))').all(Buffer.from(query)); console.log(results); // Output: [ { rowid: 1 }, { rowid: 2 } ]

Debug

Known issues

gotchaWhen using vector_from_json, you must pass a JSON string, not a JavaScript object.

fix

Use JSON.stringify() to serialize arrays before passing to vector_from_json.

affects: >=0.1.0

gotchaThe raw vector buffer must be a Buffer created from a Float32Array's underlying ArrayBuffer. Passing a plain Buffer may produce incorrect results.

fix

Use Buffer.from(Float32Array.from(array).buffer) to create the correct buffer.

affects: >=0.1.0

deprecatedvectorlite_info() function returns version info but its output format may change between minor versions.

fix

Do not parse the output of vectorlite_info() programmatically; use only for debugging.

affects: >=0.1.0

gotchaThe knn_param() function's second argument (k) is the number of neighbors. The first argument is the query vector buffer.

fix

Ensure the first argument to knn_search is the query vector buffer, and knn_param is the second argument.

affects: >=0.1.0

gotchaThe vector index (HNSW) parameters like max_elements must be set at creation time and cannot be changed later.

fix

Plan vector capacity ahead when defining the virtual table.

affects: >=0.1.0

Errors

Common errors & fixes

SQLITE_ERROR: no such module: vectorlite

Vectorlite extension not loaded into the SQLite connection.

fix

Call db.loadExtension(vectorlitePath()) before executing any vectorlite SQL commands.

TypeError: vectorlitePath is not a function

Importing vectorlite incorrectly (e.g., using default import where vectorlitePath is not exported).

fix

Use named import: import { vectorlitePath } from 'vectorlite'.

SQLITE_ERROR: unknown function: vector_from_json

Vectorlite extension not loaded before using vector_from_json function.

fix

Ensure db.loadExtension(vectorlitePath()) is called first.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node