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.

Navigating Feedback Loops – A Practical Approach

Let’s be honest; the initial excitement of building with pgvector can quickly give way to a deluge of feedback. As a developer, you’re not just writing code; you’re communicating its intent, justifying decisions, and receiving critiques that shape the entire process. Mastering the vocabulary around this communication – particularly when dealing with complex concepts like embeddings and similarity search – is crucial. It’s not enough to simply understand the technical details; you need to articulate them clearly and confidently, both in code reviews and broader discussions.

Consider a scenario: You’ve implemented a new hybrid search index combining exact phrase matching with cosine similarity on vector embeddings. During a code review, a senior engineer comments: “The current implementation lacks clarity around the weighting applied to the different vectors. It’s difficult to gauge whether the system prioritizes precision or recall. Could you elaborate on your rationale and potentially introduce logging for key metrics like query hit rate versus index coverage?” This isn’t about arguing; it’s about responding with a technically sound explanation, using precise vocabulary. Saying “I optimized the search” is far less effective than saying, “I leveraged cosine similarity to capture semantic relationships alongside an exact phrase index, recognizing that prioritizing recall requires a higher weighting for broader vector matches.”

A common Slack message you might encounter could be: “Hey team, need to increase the performance of our product recommendations. Thinking about re-indexing with pgvector and experimenting with different distance metrics. Anyone have experience with using Euclidean vs. Manhattan?” The ability to discuss these nuances – understanding the implications of choosing one metric over another - is key. Framing your thoughts using terms like “semantic drift,” “dimensionality reduction,” or even referencing specific distance metrics (“Euclidean distance favors larger values, potentially leading to bias if not carefully calibrated”) demonstrates a deeper level of engagement and allows for more productive conversations. It’s about moving beyond simply doing the work to actively shaping the discussion around it.

Finally, crafting clear PR descriptions that incorporate this vocabulary is essential. Instead of “Updated index,” try: “Implemented a new hybrid search index leveraging cosine similarity with an exact phrase index to improve recall for user queries related to product features. The system now utilizes a configurable weighting scheme to dynamically adjust between precision and recall based on query characteristics, tracked via internal logging metrics.”

# Example pgvector CLI command - demonstrating creating an index with a specific distance metric:
pgvector_cli create --db mydatabase --collection products --index type=gist --distance=cosine

This simple command demonstrates how the vocabulary – “gist,” “cosine” – would be frequently used to discuss and troubleshoot indexing strategies.