Skip to content

Guide: JavaScript API

This page walks through the JavaScript API: VecnestDB, adding text, using raw vectors, and searching.

VecnestDB class

The high-level client is VecnestDB. You give it a database name (IndexedDB), connect, then call methods.

import { VecnestDB } from 'vecnest';

const db = new VecnestDB('my-db');
await db.connect();

// ... use db ...

db.close();
  • new VecnestDB(name) — name is the IndexedDB database name (default 'vecnest').
  • connect() — Opens the DB. Must be called before other methods.
  • close() — Closes the DB. Call when done (e.g. on app tear-down).

Add text (with embeddings)

Use addText to store text. Vecnest embeds it via Transformers.js, then inserts the vector and metadata.

await db.addText('Your text here.', { source: 'doc1', category: 'intro' });

Metadata is optional. The stored metadata object always includes text (the string you passed). You can add any extra keys.

Add multiple texts efficiently with addTexts:

const texts = [
  'First document.',
  'Second document.',
  'Third document.',
];
const ids = await db.addTexts(texts, { source: 'batch-1' });
// ids: [1, 2, 3]

You can pass per-text metadata as an array:

const ids = await db.addTexts(
  ['Doc A', 'Doc B', 'Doc C'],
  [
    { category: 'a' },
    { category: 'b' },
    { category: 'c' },
  ]
);

Use your own vectors

Skip embeddings and store raw vectors with insert:

const vector = [0.1, -0.2, 0.5, 0.0, ...]; // length must match your search vectors
await db.insert(vector, { docId: '1', title: 'Doc 1' });

Vectors must be same length across the database when using HNSW. Typical embedding size (e.g. MiniLM) is 384 dimensions.

Batch insert with insertBatch (low-level API; see API reference):

import { openDB, insertBatch } from 'vecnest';

const db = await openDB('my-db');
const items = [
  { vector: [0.1, -0.2, ...], metadata: { title: 'A' } },
  { vector: [0.3, 0.1, ...], metadata: { title: 'B' } },
];
const ids = await insertBatch(db, items);
db.close();

Search by text

searchText embeds the query string, then runs similarity search:

const results = await db.searchText('What is machine learning?', { k: 5 });

for (const r of results) {
  console.log(r.id, r.score, r.metadata?.text);
}

Each result has:

  • id — Vector ID.
  • score — Cosine similarity (0–1, higher = more similar).
  • metadata — Stored metadata (including text when added via addText).

Search by vector

Use search when you already have a query vector:

import { embed } from 'vecnest';

const queryVector = await embed('your query');
const results = await db.search(queryVector, { k: 10 });

Or use a vector from your own model:

const queryVector = [0.15, -0.1, 0.4, ...];
const results = await db.search(queryVector, { k: 10 });

Embedding API

Vecnest re-exports embed and embedBatch from the embeddings layer:

import { embed, embedBatch } from 'vecnest';

const v = await embed('Hello world');
// v: number[] (e.g. 384 dimensions)

const vs = await embedBatch(['A', 'B', 'C']);
// vs: number[][]

Use these when you need vectors without storing them (e.g. to call search directly or pass to another system).

Next steps