pgvector: English for PostgreSQL AI Engineers

The pgvector extension brings vector similarity search directly into PostgreSQL, allowing teams to build AI-powered features without adding a separate specialised database to their stack. It has become enormously popular because it lets engineers store embeddings alongside their existing relational data, join across tables, and leverage PostgreSQL’s mature ecosystem of tooling, backups, and access controls. To work effectively with pgvector in an English-speaking team, you need to understand the specific vocabulary that appears in pull request comments, architecture proposals, and the official documentation.

Key Vocabulary

Vector Column — A column in a PostgreSQL table with the type vector(n), where n is the number of dimensions. Just like an integer or text column, a vector column stores one value per row, but that value is an array of floating-point numbers representing an embedding. “We added a vector(1536) column called embedding to the articles table to store OpenAI embeddings alongside the original text.”

Embedding Dimension — The number of elements in a vector, determined by the model that produced it. Different models output different dimensions — for example, text-embedding-3-small outputs 1536 dimensions by default. The dimension must be declared when creating a vector column and cannot be changed without migrating the table. “Before creating the index, confirm the embedding dimension matches the model output — a mismatch will cause insertion errors.”

IVFFlat Index — Short for Inverted File with Flat quantisation, this is one of two index types available in pgvector. It divides the vector space into a fixed number of clusters (called lists) and searches only the nearest clusters at query time. It is faster to build than HNSW but typically less accurate. “We used an IVFFlat index during the prototype phase because it builds quickly, but we plan to migrate to HNSW before launch.”

HNSW Index — The Hierarchical Navigable Small World index, which builds a multi-layer graph over all vectors. It is slower to build and uses more memory than IVFFlat, but it generally delivers higher recall and better query performance at scale. “After switching to the HNSW index, our nearest-neighbour queries became roughly three times faster with a measurable improvement in recall.”

Cosine Similarity — A distance measure that calculates the angle between two vectors rather than the straight-line distance between them. It is often preferred for text embeddings because it focuses on the direction of the vector (semantic meaning) rather than its magnitude. “We use the cosine distance operator <=> because our embeddings are not normalised, and cosine similarity gives more consistent results for semantic search.”

L2 Distance — Also called Euclidean distance, this measures the straight-line distance between two points in vector space. It is the default distance metric in many systems and works well for image embeddings and other use cases where magnitude is meaningful. “The L2 distance operator <-> is suitable here because our image embeddings carry meaningful magnitude information.”

Inner Product — A distance metric equivalent to the dot product of two vectors. When vectors are normalised to unit length, inner product and cosine similarity produce identical rankings. pgvector uses the negative inner product operator <#> because PostgreSQL index scans minimise values. “Since we normalise all embeddings before storing them, we switched to inner product distance, which is marginally faster to compute.”

Approximate Nearest Neighbour (ANN) — A search strategy that finds vectors close to the query vector very quickly, accepting a small trade-off in accuracy compared to an exhaustive exact search. Both IVFFlat and HNSW are ANN methods. The term “approximate” is not a criticism — at scale, exact search is too slow to be practical. “We explained to the product team that approximate nearest neighbour search occasionally misses the single closest result, but in practice users cannot perceive the difference.”

Useful Phrases

Engineers working with pgvector in English-speaking teams regularly use phrases like these:

• “We need to vacuum the table after the bulk insert before the HNSW index reaches its full performance — the index updates lazily.”
• “Set ivfflat.probes to a higher value to improve recall at the cost of slower queries during development.”
• “The query is doing a sequential scan instead of using the index — check that enable_seqscan is off and the planner statistics are up to date.”
• “We’re doing hybrid search by combining the vector similarity score with a full-text search rank using a weighted sum.”
• “Can you add a WHERE clause to pre-filter by tenant_id before the ANN search? That will keep results isolated per customer.”

Common Mistakes

Using “accuracy” when you mean “recall”

Non-native speakers often say “the index has lower accuracy” when discussing ANN search. In this context, the correct technical term is recall — specifically, the percentage of true nearest neighbours that the approximate search successfully returns. “Accuracy” implies a classification problem. Saying “we measured recall at 95%” sounds professional; “we measured accuracy at 95%” may confuse your colleagues.

Confusing ivfflat and hnsw build-time behaviour

Engineers sometimes say “rebuild the index” when they mean “create the index.” With ivfflat, you must insert data before building the index, because it needs data to compute the cluster centroids. Saying “we’ll build the index first and then populate the table” is a common mistake — both in workflow and in English communication about the workflow.

Forgetting to specify distance operator in conversation

When discussing pgvector queries verbally or in writing, always name the distance metric explicitly. Saying “I’ll query the nearest vectors” leaves ambiguity. Saying “I’ll query using cosine distance” is precise and avoids misunderstandings when a colleague assumes a different metric.

Mastering pgvector vocabulary allows you to participate confidently in database design reviews and AI feature planning sessions. The ability to explain the trade-offs between IVFFlat and HNSW, or to articulate why you chose cosine similarity over L2 distance, demonstrates both technical depth and professional communication skills that will serve you well in any English-speaking engineering team.