Skip to content

Guide: Search and filters

This page covers search options, HNSW, Web Workers, and metadata filtering.

By text:

const results = await db.searchText('your query', { k: 5 });

By vector:

const results = await db.search(queryVector, { k: 5 });

Each result: { id, score, metadata }. Results are ordered by score (cosine similarity) descending.

Search options

Option Type Default Description
k number 10 Number of results to return.
filter object — Metadata filter (see Metadata filtering).
useHnsw boolean true Use HNSW when available; otherwise brute-force.
useWorker boolean false Run brute-force search in a Web Worker.

Example:

const results = await db.searchText('query', {
  k: 20,
  filter: { category: 'docs', status: 'published' },
  useHnsw: true,
  useWorker: true,
});

HNSW (approximate nearest neighbor)

Vecnest uses HNSW (Hierarchical Navigable Small World) via hnswlib-wasm for fast approximate search. When possible, search uses the HNSW index instead of a full brute-force scan.

  • Automatic: HNSW is used when the index exists and is valid; otherwise Vecnest falls back to brute-force.
  • Updates/deletes: The HNSW index is rebuilt asynchronously after updates or deletes so results stay correct.
  • Manual rebuild: Use rebuildIndex(dimensions, opts?) after bulk changes if needed:
await db.rebuildIndex(384, { maxElements: 10000, m: 16, efConstruction: 200 });

Web Workers

Brute-force search can run in a Web Worker so the main thread stays responsive. Enable it with useWorker: true:

const results = await db.search(queryVector, { k: 100, useWorker: true });

Use Workers when you have many vectors and no HNSW (or HNSW disabled). If HNSW is used, the Worker is not involved.

Metadata filtering

You can filter results by metadata. Simple equality:

const results = await db.searchText('query', {
  k: 10,
  filter: { category: 'docs', lang: 'en' },
});

Advanced operators ($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin):

const results = await db.searchText('query', {
  k: 10,
  filter: {
    score: { $gte: 0.8 },
    views: { $lt: 1000 },
    status: { $in: ['active', 'pending'] },
    deleted: { $ne: true },
  },
});

Filtering is applied after retrieval (top-k), then results are re-sorted by score. For full details and examples, see Metadata filtering.

React hooks and search options

Pass the same options into useSearchText (or useSearch):

const { results } = useSearchText(db, query, {
  k: 5,
  filter: { category: 'docs' },
  useWorker: true,
});

Next steps