What is cosine distance vs cosine similarity and which does pgvector return?

-- pgvector's <=> returns COSINE DISTANCE (not similarity)
-- Lower value = more similar
SELECT id, content,
       embedding <=> '[0.1,0.2,0.3]' AS cosine_distance
FROM documents
ORDER BY cosine_distance          -- ASC: smallest distance first = most similar
LIMIT 5;

-- Convert to cosine SIMILARITY:
SELECT id, content,
       1 - (embedding <=> '[0.1,0.2,0.3]') AS cosine_similarity
FROM documents
ORDER BY embedding <=> '[0.1,0.2,0.3]'  -- still ORDER BY distance
LIMIT 5;

-- For normalised vectors (most embedding models output unit vectors):
-- cosine_similarity = 1 - cosine_distance
-- Also: cosine_similarity ~= inner_product for unit vectors
-- So for OpenAI text-embedding-3-small (outputs unit vectors):
-- <=> and <#> (after negation) give equivalent rankings

-- Verify a vector is normalised (magnitude = 1.0):
SELECT id, |/( embedding <-> '[0,0,0]'^2 ) AS magnitude
-- or more simply:
SELECT id, sqrt(embedding <.> embedding) AS magnitude  -- inner product of self