L2, Cosine, Inner Product, L1, Hamming, and Jaccard Distance

A distance metric defines what “near” means. pgvector supports L2 (<->), negative inner product (<#>), cosine (<=>), L1 (<+>), Hamming (<~>), and Jaccard (<%>) operators for compatible types. Use the metric your embedding or feature design expects, then build the matching operator-class index and evaluate it on your task.

What will you be able to do?

• Map every pgvector distance operator to its meaning.
• Convert distance to an interpretable similarity when appropriate.
• Select matching HNSW or IVFFlat operator classes.
• Explain metric differences with small vectors.
• Catch incorrect sort directions and thresholds.

Which operator does what?

<#> is negative because PostgreSQL index scans order ascending. Do not sort it descending to “fix” the sign; use ascending distance for nearest-neighbor index access and negate only the displayed score.

How do continuous-vector metrics differ?

• L2 measures straight-line separation and is sensitive to magnitude.
• Cosine measures angular difference and largely ignores magnitude for non-zero vectors.
• Inner product rewards alignment and magnitude; it is especially efficient for normalized vectors when recommended by the model.
• L1 sums absolute coordinate differences and can behave more robustly for some feature distributions.

For normalized vectors a and b, ||a-b||² = 2 - 2(a·b), so L2, cosine, and inner-product rankings are closely related. Do not assume normalization unless you verify it.

What do binary metrics do?

For bit vectors, Hamming counts differing bit positions. Jaccard compares the intersection and union of set bits. Binary quantization can make storage and first-stage search smaller or faster, but it discards information. Rerank binary candidates with the original continuous vectors when quality requires it.

How do operator classes match?

The cosine query must use <=> to use vector_cosine_ops; L2 uses <-> with vector_l2_ops. Indexing each metric consumes space and write work. Build only metrics your application actually uses.

How do you verify it?

Predict first. Then use EXPLAIN (ANALYZE, BUFFERS) on an indexed, non-trivial table and confirm the intended index and ordering operator.

What breaks in production?

• A cosine index is built while queries order by L2.
• A team calls cosine distance “similarity” without subtracting from one.
• Thresholds are copied across models, metrics, and domains.
• Inner-product results are displayed with the negative sign.
• Bit quantization is introduced without measuring recall loss.

AI pair-work prompt

Given this embedding model documentation [paste excerpt] and these query/index definitions [paste SQL], identify the intended metric, pgvector operator, type-specific operator class, sort direction, and displayed score conversion. State every assumption and create a five-query verification matrix.

Verification contract: Confirm the answer against the model's primary documentation and an EXPLAIN plan; do not accept a metric chosen only because it is popular.

Check your understanding

1. Why does <#> return a negative value?
2. Which operator and operator class implement cosine search for vector?
3. Compare [1,0] and [2,0] under cosine and L2.

Official references

• pgvector distances
• pgvector indexes
• PostgreSQL operator classes