A Beginner's Guide to Vector Database Principles

Deep Dive: Stage 1 — Deep Dive: ANN Index Structures

• ANN (Approximate Nearest Neighbor) indexes make vector search fast at scale by trading a tiny amount of recall for dramatically lower query latency: Pinecone and Weaviate default to HNSW.
• Chroma uses HNSW via hnswlib .
• pgvector supports both HNSW and IVF.
• 🔬 Internals Vector databases index high-dimensional embeddings using Approximate Nearest Neighbor (ANN) algorithms.

Observable outcome: 🔬 Internals Vector databases index high-dimensional embeddings using Approximate Nearest Neighbor (ANN) algorithms.

Deep Dive: Stage 2 — Real-World Application: Semantic Search for a Support Knowledge Base

• Scenario: Your support team has 50,000 help articles.
• Customers type questions in natural language and expect the right article — even when wording does not match any article title.
• Step 1 — Index: Chunk each article into 400-token segments.
• Embed each chunk with text-embedding-ada-002 .

Observable outcome: Embed each chunk with text-embedding-ada-002 .

Deep Dive: Stage 3 — Your First Semantic Search with Chroma in Python

• Chroma is the fastest way to try a vector database locally — no signup, no cluster, one pip install .
• What happens under the hood: Chroma embeds the documents and query using all-MiniLM-L6-v2 , stores them in an HNSW index, and returns the nearest vectors by cosine distance.
• To go to production, swap chromadb.Client() for Pinecone or Weaviate and use text-embedding-ada-002 .

import chromadb

client = chromadb.Client()
collection = client.create_collection("support-docs")

# Index two documents (Chroma embeds them with its built-in model)
collection.add(
    documents=[
        "How to reset your account password via email link",
        "Steps to recover access when two-factor authentication is lost",
    ],
    ids=["doc-1", "doc-2"],
)

# Query with a natural-language question
results = collection.query(
    query_texts=["I can't log in, forgot my credentials"],
    n_results=2,
)

for doc, dist in zip(results["documents"][0], results["distances"][0]):
    print(f"[score {1 - dist:.3f}] {doc[:60]}...")

Observable outcome: To go to production, swap chromadb.Client() for Pinecone or Weaviate and use text-embedding-ada-002 .

Deep Dive: Stage 4 — ChromaDB, Pinecone, Weaviate, and pgvector: Picking the Right Vector Store

• ChromaDB is an open-source embedded vector database built for local development and rapid prototyping — zero infrastructure required.
• Pinecone is a managed cloud vector database with serverless scaling.
• Weaviate is an open-source vector search engine with native hybrid (BM25 + vector) search.
• pgvector is a PostgreSQL extension that adds vector storage and ANN search without leaving your existing relational database.

# --- ChromaDB + sentence-transformers (local prototype, no signup needed) ---
# pip install chromadb sentence-transformers
import chromadb
from sentence_transformers import SentenceTransformer

encoder    = SentenceTransformer("all-MiniLM-L6-v2")
client     = chromadb.PersistentClient(path="./chroma_store")
collection = client.get_or_create_collection("knowledge-base")

docs = [
    "Password reset sends a one-time link to your registered email address.",
    "Two-factor authentication can be disabled from your account security settings.",
]
embeddings = encoder.encode(docs).tolist()
collection.upsert(documents=docs, embeddings=embeddings, ids=["doc-1", "doc-2"])

query_vec = encoder.encode(["I forgot my login credentials"]).tolist()
results   = collection.query(query_embeddings=query_vec, n_results=2)
for doc, dist in zip(results["documents"][0], results["distances"][0]):
    print(f"[similarity {1 - dist:.3f}] {doc[:80]}")

# --- pgvector (stays inside Postgres — zero new infrastructure) ---
# pip install psycopg2-binary pgvector
import psycopg2
from pgvector.psycopg2 import register_vector

conn = psycopg2.connect("dbname=support user=postgres")
register_vector(conn)
with conn.cursor() as cur:
    cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
    cur.execute(
        "CREATE TABLE IF NOT EXISTS docs "
        "(id serial PRIMARY KEY, content text, embedding vector(384))"
    )
    vec = encoder.encode("Password reset guide").tolist()
    cur.execute("INSERT INTO docs (content, embedding) VALUES (%s, %s)",
                ("Password reset guide", vec))
    # Cosine similarity search: <=> is the pgvector cosine distance operator
    query_vec = encoder.encode("forgot credentials").tolist()
    cur.execute(
        "SELECT content, 1 - (embedding <=> %s) AS similarity "
        "FROM docs ORDER BY embedding <=> %s LIMIT 5",
        (query_vec, query_vec)
    )
    for row in cur.fetchall():
        print(f"[similarity {row[1]:.3f}] {row[0]}")
conn.commit()

Observable outcome: pgvector is a PostgreSQL extension that adds vector storage and ANN search without leaving your existing relational database.

Deep Dive: Stage 5 — Three Things That Catch Every Vector Database Beginner

• You cannot search across mixed embedding models.
• If you index with text-embedding-ada-002 and later query with bge-base-en , the vectors live in incompatible geometric spaces — ANN search returns garbage.
• Use the same model for both indexing and querying, and track which model version was used for each document batch.
• Filtering happens in metadata, not in the vector space.

Observable outcome: Filtering happens in metadata, not in the vector space.