migration guide

Migrate from Typesense to altor-vec

Eliminate your Typesense server and run zero-infrastructure semantic search in the browser with altor-vec. Migration guide for documentation and static site search use cases.

When migration makes sense

• You are self-hosting Typesense (or paying Typesense Cloud) for a public documentation site that could serve search as a static asset
• You want semantic/meaning-based search rather than Typesense's keyword+typo-tolerance approach
• You need offline search or want to eliminate the server dependency entirely

What you give up

Migration is not always the right call. altor-vec cannot replace Typesense for:

• Typo tolerance: altor-vec does not correct misspellings — it finds semantically similar results, which may or may not match typos
• Real-time indexing: Typesense can index new documents instantly; altor-vec requires an index rebuild
• Faceting: Typesense has a powerful filter/facet query language; altor-vec requires post-retrieval filtering

Step-by-step migration

// 1. Export documents from Typesense
import Typesense from 'typesense';
import { writeFileSync } from 'fs';

const client = new Typesense.Client({
  nodes: [{ host: 'your-host', port: 443, protocol: 'https' }],
  apiKey: process.env.TYPESENSE_API_KEY,
  connectionTimeoutSeconds: 2,
});

// Export all documents
const docs = [];
let page = 1;
while (true) {
  const result = await client.collections('your-collection').documents().search({
    q: '*', query_by: 'title', per_page: 250, page,
  });
  docs.push(...result.hits.map(h => h.document));
  if (result.hits.length < 250) break;
  page++;
}
writeFileSync('typesense-export.json', JSON.stringify(docs));
console.log(`Exported ${docs.length} documents`);

// 2. Build altor-vec index at build time
import { pipeline } from '@xenova/transformers';
import init, { WasmSearchEngine } from 'altor-vec';
await init();
const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');

const DIM = 384;
const vectors = new Float32Array(docs.length * DIM);
for (const [i, doc] of docs.entries()) {
  const text = `${doc.title}. ${doc.description ?? doc.content ?? ''}`;
  const out = await embedder(text, { pooling: 'mean', normalize: true });
  vectors.set(out.data, i * DIM);
}

const engine = WasmSearchEngine.from_vectors(vectors, DIM, 16, 200, 50);
writeFileSync('public/search-index.json', engine.to_json());
writeFileSync('public/docs-metadata.json', JSON.stringify(docs));

After migration

Once your index is built and deployed to public/search-index.json, load it in the browser:

import init, { WasmSearchEngine } from 'altor-vec';
import { pipeline } from '@xenova/transformers';

await init();
const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
const resp = await fetch('/search-index.json');
const engine = WasmSearchEngine.from_json(await resp.text());

async function search(query, k = 5) {
  const out = await embedder(query, { pooling: 'mean', normalize: true });
  const hits = JSON.parse(engine.search(new Float32Array(out.data), k));
  return hits; // [{id, score}] - map id back to your metadata
}

Frequently asked questions

Does altor-vec support typo-tolerant search like Typesense?

No. altor-vec uses semantic embedding similarity, not keyword matching. A misspelled query like 'serach' won't be corrected, but it may still return relevant results if the embedding model maps it close to 'search'. For hard typo-tolerance requirements, Typesense is the better fit.

Which is better for documentation search: altor-vec or Typesense?

altor-vec is better when you want meaning-based search with zero infrastructure. Typesense is better when you need typo tolerance, real-time indexing, and a managed search service. Many doc sites use altor-vec for the simplicity; Algolia DocSearch users often migrate to either.

Can I run altor-vec and Typesense together?

Yes. A hybrid approach works well: use Typesense for keyword/typo-tolerant search and altor-vec for semantic search, then merge and deduplicate results. This gives users both exact-match and concept-match results.

How do I handle search updates after migrating from Typesense?

Rebuild the altor-vec index on every deploy using a Node.js build script. If content changes frequently (multiple times per day), consider keeping Typesense for real-time content and using altor-vec only for static/cached content.