Vector Database

AI / ML Intermediate

debt(d8/e6/b7/t7)

d8 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'silent in production until users hit it' (d9), backing off slightly to d8. No detection tools are listed in detection_hints.tools. The canonical misuse — treating the vector database as a full replacement for relational databases, or choosing wrong distance metrics — produces incorrect semantic rankings or missing transactional data that only surfaces when users notice irrelevant results or data inconsistencies in production. No linter or static analysis catches architectural misuse of this kind.

e6 Effort Remediation debt — work required to fix once spotted

Closest to 'touches multiple files / significant refactor in one component' (e5), scoring e6. The quick_fix (pgvector extension) is easy for greenfield adoption, but correcting misuse — such as having already migrated structured data into a vector store, chosen the wrong distance metric affecting all stored vectors, or built a pipeline around a cloud vector DB before validating the use case — requires re-architecting data storage, re-embedding content, and potentially migrating infrastructure, spanning multiple components and files.

b7 Burden Structural debt — long-term weight of choosing wrong

Closest to 'strong gravitational pull' (d7), scoring b7. The choice of vector database architecture shapes the entire RAG pipeline and similarity-search strategy. Every component that queries for semantic similarity, every chunk storage decision, and every embedding pipeline is shaped by this choice. Switching vector backends (e.g., from a managed cloud store to pgvector) requires changes across ingestion, retrieval, and query layers — a cross-cutting commitment.

t7 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception field is explicit: developers assume a vector database replaces their regular database for AI features, mirroring how they might adopt a new specialised database (e.g., Redis for caching) by offloading all relevant data. In reality, vector databases are complementary, not substitutes. Additionally, the distance-metric trap (Euclidean vs. cosine) contradicts intuitions from traditional numeric distance calculations, producing silently wrong rankings.

About DEBT scoring → scored by claude-sonnet-4-6 · 2026-05-11 · reviewed by human

Also Known As

vector store embedding database ANN database similarity search database

TL;DR

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.

Explanation

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.

Common 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.

Code Examples

✗ Vulnerable

// ❌ Storing raw text and doing LIKE search instead of vector similarity
function findSimilar(string $query, PDO $db): array {
    $stmt = $db->prepare(
        "SELECT * FROM documents WHERE content LIKE :q ORDER BY id LIMIT 10"
    );
    $stmt->execute([':q' => "%$query%"]);
    return $stmt->fetchAll();
    // Zero semantic understanding — "car" won't match "automobile" or "vehicle"
}

✓ Fixed

// ✅ pgvector — vector similarity search on existing PostgreSQL
// Setup (once):
// CREATE EXTENSION vector;
// ALTER TABLE documents ADD COLUMN embedding vector(1536);
// CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops);

// Store embedding at ingest
$embedding = $embedder->embed($document['content']); // 1536-dim float array
$stmt = $pdo->prepare(
    'INSERT INTO documents (content, embedding) VALUES (:content, :embedding)'
);
$stmt->execute([
    ':content'   => $document['content'],
    ':embedding' => '[' . implode(',', $embedding) . ']', // pgvector format
]);

// Similarity search — cosine distance, top 10 results
$queryEmbedding = $embedder->embed($userQuery);
$stmt = $pdo->prepare("
    SELECT content, 1 - (embedding <=> :q::vector) AS similarity
    FROM documents
    ORDER BY embedding <=> :q::vector
    LIMIT 10
");
$stmt->execute([':q' => '[' . implode(',', $queryEmbedding) . ']']);

References

https://github.com/pgvector/pgvector