English for pgvector Developers

pgvector has become a popular way to add vector similarity search directly inside Postgres, avoiding the need for a separate vector database. If you work with pgvector on an international team, you’ll need precise English to describe embeddings, indexing strategies, and query performance. This guide covers the core vocabulary for pgvector developers.

Key Vocabulary

Embedding — a numerical vector representation of text, images, or other data, produced by a machine learning model, that captures semantic meaning. “We store the embedding for each support article alongside its text so we can find semantically similar articles.”

Vector column — a Postgres column of type vector, used by pgvector to store fixed-length embeddings. “We added a vector column with 1536 dimensions to match the output size of our embedding model.”

Distance metric — the mathematical function used to measure similarity between two vectors, such as cosine distance, L2 distance, or inner product. “We use cosine distance for our search because our embeddings aren’t normalised by magnitude.”

Nearest neighbour search — a query that finds the vectors most similar to a given query vector, typically the basis of semantic search. “The nearest neighbour search returns the five most relevant documents for a user’s question in under 50 milliseconds.”

HNSW index — a graph-based approximate nearest neighbour index type in pgvector, offering fast queries at the cost of exact recall. “We switched from a flat scan to an HNSW index once our embeddings table passed a million rows.”

IVFFlat index — an inverted-file index type in pgvector that clusters vectors into partitions to speed up approximate search. “The IVFFlat index requires us to run ANALYZE after loading data, otherwise the query planner picks a poor number of probes.”

Recall — the proportion of true nearest neighbours actually returned by an approximate search, used to measure index quality. “We tuned the HNSW parameters until we hit 95% recall without sacrificing too much query latency.”

Hybrid search — a search strategy that combines vector similarity with traditional keyword or full-text search to improve relevance. “Hybrid search catches cases where a user searches for an exact error code that pure semantic search would miss.”

Re-ranking — a second-pass scoring step applied to an initial set of candidate results to improve final ordering. “We re-rank the top 50 vector search results with a cross-encoder model before showing the top 5 to the user.”

Discussing Indexing Choices

• “We chose HNSW over IVFFlat because our write volume is low and query latency matters more than index build time.”
• “Rebuilding the index after a bulk import took twenty minutes, so we scheduled it during our maintenance window.”
• “We index only the embedding column, not the raw text, since the text lives in a separate full-text search index.”

Talking About Search Quality

• “Users complained that search results felt ‘close but not quite right’ — we traced it to using L2 distance instead of cosine distance for normalised embeddings.”
• “We added a re-ranking step because raw vector similarity alone ranked some off-topic results too highly.”
• “Recall dropped after we lowered the ef_search parameter to reduce latency — we’re now testing a middle ground.”

Professional Tips

1. Match the distance metric to how the model was trained. Using the wrong metric silently degrades search quality without throwing errors.
2. Explain approximate search trade-offs to stakeholders. “Approximate” can sound alarming — frame it as a deliberate speed-versus-precision choice.
3. Benchmark before choosing an index type. HNSW and IVFFlat behave very differently at different data sizes and query patterns.

Practice Exercise

1. Explain to a teammate, in 3-4 sentences, why you chose cosine distance over L2 distance for your embeddings.
2. Write a short explanation (4-5 sentences) of what an HNSW index is and why it speeds up nearest neighbour search.
3. Describe a search quality bug you fixed by adding hybrid search or re-ranking, in a way a non-technical product manager could follow.