Part 4: Building Vector Search with TypeScript

← Part 3: pgvector Setup | Part 5: Advanced Queries →

The Knowledge Base That Nobody Used

I built a customer support knowledge base. It had everything:

• 500+ carefully written articles

• Perfect categorization

• Beautiful UI

• Traditional search

Usage: 12% of tickets. Support agents ignored it and asked engineers directly.

Why? The search was useless:

• Query: "customer can't login" → 0 results

• (Article title: "Authentication Troubleshooting Guide")

• Query: "payment failed" → Wrong articles

• (Returns billing setup, not payment errors)

I rebuilt it with semantic search. Same knowledge base, vector-powered search.

Usage: 12% → 78%. Support ticket resolution time: 4.2 hours → 1.3 hours. Engineers finally got time to code instead of answering the same questions.

This article shows you exactly how I built it with TypeScript and pgvector.

Project Setup

Initialize TypeScript Project

mkdir vector-search-api
cd vector-search-api

# Initialize npm project
npm init -y

# Install dependencies
npm install \
  @prisma/client \
  prisma \
  openai \
  express \
  dotenv \
  zod

# Install dev dependencies
npm install -D \
  @types/node \
  @types/express \
  typescript \
  tsx \
  nodemon

TypeScript Configuration

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Environment Variables

# .env
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/vectordb?schema=public"
OPENAI_API_KEY="sk-..."
PORT=3000

Package Scripts

// package.json
{
  "scripts": {
    "dev": "nodemon --exec tsx src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "db:generate": "prisma generate",
    "db:migrate": "prisma migrate dev",
    "db:studio": "prisma studio"
  }
}

Prisma Schema Setup

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
  previewFeatures = ["postgresqlExtensions"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  extensions = [vector]
}

model Article {
  id          Int      @id @default(autoincrement())
  title       String
  content     String
  category    String
  tags        String[]
  author      String
  url         String
  
  // Vector embedding
  embedding   Unsupported("vector(1536)")?
  
  createdAt   DateTime @default(now()) @map("created_at")
  updatedAt   DateTime @updatedAt @map("updated_at")
  
  @@index([category])
  @@index([embedding], type: Hnsw, name: "article_embedding_idx")
  @@map("articles")
}

model SearchLog {
  id        Int      @id @default(autoincrement())
  query     String
  resultsCount Int   @map("results_count")
  topResult String? @map("top_result")
  userId    String? @map("user_id")
  timestamp DateTime @default(now())
  
  @@index([timestamp])
  @@map("search_logs")
}

# Generate Prisma client
npx prisma generate

# Create and run migration
npx prisma migrate dev --name init

Embedding Service

// src/services/embedding.service.ts
import { OpenAI } from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

export class EmbeddingService {
  private static readonly MODEL = 'text-embedding-3-small';
  private static readonly BATCH_SIZE = 2048;
  
  /**
   * Generate embedding for a single text
   */
  static async getEmbedding(text: string): Promise<number[]> {
    const cleaned = this.preprocessText(text);
    
    if (!cleaned || cleaned.length < 3) {
      throw new Error('Text too short for embedding');
    }
    
    try {
      const response = await openai.embeddings.create({
        model: this.MODEL,
        input: cleaned,
      });
      
      return response.data[0].embedding;
    } catch (error: any) {
      throw new Error(`Embedding generation failed: ${error.message}`);
    }
  }
  
  /**
   * Generate embeddings for multiple texts (batched)
   */
  static async getBatchEmbeddings(texts: string[]): Promise<number[][]> {
    const allEmbeddings: number[][] = [];
    
    for (let i = 0; i < texts.length; i += this.BATCH_SIZE) {
      const batch = texts.slice(i, i + this.BATCH_SIZE);
      const cleaned = batch.map(t => this.preprocessText(t));
      
      try {
        const response = await openai.embeddings.create({
          model: this.MODEL,
          input: cleaned,
        });
        
        const embeddings = response.data
          .sort((a, b) => a.index - b.index)
          .map(item => item.embedding);
        
        allEmbeddings.push(...embeddings);
        
        console.log(`Embedded ${i + batch.length}/${texts.length} texts`);
      } catch (error: any) {
        throw new Error(`Batch embedding failed: ${error.message}`);
      }
    }
    
    return allEmbeddings;
  }
  
  /**
   * Preprocess text before embedding
   */
  private static preprocessText(text: string): string {
    return text
      .replace(/\s+/g, ' ')           // Normalize whitespace
      .replace(/[^\w\s.-]/g, '')      // Remove special chars
      .trim()
      .slice(0, 8000);                // OpenAI token limit
  }
  
