Skip to content

Guides

Vector search

Semantic similarity search with embeddings

KiteDB has built-in vector search for similarity queries. You store an embedding per node, and an approximate nearest-neighbor index (IVF, or IVF-PQ for large high-dimensional collections) finds the nearest vectors to a query embedding.

Creating a vector index

TypeScript
import { createVectorIndex, DistanceMetric } from '@kitedb/core';// Create an index for 1536-dimensional vectors (OpenAI embeddings)const index = createVectorIndex({  dimensions: 1536,  metric: DistanceMetric.Cosine, // or Euclidean, DotProduct});

Storing embeddings

TypeScript
// Generate embedding with your preferred providerconst response = await openai.embeddings.create({  model: 'text-embedding-ada-002',  input: 'Your document content here',});const embedding = response.data[0].embedding;// Store the vector, associated with a node IDindex.set(doc.id, embedding);
TypeScript
// Search for similar vectorsconst queryEmbedding = await getEmbedding('search query');const results = index.search(queryEmbedding, {  k: 10,           // Return top 10 results  threshold: 0.7,  // Minimum similarity (0-1)});// Results contain nodeId, distance, and similarityfor (const hit of results) {  console.log(`Node ${hit.nodeId}: similarity=${hit.similarity.toFixed(3)}`);}

Index management

TypeScript
// Check if a node has a vectorconst hasVector = index.has(doc.id);// Get a stored vectorconst vector = index.get(doc.id);// Delete a vectorindex.delete(doc.id);// Build/rebuild the IVF index for faster searchindex.buildIndex();// Get index statisticsconst stats = index.stats();console.log(`Total vectors: ${stats.totalVectors}`);

Choosing the index backend

By default (auto) the index picks its backend each time it builds, from the live vector count and dimensions at that point:

  • Plain IVF while the collection has fewer than 50,000 vectors or fewer than 512 dimensions. Results carry exact distances, and builds are fast.
  • IVF-PQ from 512 dimensions and 50,000 vectors on. Searches scan compact product-quantization codes (2.9x faster than IVF at 768 dimensions and 50,000 vectors in our measurements) and re-rank the best candidates by exact distance. Raise rerankFactor for higher recall.

The index rebuilds itself on the next search as it grows (at 4x the size it was built at, or when it crosses the threshold), so a growing collection moves from IVF to IVF-PQ on its own. Set the backend explicitly to keep one:

TypeScript
import { AnnAlgorithm, createVectorIndex } from '@kitedb/core';const index = createVectorIndex({  dimensions: 1536,  annAlgorithm: AnnAlgorithm.Ivf, // 'ivf' | 'ivf_pq' | 'auto' (default)});index.buildIndex();console.log(index.stats().indexAlgorithm); // 'ivf'

Next steps