Metric and Index Selection Cheat Sheet

Last validated: 2026-05-11

Use this page when you need a fast decision for metric and index settings without reading full command docs.

30-Second Decision Path

Current CLI reality:

Let query vector be $q$ and candidate vector be $x$.

Metric	Formula	Better score	Best when
`L2`	$d_{L2}(q,x)=\lVert q-x\rVert_2$	Smaller	You care about absolute geometric distance.
`IP`	$s_{IP}(q,x)=q\cdot x$	Larger	Magnitude and direction both matter.
`COSINE`	$s_{cos}(q,x)=\frac{q\cdot x}{\lVert q\rVert_2\lVert x\rVert_2}$	Larger	Angular similarity matters more than magnitude.

Normalization insight:

If vectors are unit-normalized, then $\lVert q-x\rVert_2^2 = 2 - 2s_{cos}(q,x)$.
In that case, L2 and COSINE produce identical ranking.

Index type	Search style	Strength	Trade-off
`FLAT`	Exact	Maximum correctness baseline	Latency rises fastest as data grows
`HNSW`	Approximate graph ANN	Strong latency/recall default	Higher memory overhead
`IVF_FLAT`	Approximate inverted file	Good scale with controllable quality	Needs tuning for best recall
`IVF_SQ8`	IVF + quantization	Better memory efficiency	More approximation loss

Situation	Starting config	Why
New project, verify data quality	`FLAT + L2`	Establish trusted baseline before optimization
General production vector search	`HNSW + L2`	Balanced speed and quality
Growing dataset with latency pressure	`IVF_FLAT + L2`	Better scale characteristics
Memory-constrained very large deployment	`IVF_SQ8 + L2`	Reduces memory footprint

Use direct CLI path for standard operations:

Use RunCommand when you need unsupported search/index controls, especially explicit metric behavior beyond first-class CLI defaults.

RunCommand workflow:

Metric intent is clear (L2, IP, or COSINE).
Index type matches scale and latency goals.
Vector dimension in data matches collection schema.
Field names in insert/search match collection definition.
If using first-class CLI search, metric expectation is consistent with L2 behavior.