  /**
   * Generate embedding with retry logic
   */
  static async getEmbeddingWithRetry(
    text: string,
    maxRetries: number = 3
  ): Promise<number[]> {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      try {
        return await this.getEmbedding(text);
      } catch (error) {
        if (attempt === maxRetries - 1) throw error;
        
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        console.log(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
    
    throw new Error('Max retries exceeded');
  }
}

Vector Search Service

// src/services/search.service.ts
import { PrismaClient } from '@prisma/client';
import { EmbeddingService } from './embedding.service';

const prisma = new PrismaClient();

export interface SearchResult {
  id: number;
  title: string;
  content: string;
  category: string;
  url: string;
  similarity: number;
}

export interface SearchOptions {
  limit?: number;
  minSimilarity?: number;
  category?: string;
  tags?: string[];
}

export class SearchService {
  /**
   * Semantic search using vector similarity
   */
  static async searchArticles(
    query: string,
    options: SearchOptions = {}
  ): Promise<SearchResult[]> {
    const {
      limit = 10,
      minSimilarity = 0.7,
      category,
      tags,
    } = options;
    
    // Generate query embedding
    const queryEmbedding = await EmbeddingService.getEmbedding(query);
    
    // Build WHERE clause for filters
    const categoryFilter = category ? `AND category = '${category}'` : '';
    const tagsFilter = tags && tags.length > 0
      ? `AND tags && ARRAY[${tags.map(t => `'${t}'`).join(',')}]::text[]`
      : '';
    
    // Execute vector similarity search
    const results = await prisma.$queryRaw<SearchResult[]>`
      SELECT 
        id,
        title,
        content,
        category,
        url,
        1 - (embedding <=> ${queryEmbedding}::vector) as similarity
      FROM articles
      WHERE embedding IS NOT NULL
        AND 1 - (embedding <=> ${queryEmbedding}::vector) > ${minSimilarity}
        ${categoryFilter}
        ${tagsFilter}
      ORDER BY embedding <=> ${queryEmbedding}::vector
      LIMIT ${limit}
    `;
    
    // Log search
    await this.logSearch(query, results);
    
    return results;
  }
  
  /**
   * Hybrid search: combine vector + keyword search
   */
  static async hybridSearch(
    query: string,
    options: SearchOptions = {}
  ): Promise<SearchResult[]> {
    const { limit = 10, minSimilarity = 0.6 } = options;
    
    const queryEmbedding = await EmbeddingService.getEmbedding(query);
    
    // Combine vector similarity with full-text search
    const results = await prisma.$queryRaw<SearchResult[]>`
      WITH vector_search AS (
        SELECT 
          id,
          title,
          content,
          category,
          url,
          1 - (embedding <=> ${queryEmbedding}::vector) as similarity
        FROM articles
        WHERE embedding IS NOT NULL
        ORDER BY embedding <=> ${queryEmbedding}::vector
        LIMIT 50
      ),
      keyword_search AS (
        SELECT 
          id,
          title,
          content,
          category,
          url,
          ts_rank(to_tsvector('english', title || ' ' || content), plainto_tsquery('english', ${query})) as rank
        FROM articles
        WHERE to_tsvector('english', title || ' ' || content) @@ plainto_tsquery('english', ${query})
        LIMIT 50
      )
      SELECT DISTINCT
        COALESCE(v.id, k.id) as id,
        COALESCE(v.title, k.title) as title,
        COALESCE(v.content, k.content) as content,
        COALESCE(v.category, k.category) as category,
        COALESCE(v.url, k.url) as url,
        COALESCE(v.similarity, 0) + COALESCE(k.rank, 0) * 0.3 as similarity
      FROM vector_search v
      FULL OUTER JOIN keyword_search k ON v.id = k.id
      WHERE COALESCE(v.similarity, 0) > ${minSimilarity} OR COALESCE(k.rank, 0) > 0
      ORDER BY similarity DESC
      LIMIT ${limit}
    `;
    
    await this.logSearch(query, results);
    
    return results;
  }
  
  /**
   * Find similar articles to a given article
   */
  static async findSimilar(
    articleId: number,
    limit: number = 5
  ): Promise<SearchResult[]> {
    const article = await prisma.article.findUnique({
      where: { id: articleId },
    });
    
    if (!article) {
      throw new Error('Article not found');
    }
    
    const results = await prisma.$queryRaw<SearchResult[]>`
      SELECT 
        id,
        title,
        content,
        category,
        url,
        1 - (embedding <=> (SELECT embedding FROM articles WHERE id = ${articleId})::vector) as similarity
      FROM articles
      WHERE id != ${articleId}
        AND embedding IS NOT NULL
      ORDER BY embedding <=> (SELECT embedding FROM articles WHERE id = ${articleId})::vector
      LIMIT ${limit}
    `;
    
    return results;
  }
  
  /**
   * Log search for analytics
   */
  private static async logSearch(query: string, results: SearchResult[]) {
    try {
      await prisma.searchLog.create({
        data: {
          query,
          resultsCount: results.length,
          topResult: results[0]?.title || null,
        },
      });
    } catch (error) {
      console.error('Failed to log search:', error);
    }
  }
}

Data Ingestion Service

// src/services/ingestion.service.ts
import { PrismaClient } from '@prisma/client';
import { EmbeddingService } from './embedding.service';

const prisma = new PrismaClient();

export interface ArticleInput {
  title: string;
  content: string;
  category: string;
  tags?: string[];
  author: string;
  url: string;
}

export class IngestionService {
  /**
   * Add single article with embedding
   */
  static async addArticle(input: ArticleInput): Promise<number> {
    const text = `${input.title}\n${input.content}`;
    const embedding = await EmbeddingService.getEmbedding(text);
    
    const article = await prisma.$executeRaw`
      INSERT INTO articles (title, content, category, tags, author, url, embedding)
      VALUES (
        ${input.title},
        ${input.content},
        ${input.category},
        ${input.tags || []}::text[],
        ${input.author},
        ${input.url},
        ${embedding}::vector
      )
      RETURNING id
    `;
    
    return article;
  }
  
  /**
   * Bulk import articles
   */
  static async bulkImport(articles: ArticleInput[]): Promise<void> {
    console.log(`Importing ${articles.length} articles...`);
    
    // Generate all embeddings (batched)
    const texts = articles.map(a => `${a.title}\n${a.content}`);
    const embeddings = await EmbeddingService.getBatchEmbeddings(texts);
    
    // Insert all articles
    for (let i = 0; i < articles.length; i++) {
      const article = articles[i];
      const embedding = embeddings[i];
      
      await prisma.$executeRaw`
        INSERT INTO articles (title, content, category, tags, author, url, embedding)
        VALUES (
          ${article.title},
          ${article.content},
          ${article.category},
          ${article.tags || []}::text[],
          ${article.author},
          ${article.url},
          ${embedding}::vector
        )
        ON CONFLICT (url) DO UPDATE SET
          content = EXCLUDED.content,
          embedding = EXCLUDED.embedding,
          updated_at = NOW()
      `;
      
      if ((i + 1) % 10 === 0) {
        console.log(`Imported ${i + 1}/${articles.length}`);
      }
    }
    
    console.log(`Successfully imported ${articles.length} articles`);
  }
  
  /**
   * Update article embedding (when content changes)
   */
  static async updateEmbedding(articleId: number): Promise<void> {
    const article = await prisma.article.findUnique({
      where: { id: articleId },
    });
    
    if (!article) {
      throw new Error('Article not found');
    }
    
    const text = `${article.title}\n${article.content}`;
    const embedding = await EmbeddingService.getEmbedding(text);
    
    await prisma.$executeRaw`
      UPDATE articles
      SET embedding = ${embedding}::vector, updated_at = NOW()
      WHERE id = ${articleId}
    `;
  }
  
  /**
   * Re-embed all articles (e.g., when changing embedding model)
   */
  static async reembedAll(): Promise<void> {
    const articles = await prisma.article.findMany({
      select: { id: true, title: true, content: true },
    });
    
    console.log(`Re-embedding ${articles.length} articles...`);
    
    const texts = articles.map(a => `${a.title}\n${a.content}`);
    const embeddings = await EmbeddingService.getBatchEmbeddings(texts);
    
    for (let i = 0; i < articles.length; i++) {
      await prisma.$executeRaw`
        UPDATE articles
        SET embedding = ${embeddings[i]}::vector
        WHERE id = ${articles[i].id}
      `;
      
      if ((i + 1) % 50 === 0) {
        console.log(`Re-embedded ${i + 1}/${articles.length}`);
      }
    }
    
    console.log('Re-embedding complete!');
  }
}

REST API Endpoints

// src/index.ts
import express, { Request, Response } from 'express';
import { z } from 'zod';
import { SearchService } from './services/search.service';
import { IngestionService } from './services/ingestion.service';
import dotenv from 'dotenv';

dotenv.config();

const app = express();
app.use(express.json());

// Validation schemas
const SearchSchema = z.object({
  query: z.string().min(1).max(500),
  limit: z.number().min(1).max(50).optional(),
  minSimilarity: z.number().min(0).max(1).optional(),
  category: z.string().optional(),
  tags: z.array(z.string()).optional(),
});

const ArticleSchema = z.object({
  title: z.string().min(1).max(255),
  content: z.string().min(10),
  category: z.string(),
  tags: z.array(z.string()).optional(),
  author: z.string(),
  url: z.string().url(),
});

/**
 * POST /api/search
 * Semantic search for articles
 */
app.post('/api/search', async (req: Request, res: Response) => {
  try {
    const input = SearchSchema.parse(req.body);
    const results = await SearchService.searchArticles(input.query, {
      limit: input.limit,
      minSimilarity: input.minSimilarity,
      category: input.category,
      tags: input.tags,
    });
    
    res.json({
      success: true,
      query: input.query,
      count: results.length,
      results,
    });
  } catch (error: any) {
    res.status(400).json({
      success: false,
      error: error.message,
    });
  }
});

/**
 * POST /api/search/hybrid
 * Hybrid search (vector + keyword)
 */
app.post('/api/search/hybrid', async (req: Request, res: Response) => {
  try {
    const input = SearchSchema.parse(req.body);
    const results = await SearchService.hybridSearch(input.query, {
      limit: input.limit,
      minSimilarity: input.minSimilarity,
    });
    
    res.json({
      success: true,
      query: input.query,
      count: results.length,
      results,
    });
  } catch (error: any) {
    res.status(400).json({
      success: false,
      error: error.message,
    });
  }
});

/**
 * GET /api/articles/:id/similar
 * Find similar articles
 */
app.get('/api/articles/:id/similar', async (req: Request, res: Response) => {
  try {
    const id = parseInt(req.params.id);
    const limit = parseInt(req.query.limit as string) || 5;
    
    const results = await SearchService.findSimilar(id, limit);
    
    res.json({
      success: true,
      count: results.length,
      results,
    });
  } catch (error: any) {
    res.status(404).json({
      success: false,
      error: error.message,
    });
  }
});

/**
 * POST /api/articles
 * Add new article
 */
app.post('/api/articles', async (req: Request, res: Response) => {
  try {
    const input = ArticleSchema.parse(req.body);
    const id = await IngestionService.addArticle(input);
    
    res.status(201).json({
      success: true,
      id,
    });
  } catch (error: any) {
    res.status(400).json({
      success: false,
      error: error.message,
    });
  }
});

/**
 * POST /api/articles/bulk
 * Bulk import articles
 */
app.post('/api/articles/bulk', async (req: Request, res: Response) => {
  try {
    const articles = z.array(ArticleSchema).parse(req.body);
    await IngestionService.bulkImport(articles);
    
    res.json({
      success: true,
      count: articles.length,
    });
  } catch (error: any) {
    res.status(400).json({
      success: false,
      error: error.message,
    });
  }
});

/**
 * Health check
 */
app.get('/health', (req: Request, res: Response) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`🚀 Vector search API running on http://localhost:${PORT}`);
});

