Cosine distance measures how far apart two vectors point: 0 means identical direction, while larger values indicate less similarity. In pgvector, the <=> operator computes this distance inside PostgreSQL rather than in application code. section 5.4.3
A production vector search uses cosine distance to:
- Rank stored embeddings against a query embedding and return the top-k matches. section 5.4.3
- Convert distance into a similarity score with 1 - distance, so higher values represent closer matches. section 5.4.3
- Combine vector comparison with index and metadata filters in one SQL query. section 5.4.3
pgvector search score
A search expression such as 1 - (embedding <=> query_embedding) turns pgvector's lower-is-better distance into a higher-is-better similarity score. A later threshold can then decide whether the matching chunk is relevant enough for model context. section 5.4.3
Listing 5.19 pgvectorStore search implementation
class PgvectorStore(VectorStore):
def __init__(self, connection_string: str):
self.conn = psycopg2.connect(connection_string)
def search(
self,
index_name: str,
query_embedding: List[float],
top_k: int = 5,
metadata_filters: Optional[Dict[str, str]] = None,
score_threshold: Optional[float] = None
) -> List[SearchResult]:
query = """
SELECT chunk_id, document_id, chunk_text, metadata,
1 - (embedding <=> %s::vector) AS score
FROM chunks
WHERE index_name = %s
""" #A
params = [query_embedding, index_name]
if metadata_filters:
for key, value in metadata_filters.items():
query += " AND metadata->>%s = %s"
params.extend([key, value]) #B
if score_threshold:
query += " AND 1 - (embedding <=> %s::vector) >= %s"
params.extend
➥([query_embedding, score_threshold]) #C
query += " ORDER BY embedding <=> %s::vector LIMIT %s"
params.extend([query_embedding, top_k]) #D
cursor = self.conn.cursor()
cursor.execute(query, params)
return [
SearchResult(
chunk_id=row[0], document_id=row[1],
text=row[2], metadata=row[3], score=row[4]
)
for row in cursor.fetchall()
]Shows a PgvectorStore interface that computes cosine-based scores, applies index and metadata filters, and returns ranked search results. section 5.4.3








