Module 4: Vector Databases Engineering

Learning Objectives

• Understand ANN algorithms (HNSW, IVF) and their tradeoffs
• Deploy and operate Qdrant for production vector search
• Use pgvector for PostgreSQL-integrated vector search
• Design metadata filtering and multi-tenancy strategies

Why This Matters

The vector database is the engine of your RAG system. A bad choice means poor performance at scale, inability to filter by metadata (tenant, date, category), and operational headaches. This module teaches production vector database engineering, not just API calls.

Lesson Content

Vector databases store and search high-dimensional embeddings efficiently. The difference between a toy demo and a production system often comes down to the vector database: indexing strategy, filtering, multi-tenancy, and operational reliability.

ANN Algorithms: How Fast Search Works

Exact nearest neighbor search (comparing against every vector) is O(n) — too slow for millions of vectors. Approximate Nearest Neighbor (ANN) algorithms trade a tiny accuracy loss for dramatic speed gains.

• HNSW: Hierarchical Navigable Small World graph. The most popular. O(log n) search, 95-99% recall. Memory-intensive but fast.
• IVF: Inverted File Index. Clusters vectors, searches only relevant clusters. Less memory but lower recall.
• Flat: Exact search. Perfect recall but O(n). Use for small datasets only.

Qdrant: Production Vector Search

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

# Create collection with HNSW index
client.create_collection(
    collection_name="documents",
    vectors_config=models.VectorParams(size=384, distance=models.Distance.COSINE),
)

# Insert vectors with metadata
client.upsert(collection_name="documents", points=[
    models.PointStruct(id=1, vector=embedding, payload={"title": "Doc 1", "category": "engineering"}),
])

# Search with metadata filtering
results = client.search(
    collection_name="documents",
    query_vector=query_embedding,
    query_filter=models.Filter(must=[
        models.FieldCondition(key="category", match=models.MatchValue(value="engineering"))
    ]),
    limit=5,
)

pgvector: Vector Search in PostgreSQL

-- Enable extension
CREATE EXTENSION vector;

-- Create table with vector column
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding vector(384)
);

-- HNSW index for fast search
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

-- Search
SELECT id, content, embedding <=> query_vector AS distance
FROM documents ORDER BY distance LIMIT 5;

Common Mistakes

• Using ChromaDB in production (designed for prototyping, not operations)
• Not creating HNSW indexes (falls back to brute-force search)
• Storing vectors without metadata (cannot filter by category, tenant, date)
• Not monitoring collection size and search latency as data grows

Design Tradeoffs

Qdrant

Pros

• High performance
• Rich filtering
• Multi-tenant
• Open source

Cons

• Separate infrastructure
• Ops overhead

pgvector

Pros

• Reuses existing PostgreSQL
• SQL interface
• No new infrastructure

Cons

• Lower performance at scale
• Limited filtering
• Not designed for billions of vectors

Key Terms

ANN

Approximate Nearest Neighbor — fast but slightly imprecise vector search

HNSW

Hierarchical Navigable Small World — graph-based ANN algorithm

Qdrant

Open-source vector database optimized for production workloads

pgvector

PostgreSQL extension for vector similarity search

Hands-On Labs

1. Setup Qdrant and Build Semantic Search

   Deploy Qdrant and build a search API.

   35 min - Intermediate

   • Deploy Qdrant with Docker
   • Create a collection with HNSW index
   • Ingest 1000 documents with metadata
   • Build a FastAPI search endpoint with filtering

   View lab files on GitHub

2. Build Search APIs with pgvector

   Use PostgreSQL for vector search.

   30 min - Intermediate

   • Setup PostgreSQL with pgvector extension
   • Create table with vector column and HNSW index
   • Insert embeddings and query with SQL
   • Compare performance with Qdrant

   View lab files on GitHub

Key Takeaways

• HNSW is the dominant ANN algorithm — O(log n) with 95-99% recall
• Qdrant is production-grade: fast, filterable, multi-tenant, open source
• pgvector works if you already use PostgreSQL and need moderate scale
• Metadata filtering is critical — vector similarity alone is not enough
• Choose your vector DB based on scale, ops model, and existing infrastructure