How do you implement semantic search with pgvector and a similarity threshold?

-- Return results only within a distance threshold
-- (distance < threshold means similar enough)

-- Cosine distance threshold (0 = identical, 1 = orthogonal)
SELECT id, content,
       1 - (embedding <=> '[...]') AS similarity,
       embedding <=> '[...]' AS distance
FROM documents
WHERE embedding <=> '[...]' < 0.3    -- only results within distance 0.3
ORDER BY distance
LIMIT 20;

-- L2 distance threshold (depends on your vector magnitude):
SELECT id, content, embedding <-> '[...]' AS distance
FROM documents
WHERE embedding <-> '[...]' < 1.5    -- only close vectors
ORDER BY distance
LIMIT 10;

-- Dynamic threshold: always return at least 1 result,
-- but enforce threshold if more than 1 exists
WITH ranked AS (
    SELECT id, content,
           embedding <=> '[...]' AS dist,
           ROW_NUMBER() OVER (ORDER BY embedding <=> '[...]') AS rn
    FROM documents
)
SELECT id, content, dist
FROM ranked
WHERE dist < 0.3 OR rn = 1  -- always return top result
ORDER BY dist
LIMIT 10;

-- Typical cosine distance thresholds (vary by model and use case):
-- 0.0 - 0.15: very similar (nearly duplicate content)
-- 0.15 - 0.30: similar (same topic, different wording)
-- 0.30 - 0.50: somewhat related
-- > 0.50: likely unrelated (for most text embedding models)