Skip to content

Vecnest tutorial

1. Add and search text (browser)

Install Vecnest and run in a browser context (Vite, Next.js, etc.):

npm install vecnest

import { VecnestDB } from 'vecnest';

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

// Add documents
await db.addText('Vecnest stores vectors in IndexedDB.', { id: 'a' });
await db.addText('Transformers.js embeds text in the browser.', { id: 'b' });
await db.addText('Cosine similarity finds nearest vectors.', { id: 'c' });

// Search by text (query is embedded, then we search)
const results = await db.searchText('Where are vectors stored?', { k: 5 });
for (const r of results) {
  console.log(r.metadata.text, '—', r.score);
}

db.close();

2. Use your own vectors

Skip embeddings and supply vectors yourself:

import { VecnestDB } from 'vecnest';

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

// Insert raw vectors (e.g. from your API or another model)
await db.insert([0.1, -0.2, 0.5, ...], { docId: '1', title: 'Doc 1' });
await db.insert([0.3, 0.1, -0.1, ...], { docId: '2', title: 'Doc 2' });

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

3. React hooks

import { useVecnest, useSearchText } from 'vecnest/react';

function SearchUI() {
  const { db, loading, error } = useVecnest('my-app-db');
  const [q, setQ] = useState('');
  const { results, loading: searchLoading } = useSearchText(db, q, { k: 5 });

  if (loading) return <p>Loading DB…</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!db) return null;

  return (
    <div>
      <input value={q} onChange={(e) => setQ(e.target.value)} placeholder="Search" />
      {searchLoading && <span>Searching…</span>}
      <ul>
        {results.map((r) => (
          <li key={r.id}>{r.metadata?.text} (score: {r.score.toFixed(4)})</li>
        ))}
      </ul>
    </div>
  );
}

4. Run the examples

From the repo root:

npm install
npm run dev      # React demo at http://localhost:5174
npm run dev:js   # JS-only example at http://localhost:5175

Next steps