{
    "slug": "vector_database",
    "term": "Vector Database",
    "category": "ai_ml",
    "difficulty": "intermediate",
    "short": "A database optimised for storing and querying high-dimensional vector embeddings, enabling similarity search — finding items semantically close to a query rather than exact-match lookups.",
    "long": "Vector databases store embeddings — fixed-length arrays of floating-point numbers that encode semantic meaning — and provide approximate nearest neighbour (ANN) search across millions of vectors in milliseconds. Unlike SQL databases that match exact values, a vector database returns the N most semantically similar vectors to a query embedding using distance metrics like cosine similarity or Euclidean distance. Common implementations include Pinecone (managed cloud), pgvector (PostgreSQL extension), Qdrant, Weaviate, and Chroma. In PHP applications, vector databases are typically accessed via HTTP APIs — you embed text locally or via an API, then store or query the resulting vector.",
    "aliases": [
        "vector store",
        "embedding database",
        "ANN database",
        "similarity search database"
    ],
    "tags": [
        "vector-database",
        "embeddings",
        "similarity-search",
        "ai",
        "rag"
    ],
    "misconception": "A vector database replaces your regular database for AI features. Vector databases complement SQL/NoSQL databases — they handle similarity search while relational databases handle structured queries, transactions, and joins. Most production systems use both: metadata filtering in SQL, semantic ranking in the vector store.",
    "why_it_matters": "Vector databases make semantic search possible — finding documents by meaning rather than keyword. Without one, building a RAG pipeline requires loading all documents into memory and computing distances in PHP, which is slow and does not scale. With pgvector you can add vector search to an existing PostgreSQL database with one extension, making it the lowest-friction entry point for most PHP applications.",
    "common_mistakes": [
        "Using Euclidean distance when cosine similarity is appropriate — for text embeddings, cosine similarity is almost always correct because it measures directional similarity regardless of magnitude.",
        "Not normalising vectors before storage when using dot product similarity — unnormalised vectors produce incorrect rankings.",
        "Storing the full document text in the vector database — keep metadata in your relational database and store only the chunk text and embedding in the vector store.",
        "Choosing a managed cloud vector database before validating the use case — pgvector on your existing PostgreSQL instance handles millions of vectors adequately for most PHP applications."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "embeddings",
        "rag_retrieval",
        "semantic_search",
        "tokenization_llm"
    ],
    "prerequisites": [],
    "refs": [
        "https://github.com/pgvector/pgvector"
    ],
    "bad_code": "// ❌ Storing raw text and doing LIKE search instead of vector similarity\nfunction findSimilar(string $query, PDO $db): array {\n    $stmt = $db->prepare(\n        \"SELECT * FROM documents WHERE content LIKE :q ORDER BY id LIMIT 10\"\n    );\n    $stmt->execute([':q' => \"%$query%\"]);\n    return $stmt->fetchAll();\n    // Zero semantic understanding — \"car\" won't match \"automobile\" or \"vehicle\"\n}",
    "good_code": "// ✅ pgvector — vector similarity search on existing PostgreSQL\n// Setup (once):\n// CREATE EXTENSION vector;\n// ALTER TABLE documents ADD COLUMN embedding vector(1536);\n// CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops);\n\n// Store embedding at ingest\n$embedding = $embedder->embed($document['content']); // 1536-dim float array\n$stmt = $pdo->prepare(\n    'INSERT INTO documents (content, embedding) VALUES (:content, :embedding)'\n);\n$stmt->execute([\n    ':content'   => $document['content'],\n    ':embedding' => '[' . implode(',', $embedding) . ']', // pgvector format\n]);\n\n// Similarity search — cosine distance, top 10 results\n$queryEmbedding = $embedder->embed($userQuery);\n$stmt = $pdo->prepare(\"\n    SELECT content, 1 - (embedding <=> :q::vector) AS similarity\n    FROM documents\n    ORDER BY embedding <=> :q::vector\n    LIMIT 10\n\");\n$stmt->execute([':q' => '[' . implode(',', $queryEmbedding) . ']']);",
    "quick_fix": "Start with pgvector on existing PostgreSQL: CREATE EXTENSION vector; then add a vector(1536) column — no new infrastructure required",
    "severity": "info",
    "effort": "medium",
    "created": "2026-03-23",
    "updated": "2026-03-23",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/vector_database",
        "html_url": "https://codeclaritylab.com/glossary/vector_database",
        "json_url": "https://codeclaritylab.com/glossary/vector_database.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Vector Database](https://codeclaritylab.com/glossary/vector_database) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/vector_database"
            }
        }
    }
}