Quickstart

Build your first semantic search in minutes

Build a semantic search index in just a few lines of code.

Basic Example

src/index.ts

import { VectoriaDB, DocumentMetadata } from 'vectoriadb';

// Define your metadata shape
interface ToolDocument extends DocumentMetadata {
  toolName: string;
  owner: string;
  tags: string[];
  risk: 'safe' | 'destructive';
}

// Create the database
const toolIndex = new VectoriaDB<ToolDocument>({
  cacheDir: './.cache/transformers',
  defaultSimilarityThreshold: 0.4,
});

// Initialize (downloads model on first run)
await toolIndex.initialize();

// Add a document
await toolIndex.add('users:list', 'List all users with pagination', {
  id: 'users:list',
  toolName: 'list',
  owner: 'users',
  tags: ['read'],
  risk: 'safe',
});

// Search
const results = await toolIndex.search('find users');
console.log(results[0].metadata.toolName); // 'list'

You now have a working semantic search index. initialize() must run before add, search, or update. Calling it twice is safe because VectoriaDB short-circuits if it is already ready.

Step-by-Step Breakdown

1. Define Metadata Interface

src/types.ts

import { DocumentMetadata } from 'vectoriadb';

interface ToolDocument extends DocumentMetadata {
  toolName: string;
  owner: string;
  tags: string[];
  risk: 'safe' | 'destructive';
}

This ensures type safety for all documents in your index.

2. Create and Initialize

src/setup.ts

const db = new VectoriaDB<ToolDocument>({
  cacheDir: './.cache/transformers',
  defaultSimilarityThreshold: 0.4,
});

await db.initialize();

3. Add Documents

src/add.ts

// Single document
await db.add('users:list', 'List all users with pagination', {
  id: 'users:list',
  toolName: 'list',
  owner: 'users',
  tags: ['read'],
  risk: 'safe',
});

// Batch add
await db.addMany([
  { id: 'users:create', text: 'Create a new user', metadata: { /* ... */ } },
  { id: 'users:delete', text: 'Delete a user', metadata: { /* ... */ } },
]);

4. Search

src/search.ts

const results = await db.search('create account', {
  topK: 5,
  threshold: 0.4,
  filter: (m) => m.risk === 'safe',
});

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

Configuration Options

Option	Type	Default	Description
modelName	string	'Xenova/all-MiniLM-L6-v2'	Embedding model to use
cacheDir	string	'./.cache/transformers'	Model cache directory
dimensions	number	Auto-detected	Vector dimensions
defaultSimilarityThreshold	number	0.3	Minimum similarity score
defaultTopK	number	10	Default results limit
useHNSW	boolean	false	Enable HNSW index
maxDocuments	number	100000	Max documents (DoS protection)
maxDocumentSize	number	1000000	Max document size in chars
maxBatchSize	number	1000	Max batch operation size
verboseErrors	boolean	true	Enable detailed errors

Next Steps

Adding Documents

Learn about indexing options

Search

Master search queries

Persistence

Persist embeddings between restarts

HNSW Scaling

Scale to large datasets