Skip to content

API reference

Full reference for the core (vecnest) and React (vecnest/react) APIs.

Core API (vecnest)

openDB(name?)

Opens the IndexedDB database.

import { openDB } from 'vecnest';

const db = await openDB('my-db');
// ... use db ...
db.close();
Parameter Type Default Description
name string 'vecnest' IndexedDB database name.

Returns: Promise<IDBDatabase>

insert(db, vector, metadata?, opts?)

Inserts a vector and metadata. Optionally updates the HNSW index.

import { openDB, insert } from 'vecnest';

const db = await openDB('my-db');
const id = await insert(db, [0.1, -0.2, 0.5, ...], { label: 'doc-1' }, { updateHnsw: true });
db.close();
Parameter Type Description
db IDBDatabase From openDB.
vector number[] Vector to store.
metadata object Optional metadata.
opts.updateHnsw boolean Update HNSW index (default true).

Returns: Promise<number> — Inserted record ID.

insertBatch(db, items, opts?)

Batch insert in a single transaction. More efficient than multiple insert calls.

import { openDB, insertBatch } from 'vecnest';

const db = await openDB('my-db');
const items = [
  { vector: [0.1, ...], metadata: { title: 'A' } },
  { vector: [0.2, ...], metadata: { title: 'B' } },
];
const ids = await insertBatch(db, items, { updateHnsw: true });
// ids: [1, 2]
db.close();
Parameter Type Description
db IDBDatabase From openDB.
items Array<{ vector, metadata? }> Vectors and optional metadata.
opts.updateHnsw boolean Update HNSW index (default true).

Returns: Promise<number[]> — Inserted IDs, same order as items.

search(db, queryVector, opts?)

Similarity search by vector.

import { openDB, search } from 'vecnest';

const db = await openDB('my-db');
const results = await search(db, queryVector, {
  k: 10,
  filter: { category: 'docs' },
  useHnsw: true,
  useWorker: false,
});
// results: [{ id, score, metadata }, ...]
db.close();
Parameter Type Description
db IDBDatabase From openDB.
queryVector number[] Query vector.
opts.k number Max results (default 10).
opts.filter object Metadata filter. See Metadata filtering.
opts.useHnsw boolean Use HNSW (default true).
opts.useWorker boolean Use Web Worker for brute-force (default false).

Returns: Promise<Array<{ id: number, score: number, metadata: object }>>

update(db, id, updates)

Updates a vector and/or metadata by ID.

import { openDB, update } from 'vecnest';

const db = await openDB('my-db');
await update(db, 123, {
  vector: newVector,       // optional
  metadata: { key: 'val' }, // merged with existing
});
db.close();
Parameter Type Description
db IDBDatabase From openDB.
id number Record ID.
updates.vector number[] New vector (optional).
updates.metadata object Metadata to merge (optional).

Returns: Promise<void>

remove(db, id, opts?)

Deletes a vector by ID. Optionally rebuilds the HNSW index.

import { openDB, remove } from 'vecnest';

const db = await openDB('my-db');
await remove(db, 123, { rebuildHnsw: true });
db.close();
Parameter Type Description
db IDBDatabase From openDB.
id number Record ID.
opts.rebuildHnsw boolean Rebuild HNSW after delete (default true).

Returns: Promise<void>

count(db)

Returns the total number of vectors.

import { openDB, count } from 'vecnest';

const db = await openDB('my-db');
const n = await count(db);
db.close();

Returns: Promise<number>

list(db, opts?)

Lists vectors, newest first, with optional pagination.

import { openDB, list } from 'vecnest';

const db = await openDB('my-db');
const items = await list(db, { limit: 50, offset: 0 });
// items: [{ id, vector, metadata, created }, ...]
db.close();
Parameter Type Description
opts.limit number Max items (default 50).
opts.offset number Skip (default 0).

Returns: Promise<Array<{ id, vector, metadata, created }>>

getStorageEstimate()

Returns storage usage and quota for the current origin (bytes). Not specific to Vecnest.

import { getStorageEstimate } from 'vecnest';

const { usage, quota } = await getStorageEstimate();

Returns: Promise<{ usage: number, quota: number }>

cosineSimilarity(a, b)

Computes cosine similarity between two vectors.

import { cosineSimilarity } from 'vecnest';

const sim = cosineSimilarity([0.1, 0.2], [0.1, 0.2]); // 1

Returns: number (0–1 when normalized).

embed(text, opts?) / embedBatch(texts, opts?)

Transformers.js embeddings. Use when you need vectors without storing them.

import { embed, embedBatch } from 'vecnest';

const v = await embed('Hello');
const vs = await embedBatch(['A', 'B', 'C']);

Returns: Promise<number[]> / Promise<number[][]>

rebuildHnswIndex(db, dimensions, maxElements?, m?, efConstruction?)

Rebuilds the HNSW index from all vectors. Use after bulk updates/deletes.

import { openDB, rebuildHnswIndex } from 'vecnest';

const db = await openDB('my-db');
await rebuildHnswIndex(db, 384, 10000, 16, 200);
db.close();

VecnestDB

High-level client. Use vecnest (not raw openDB) for most apps.

Constructor

import { VecnestDB } from 'vecnest';

const db = new VecnestDB('my-db');

Methods

Method Description
connect() Opens DB. Required before other methods.
close() Closes DB.
insert(vector, metadata?, opts?) Insert vector + metadata.
addText(text, metadata?) Embed + insert.
addTexts(texts, metadata?) Batch embed + insert.
search(queryVector, opts?) Vector search.
searchText(queryText, opts?) Embed query + search.
update(id, { vector?, metadata? }) Update by ID.
delete(id, opts?) Delete by ID.
count() Total vector count.
list(opts?) List with pagination.
rebuildIndex(dimensions, opts?) Rebuild HNSW index.

Static

Method Description
VecnestDB.getStorageEstimate() { usage, quota } in bytes.

React API (vecnest/react)

useVecnest(dbName)

Opens the DB and returns { db, loading, error }. Closes on unmount.

const { db, loading, error } = useVecnest('my-db');

useSearch(db, queryVector, opts?)

Runs vector search. Returns { results, loading, error }.

const { results, loading, error } = useSearch(db, queryVector, { k: 5, filter, useHnsw, useWorker });

Use a stable queryVector (e.g. useMemo) to avoid unnecessary re-runs.

useSearchText(db, queryText, opts?)

Embeds the query and runs search. Returns { results, loading, error }.

const { results, loading, error } = useSearchText(db, query, { k: 5, filter, useHnsw, useWorker });

See also