Skip to main content
Learn how VectoriaDB manages cache invalidation and when re-indexing occurs.

​
How Invalidation Works

VectoriaDB validates the cache on initialize() by checking:
  1. Cache exists: Does the storage have cached data?
  2. Tools hash matches: Has the document content changed?
  3. Version matches: Has the application version changed?
  4. Model matches: Is the embedding model the same?
If any check fails, the cache is invalidated.

​
Configuration

src/cache-config.ts
import { VectoriaDB, FileStorageAdapter, SerializationUtils } from 'vectoriadb';

const documents = collectToolDocuments();

const db = new VectoriaDB<ToolDocument>({
  storageAdapter: new FileStorageAdapter({
    cacheDir: './.cache/vectoriadb',
  }),

  // Hash of document contents - invalidates when documents change
  toolsHash: SerializationUtils.createToolsHash(documents),

  // Application version - invalidates on deployments
  version: process.env.npm_package_version,

  // Model name - invalidates if model changes
  modelName: 'Xenova/all-MiniLM-L6-v2',
});

​
Tools Hash

Create a deterministic hash of your documents:
src/tools-hash.ts
import { SerializationUtils } from 'vectoriadb';

const documents = [
  { id: 'tool1', text: 'Description 1', metadata: { /* ... */ } },
  { id: 'tool2', text: 'Description 2', metadata: { /* ... */ } },
];

// Hash is based on document IDs and text content
const hash = SerializationUtils.createToolsHash(documents);
console.log(hash); // e.g., "abc123..."
The tools hash should change whenever your documents change. Use SerializationUtils.createToolsHash() to generate it automatically.

​
Version Invalidation

Invalidate cache on deployments:
src/version-invalidation.ts
const db = new VectoriaDB({
  version: process.env.npm_package_version, // From package.json
  // or
  version: '1.2.3', // Manual version string
});

​
Manual Cache Control

​
Force Re-index

src/force-reindex.ts
// Clear storage and re-index
await db.clearStorage();
await db.addMany(documents);
await db.saveToStorage();

​
Check Cache Status

src/check-cache.ts
await db.initialize();

if (db.size() === 0) {
  console.log('Cache miss - re-indexing...');
  await db.addMany(documents);
  await db.saveToStorage();
} else {
  console.log('Cache hit - loaded from storage');
}

​
Warm-up Pattern

Common pattern for production deployments:
src/warmup.ts
export async function warmToolIndex(documents: ToolDocument[]) {
  const toolIndex = new VectoriaDB<ToolDocument>({
    storageAdapter: new FileStorageAdapter({
      cacheDir: './.cache/vectoriadb',
      namespace: 'tool-index',
    }),
    toolsHash: SerializationUtils.createToolsHash(documents),
    version: process.env.npm_package_version,
  });

  await toolIndex.initialize();

  // Only re-index if cache was invalidated
  if (toolIndex.size() === 0) {
    console.log('Cache miss - re-indexing...');
    await toolIndex.addMany(documents);
    await toolIndex.saveToStorage();
  } else {
    console.log('Cache hit - loaded from storage');
  }

  return toolIndex;
}

​
Debugging Cache Issues

src/debug-cache.ts
await db.initialize();

console.log({
  documentsLoaded: db.size(),
  expectedDocuments: documents.length,
  cacheHit: db.size() > 0,
});

if (db.size() !== documents.length) {
  console.log('Cache mismatch - possible reasons:');
  console.log('- toolsHash changed');
  console.log('- version changed');
  console.log('- modelName changed');
  console.log('- cache file corrupted');
}

​
Error Handling

src/cache-errors.ts
import { StorageError } from 'vectoriadb';

try {
  await db.initialize();
} catch (error) {
  if (error instanceof StorageError) {
    console.warn('Storage error, continuing without cache:', error.message);
    // Continue - will re-index
  }
}

Storage Overview

Storage fundamentals

File Adapter

File storage

Deployment

Production setup