Testing the API

# Start server
npm run dev

Search Articles

curl -X POST http://localhost:3000/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to troubleshoot authentication errors",
    "limit": 5,
    "minSimilarity": 0.7
  }'

Hybrid Search

curl -X POST http://localhost:3000/api/search/hybrid \
  -H "Content-Type: application/json" \
  -d '{
    "query": "payment processing issues",
    "limit": 10
  }'

Add Article

curl -X POST http://localhost:3000/api/articles \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Debugging OAuth 2.0 Issues",
    "content": "Common OAuth 2.0 problems and solutions...",
    "category": "Authentication",
    "tags": ["oauth", "security", "debugging"],
    "author": "Engineering Team",
    "url": "https://docs.example.com/oauth-debugging"
  }'

Find Similar Articles

curl http://localhost:3000/api/articles/42/similar?limit=5

What's Next

In this article, you learned:

• ✅ Complete TypeScript project setup with Prisma and pgvector

• ✅ Embedding service with batching and retry logic

• ✅ Vector search service with filtering

• ✅ Hybrid search combining vectors and keywords

• ✅ Data ingestion with bulk import

• ✅ Production-ready REST API

Next: Advanced queries, filtering strategies, and performance optimization techniques.

---

← Part 3: pgvector Setup | Part 5: Advanced Queries →