Skip to main content

Node.js API Reference

Complete reference for the vectlite npm package.

const vectlite = require('vectlite')
// or
import * as vectlite from 'vectlite'

Module Functions​

open​

function open(path: string, options?: OpenOptions): Database

Open or create a vectlite database.

ParameterTypeDescription
pathstringPath to the .vdb file. Created if it does not exist.
optionsOpenOptionsOptional configuration.

OpenOptions

PropertyTypeDefaultDescription
dimensionnumber--Vector dimension. Required when creating a new database.
readOnlybooleanfalseOpen in read-only mode.

Returns: Database

openStore​

function openStore(root: string): Store

Open or create a collection store directory.

ParameterTypeDescription
rootstringPath to the store directory.

Returns: Store

restore​

function restore(source: string, dest: string): Database

Restore a backup to a new database path.

ParameterTypeDescription
sourcestringPath to the backup directory.
deststringPath for the restored .vdb file.

Returns: Database

sparseTerms​

function sparseTerms(text: string): SparseVector

Tokenize and weight text into a sparse term vector for BM25 search.

ParameterTypeDescription
textstringInput text.

Returns: SparseVector (Record<string, number>)

upsertText​

function upsertText(
  db: Database,
  id: string,
  text: string,
  embed: (text: string) => number[] | Promise<number[]>,
  metadata?: Metadata,
  options?: { namespace?: string }
): void | Promise<void>

High-level helper that generates a dense embedding and sparse terms from text, then upserts the record. If embed returns a Promise, the function is async.

ParameterTypeDescription
dbDatabaseTarget database.
idstringRecord identifier.
textstringText to embed and index.
embed(text: string) => number[] | Promise<number[]>Embedding function.
metadataMetadataOptional metadata object.
options.namespacestringOptional namespace.

searchText​

function searchText(
  db: Database,
  text: string,
  embed: (text: string) => number[] | Promise<number[]>,
  options?: SearchOptions
): SearchResult[] | Promise<SearchResult[]>

High-level hybrid search. Generates a dense embedding and sparse terms from text, then runs a fused search. Async if embed returns a Promise.

ParameterTypeDescription
dbDatabaseTarget database.
textstringNatural-language query.
embed(text: string) => number[] | Promise<number[]>Embedding function.
optionsSearchOptionsSearch configuration (see SearchOptions).

Returns: SearchResult[]

searchTextWithStats​

function searchTextWithStats(
  db: Database,
  text: string,
  embed: (text: string) => number[] | Promise<number[]>,
  options?: SearchOptions
): SearchResponse | Promise<SearchResponse>

Same as searchText but returns a SearchResponse with results and query statistics.

Database​

Returned by open() and restore().

Properties​

PropertyTypeDescription
pathstringAbsolute path to the .vdb file.
walPathstringPath to the write-ahead log file.
dimensionnumberVector dimension.
readOnlybooleanWhether opened in read-only mode.

count​

count(namespace?: string): number

Return the number of records, optionally scoped to a namespace.

namespaces​

namespaces(): string[]

Return all namespace names.

transaction​

transaction(): Transaction

Begin a new transaction.

Returns: Transaction

insert​

insert(
  id: string,
  vector: number[],
  metadata?: Metadata,
  options?: WriteOptions
): void

Insert a new record. Throws VectLiteError if the ID already exists.

upsert​

upsert(
  id: string,
  vector: number[],
  metadata?: Metadata,
  options?: WriteOptions
): void

Insert or replace a record.

WriteOptions

PropertyTypeDescription
namespacestringTarget namespace.
sparseSparseVectorSparse term vector for BM25.
vectorsNamedVectorsAdditional named vectors.

insertMany​

insertMany(records: Record[], options?: { namespace?: string }): number

Batch insert. Returns the number of records inserted.

upsertMany​

upsertMany(records: Record[], options?: { namespace?: string }): number

Batch upsert. Returns the number of records upserted.

bulkIngest​

bulkIngest(
  records: Iterable<Record> | AsyncIterable<Record>,
  options?: BulkIngestOptions
): number | Promise<number>

Stream large datasets into the database. Async if given an AsyncIterable.

BulkIngestOptions

PropertyTypeDefaultDescription
namespacestring--Target namespace.
batchSizenumber1000Commit every N records.
onProgress(count: number) => void--Progress callback.

Returns: number -- total records ingested.

get​

get(id: string, options?: { namespace?: string }): Record | null

Retrieve a record by ID. Returns null if not found.

delete​

delete(id: string, options?: { namespace?: string }): boolean

Delete a record. Returns true if the record existed.

deleteMany​

deleteMany(ids: string[], options?: { namespace?: string }): number

Delete multiple records. Returns the count of records deleted.

flush​

flush(): void

Flush pending writes to the WAL.

compact​

compact(): void

Merge WAL into the main .vdb file and rebuild ANN indexes as needed.

