Skip to main content
Learn how to perform semantic searches with natural language queries.
src/basic-search.ts
const results = await toolIndex.search('reset a billing password');

for (const result of results) {
  console.log(`${result.metadata.toolName} (${result.score.toFixed(2)})`);
}

​
Search Options

src/search-options.ts
const matches = await toolIndex.search('reset a billing password', {
  topK: 5,                    // Maximum results (default: 10)
  threshold: 0.45,            // Minimum similarity (default: 0.3)
  filter: (metadata) =>       // Metadata filter function
    metadata.owner === 'billing' &&
    !metadata.tags.includes('deprecated'),
  includeVector: false,       // Include raw vectors in results
});

​
Options Reference

OptionTypeDefaultDescription
topKnumber10Maximum results to return
thresholdnumber0.3Minimum similarity score (0-1)
filterfunction-Filter function for metadata
includeVectorbooleanfalseInclude raw vectors in results

​
Search Results

Each result contains:
src/types/search-result.ts
interface SearchResult<T extends DocumentMetadata> {
  id: string;           // Document ID
  score: number;        // Similarity score (0-1)
  metadata: T;          // Document metadata
  text: string;         // Original document text
  vector?: number[];    // Embedding vector (if includeVector: true)
}

​
Understanding Scores

Scores range from 0 to 1:
  • 0.8-1.0: Very high similarity (nearly identical meaning)
  • 0.6-0.8: High similarity (strongly related)
  • 0.4-0.6: Moderate similarity (related concepts)
  • 0.2-0.4: Low similarity (loosely related)
  • 0.0-0.2: Very low similarity (probably unrelated)
src/interpret-scores.ts
const results = await db.search('create user account');

for (const result of results) {
  const confidence = result.score >= 0.6 ? 'High'
    : result.score >= 0.4 ? 'Medium'
    : 'Low';

  console.log(`${result.id}: ${result.score.toFixed(2)} (${confidence})`);
}

​
Error Handling

src/error-handling.ts
import { QueryValidationError, VectoriaNotInitializedError } from 'vectoriadb';

try {
  const results = await toolIndex.search(query, { topK: -1 });
} catch (error) {
  if (error instanceof QueryValidationError) {
    console.error('Invalid search parameters:', error.message);
  } else if (error instanceof VectoriaNotInitializedError) {
    console.error('Database not initialized');
    await toolIndex.initialize();
  }
}

​
Empty Results

Common reasons for empty results:
  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-empty.ts
// Debug: search without filters and low threshold
const results = await db.search(query, {
  threshold: 0.1,
  topK: 20,
  // No filter
});
console.log('Found:', results.length);

Filtering

Filter search results

Thresholds

Tune similarity thresholds

Performance

Optimize search performance