What is cosine distance?

Cosine distance is cosine similarity converted into a value that behaves like an ordinary distance, decreasing toward zero as two vectors become more alike rather than increasing the way cosine similarity itself does.

How is cosine distance actually derived from cosine similarity?

Cosine similarity produces a value between negative 1 and 1, where 1 means two vectors point in exactly the same direction. Cosine distance is typically calculated by subtracting cosine similarity from 1, which flips this relationship around: two identical-direction vectors now produce a distance of 0, matching the usual expectation that distance shrinks toward zero as things become more alike, the opposite of how similarity scores normally behave.

Why do implementations sometimes expose cosine distance instead of cosine similarity directly?

Search systems, including HNSW itself, are generally built around the idea of finding the smallest distance to a query, since the underlying search algorithms are framed in terms of minimizing distance rather than maximizing similarity. Exposing cosine distance rather than cosine similarity lets these systems use the exact same “find the smallest value” logic they already use for Euclidean distance and every other distance function, without needing a separate code path that instead looks for the largest similarity score. This is purely a matter of framing the same underlying comparison in whichever direction a given system’s internal machinery expects, not a difference in what’s actually being measured.

How does the terminology get confused in practice?

Because cosine similarity and cosine distance are simple transformations of each other, the two terms get used loosely and sometimes incorrectly in practice — a library or an API might document a parameter as “cosine similarity” while actually computing cosine distance internally, or vice versa. This kind of mix-up is precisely the sort of semantic bug described in this site’s page on production failure modes: the numbers a system produces will still look plausible either way, but a search optimizing for the smallest cosine distance when it should be optimizing for the largest cosine similarity will quietly return the worst matches instead of the best ones. Checking explicitly which of the two a given system actually computes, rather than assuming based on the name alone, is worth the extra minute it takes.

Cosine distance and cosine similarity are two framings of exactly the same underlying comparison, covered together with inner product in this site’s page on measuring distance and similarity between vectors. From here, the page on cosine similarity itself is the natural next step for anyone who arrived here first.