snapshot​

snapshot(dest: string): void

Create a self-contained database copy at dest.

backup​

backup(dest: string): void

Full backup of .vdb and ANN sidecar files to dest directory.

search(
  vector: number[] | null,
  options?: SearchOptions
): SearchResult[]

Run a search query. Pass null as the vector for sparse-only or multi-vector search.

Returns: SearchResult[]

searchWithStats​

searchWithStats(
  vector: number[] | null,
  options?: SearchOptions
): SearchResponse

Same as search() but returns a SearchResponse.

Store​

Returned by openStore(). Manages a directory of collections.

Properties​

PropertyTypeDescription
rootstringAbsolute path to the store directory.

collections​

collections(): string[]

List all collection names.

createCollection​

createCollection(name: string, dimension: number): Database

Create a new collection. Throws if it already exists.

openOrCreateCollection​

openOrCreateCollection(name: string, dimension: number): Database

Open or create a collection.

openCollection​

openCollection(name: string): Database

Open an existing collection. Throws if it does not exist.

dropCollection​

dropCollection(name: string): void

Delete a collection and its data from disk.

Transaction​

Returned by Database.transaction(). Node.js does not have a with statement, so you must call commit() or rollback() manually.

const tx = db.transaction()
try {
  tx.upsert('doc1', emb1, { source: 'a' })
  tx.delete('old_doc')
  tx.commit()
} catch (err) {
  tx.rollback()
  throw err
}

insert​

insert(
  id: string,
  vector: number[],
  metadata?: Metadata,
  options?: WriteOptions
): void

upsert​

upsert(
  id: string,
  vector: number[],
  metadata?: Metadata,
  options?: WriteOptions
): void

insertMany​

insertMany(records: Record[], options?: { namespace?: string }): number

upsertMany​

upsertMany(records: Record[], options?: { namespace?: string }): number

delete​

delete(id: string, options?: { namespace?: string }): void

commit​

commit(): void

Commit all queued operations atomically.

rollback​

rollback(): void

Discard all queued operations.

length​

readonly length: number

Number of queued operations in the transaction.

Interfaces​

OpenOptions​

interface OpenOptions {
  dimension?: number
  readOnly?: boolean
}

WriteOptions​

interface WriteOptions {
  namespace?: string
  sparse?: SparseVector
  vectors?: NamedVectors
}

SearchOptions​

interface SearchOptions {
  k?: number                    // default: 10
  filter?: Filter
  namespace?: string
  allNamespaces?: boolean       // default: false
  sparse?: SparseVector
  denseWeight?: number          // default: 1.0
  sparseWeight?: number         // default: 1.0
  fusion?: 'linear' | 'rrf'    // default: 'linear'
  rrfK?: number                 // default: 60
  fetchK?: number               // default: 0
  mmrLambda?: number
  vectorName?: string
  queryVectors?: NamedVectors
  vectorWeights?: Record<string, number>
  explain?: boolean             // default: false
  rerank?: RerankHook
  rerankK?: number              // default: 0
}

BulkIngestOptions​

interface BulkIngestOptions {
  namespace?: string
  batchSize?: number            // default: 1000
  onProgress?: (count: number) => void
}

Record​

interface Record {
  id: string
  vector: number[]
  metadata?: Metadata
  sparse?: SparseVector
  vectors?: NamedVectors
  namespace?: string
  score?: number                // present in search results
}

SearchResult​

interface SearchResult {
  id: string
  score: number
  metadata: Metadata
  namespace: string
  explain?: ExplainDetails
}

ExplainDetails​

interface ExplainDetails {
  denseScore: number
  sparseScore: number
  fusedScore: number
  rerankScore?: number
}

SearchStats​

interface SearchStats {
  candidatesEvaluated: number
  indexType: 'hnsw' | 'flat'
  timings: SearchTimings
}

SearchTimings​

interface SearchTimings {
  totalMs: number
  indexMs: number
  filterMs: number
  rankMs: number
  rerankMs?: number
}

SearchResponse​

interface SearchResponse {
  results: SearchResult[]
  stats: SearchStats
}

MetadataValue​

type MetadataValue = string | number | boolean | null | MetadataValue[] | { [key: string]: MetadataValue }

Metadata​

type Metadata = Record<string, MetadataValue>

SparseVector​

type SparseVector = Record<string, number>

NamedVectors​

type NamedVectors = Record<string, number[]>

Filter​

type Filter = Record<string, any>

MongoDB-style filter expression. See Metadata Filters for the full query syntax.

RerankHook​

type RerankHook = (query: string, results: SearchResult[]) => SearchResult[]

Error​

VectLiteError​

class VectLiteError extends Error {
  constructor(message: string)
}

Thrown for all vectlite errors including:

  • Write operations on a read-only database
  • Duplicate ID on insert()
  • Dimension mismatch
  • Corrupt database file
  • File lock contention
  • I/O errors