iqdb_types/metric.rs
1//! The distance metric used to compare vectors.
2
3/// The metric used to measure distance (or similarity) between two vectors.
4///
5/// Which metric is valid depends on how the vectors were produced — cosine and
6/// dot product suit normalized embeddings, the geometric metrics suit raw
7/// coordinates, and Hamming suits binary codes. The engine selects the matching
8/// comparison from this tag.
9///
10/// # Examples
11///
12/// ```
13/// use iqdb_types::DistanceMetric;
14///
15/// let metric = DistanceMetric::Cosine;
16/// assert_eq!(metric, DistanceMetric::Cosine);
17/// assert_ne!(metric, DistanceMetric::Euclidean);
18/// ```
19///
20/// The enum is `#[non_exhaustive]`: future releases may add metrics (for
21/// example, Jaccard or Chebyshev) without it being a breaking change, so a
22/// `match` on it from another crate must include a wildcard arm.
23#[non_exhaustive]
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
25#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
26pub enum DistanceMetric {
27 /// Cosine distance — the angle between vectors, ignoring magnitude. Suits
28 /// normalized embeddings.
29 Cosine,
30 /// Dot-product similarity — magnitude-sensitive inner product. Suits
31 /// embeddings where magnitude carries signal.
32 DotProduct,
33 /// Euclidean (L2) distance — straight-line distance between coordinates.
34 Euclidean,
35 /// Manhattan (L1) distance — sum of absolute per-component differences.
36 Manhattan,
37 /// Hamming distance — count of differing positions. Suits binary codes.
38 Hamming,
39}