Package com.apple.foundationdb.linear

Interface DistanceEstimator

All Known Implementing Classes:
RaBitDistanceEstimator
public interface DistanceEstimator
Computes a distance between two vectors. Implementations are typically tied to a specific Metric but may add behavior on top of the raw metric — for example, applying a quantization-aware fast path when one or both vectors are encoded.

Search and clustering algorithms drive vector comparisons through this interface so they can stay agnostic of how distances are actually computed (raw metric, rabitq estimator, etc.).

  • Method Details

    • getMetric

      @Nonnull Metric getMetric()
      Returns the underlying Metric this estimator computes.

    • isOptimized

      default boolean isOptimized(@Nonnull Transformed<? extends RealVector> vector1, @Nonnull Transformed<? extends RealVector> vector2)
      Convenience overload of isOptimized(RealVector, RealVector) that unwraps the underlying vectors from Transformed containers and forwards to the RealVector variant.

    • isOptimized

      boolean isOptimized(@Nonnull RealVector vector1, @Nonnull RealVector vector2)
      Returns whether this estimator can compute the distance between vector1 and vector2 on a metric-specific fast path that bypasses the raw metric. For example, a quantization-aware estimator may report true when at least one of the vectors is in the encoded form it knows how to consume directly.

      Default ofMetric-built estimators have no fast path and always return false. Callers can use this hint to skip work that is only worthwhile for the generic path (e.g. avoiding decode of an encoded vector if both will go through the estimator's fast path anyway).

      Parameters:
      vector1 - the first vector
      vector2 - the second vector
      Returns:
      true iff this estimator has a metric-specific fast path for the given pair

    • distance

      default double distance(@Nonnull Transformed<? extends RealVector> vector1, @Nonnull Transformed<? extends RealVector> vector2)
      Convenience overload of distance(RealVector, RealVector) that unwraps the underlying vectors from Transformed containers and forwards to the RealVector variant.

    • distance

      double distance(@Nonnull RealVector vector1, @Nonnull RealVector vector2)
      Calculates the distance between two vectors that have already been transformed into the estimator's coordinate system.

      Both arguments must already have been rotated/translated as expected by the estimator before calling this method — implementations do not apply any preprocessing. Implementations may reject distance values that are not finite (depending on the metric and on whether the inputs are zero vectors, etc.) by throwing an IllegalArgumentException.

      Parameters:
      vector1 - the first pre-rotated and translated vector
      vector2 - the second pre-rotated and translated vector
      Returns:
      a non-negative double representing the distance between the two vectors

    • ofMetric

      @Nonnull static DistanceEstimator ofMetric(@Nonnull Metric metric)
      Returns a plain DistanceEstimator that delegates straight to metric.distance(...). The result has no fast path (isOptimized(com.apple.foundationdb.linear.Transformed<? extends com.apple.foundationdb.linear.RealVector>, com.apple.foundationdb.linear.Transformed<? extends com.apple.foundationdb.linear.RealVector>) is always false) and rejects non-finite distances with an IllegalArgumentException.
      Parameters:
      metric - the metric to wrap
      Returns:
      a non-null estimator that computes metric's distance directly