FAQ

Frequently asked questions about VectoriaDB

Find answers to common questions about VectoriaDB.

General

What is VectoriaDB?

VectoriaDB is a lightweight in-memory vector database for semantic search. It uses transformers.js to generate embeddings locally, so your data never leaves the server. It’s designed for tool discovery, document search, and recommendation systems.

When should I use VectoriaDB?

Use VectoriaDB when you need:

• Semantic search over tools, documents, or prompts
• Offline operation without external API dependencies
• Privacy-first applications where data can’t leave the server
• Type-safe metadata with TypeScript generics

For simple keyword matching without semantic understanding, consider the TF-IDF variant instead.

What's the difference between VectoriaDB and TFIDFVectoria?

Feature	VectoriaDB	TFIDFVectoria
Understanding	Semantic (understands meaning)	Keyword-based (exact matches)
Dependencies	transformers.js (~22MB model)	Zero dependencies
Initialization	Async (model download)	Synchronous
Reindex required	No	Yes, after changes

Use VectoriaDB for semantic understanding, TFIDFVectoria for simple keyword matching.

Is VectoriaDB production-ready?

Yes. VectoriaDB includes production-ready features:

• Operational guardrails: Rate limits, batch validation, document size limits
• Persistence: File and Redis storage adapters
• Error handling: Typed error classes with machine-readable codes
• HNSW indexing: Sub-millisecond queries at scale

Performance

How many documents can VectoriaDB handle?

VectoriaDB can handle 100,000+ documents efficiently:

• Brute-force search: Good for < 10,000 documents
• HNSW indexing: Required for > 10,000 documents, supports 100,000+

Memory usage is approximately 1.5KB per document (384-dimensional embeddings + metadata).

How fast is search?

Search performance depends on your configuration:

Documents	Brute-force	HNSW (ef=50)
10,000	~50ms	~1ms
50,000	~250ms	~1ms
100,000	~500ms	~2ms

Enable HNSW for sub-millisecond queries on large datasets.

Why is the first query slow?

The first query after initialization may be slower because:

1. Model warmup: The first embedding generation warms up the model
2. JIT compilation: JavaScript engines optimize hot code paths

Subsequent queries are significantly faster. Consider running a warmup query during startup.

How much memory does VectoriaDB use?

Memory usage depends on:

• Embeddings: ~1.5KB per document (384 dimensions x 4 bytes)
• Metadata: Variable based on your metadata size
• HNSW index: ~50-100 bytes per document for graph connections

For 100,000 documents, expect ~150-200MB memory usage.

Configuration

Can I use a different embedding model?

Yes. VectoriaDB supports any transformers.js-compatible model:

src/custom-model.ts

const db = new VectoriaDB({
  modelName: 'Xenova/paraphrase-MiniLM-L6-v2',
  dimensions: 384, // Match model dimensions
});

The default Xenova/all-MiniLM-L6-v2 provides good quality with fast inference.

How do I enable HNSW?

Enable HNSW for datasets > 10,000 documents:

src/enable-hnsw.ts

const db = new VectoriaDB({
  useHNSW: true,
  hnsw: {
    M: 16,           // Connections per node
    efConstruction: 200, // Build quality
    efSearch: 50,    // Search quality
  },
});

See HNSW guide for tuning details.

How do I persist embeddings?

Use a storage adapter to persist embeddings between restarts:

src/persistence.ts

const db = new VectoriaDB({
  storageAdapter: new FileStorageAdapter({
    cacheDir: './.cache/vectoriadb',
    namespace: 'my-index',
  }),
});

await db.initialize();
await db.addMany(documents);
await db.saveToStorage();

See Storage guide for details.

What's the default similarity threshold?

The default threshold is 0.3. Adjust based on your use case:

• 0.3-0.4: Loose matching, more results
• 0.5-0.6: Moderate matching, balanced
• 0.7+: Strict matching, high precision

Start low and increase if you’re getting too many irrelevant results.

Troubleshooting

Why am I getting VectoriaNotInitializedError?

You must call initialize() before any operation:

src/fix-not-initialized.ts

const db = new VectoriaDB();
await db.initialize(); // Required!

await db.add('id', 'text', metadata);

initialize() is idempotent - calling it multiple times is safe.

Why are my search results empty?

Common causes:

1. Threshold too high: Lower the threshold option
2. No matching documents: Check that documents are indexed
3. Filter too restrictive: Review your filter function

src/debug-search.ts

// Debug: search without filters
const results = await db.search(query, {
  threshold: 0.1, // Low threshold
  topK: 20,       // More results
  // No filter
});
console.log('Found:', results.length);

Model download fails - what should I do?

If model download fails:

1. Check network: Ensure internet access to Hugging Face
2. Check permissions: Ensure write access to cacheDir
3. Use a proxy: Set HTTPS_PROXY environment variable
4. Pre-download: Download the model manually

The model is cached after first download.

How do I debug poor search quality?

To improve search quality:

1. Check document text: Ensure text is descriptive
2. Adjust threshold: Try different values
3. Inspect scores: Look at result.score values
4. Review embeddings: Use includeVector: true to inspect

src/debug-quality.ts

const results = await db.search(query, {
  topK: 10,
  threshold: 0.0, // Show all
  includeVector: true,
});

for (const r of results) {
  console.log(`${r.id}: ${r.score.toFixed(3)}`);
}

Related

Common Errors

Error reference and solutions

Error Handling

Programmatic error handling