Distance Metrics

PistaDB supports five distance metrics — every metric is implemented for every index type, with SIMD acceleration where available.

Metric	LLM / Embedding Use Case
COSINE	Text embeddings — OpenAI text-embedding-3, Cohere, sentence-transformers, BGE, GTE
IP	Inner product — embeddings already L2-normalised (same result as cosine, faster)
L2	Image / multimodal embeddings (CLIP, ImageBind)
L1	Sparse feature vectors, BM25-style hybrid retrieval
HAMMING	Binary embeddings, hash-based deduplication

SIMD acceleration

Distance kernels are runtime-dispatched based on the host CPU:

• x86-64: AVX2 + FMA path in distance_avx2.c
• ARM: NEON path in distance_neon.c
• Fallback: portable scalar implementation in distance.c

Typical speedup: 4–8× over scalar for 768- to 1536-dimensional float32 vectors.

Choosing the right metric

from pistadb import PistaDB, Metric, Index

# OpenAI / Cohere / sentence-transformers — cosine distance
db = PistaDB("docs.pst", dim=1536, metric=Metric.COSINE, index=Index.HNSW)

# Pre-normalised embeddings (e.g. BGE with normalize=True) — inner product is faster
db = PistaDB("docs.pst", dim=1024, metric=Metric.IP, index=Index.HNSW)

# CLIP image embeddings — L2 distance
db = PistaDB("clip.pst", dim=512, metric=Metric.L2, index=Index.HNSW)

# Binary hashes (e.g. perceptual image hashes) — Hamming distance
db = PistaDB("dedup.pst", dim=64, metric=Metric.HAMMING, index=Index.LINEAR)

Tip: if your embedding model normalises vectors at output time, prefer Metric.IP. It produces the same ranking as cosine and skips the per-query normalisation step.