liveBook · Manning

Cosine distance

As explained in Designing AI Systems

Cosine distance measures dissimilarity between vectors based on the angle between their directions, with zero indicating identical direction.

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

How Designing AI Systems covers it

How deep it goes
Defines distance behavior and implements operator-to-score conversion, but does not derive the underlying geometry mathematically.
Examples
Uses pgvector's <=> operator and the expression 1 - (embedding <=> query_embedding) in a PostgreSQL search.
What you can do after
Apply it via pgvector to rank stored embeddings, convert distances into scores, and enforce relevance thresholds.
How it connects
Connects cosine distance with embeddings, vector similarity search, PostgreSQL, metadata filtering, and similarity thresholds.

Also explained in

Compare how 9 books explain cosine distance →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.