Enum Class QdrantDistance

java.lang.Object
java.lang.Enum<QdrantDistance>
org.eclipse.jnosql.databases.qdrant.communication.QdrantDistance
All Implemented Interfaces:
Serializable, Comparable<QdrantDistance>, Constable

public enum QdrantDistance extends Enum<QdrantDistance>
Defines the distance metrics supported by Qdrant vector collections.

The distance metric determines how Qdrant compares stored vectors with a query vector. The metric is part of the vector collection/index configuration and is not selected per search operation.

A typical configuration may use:


 QdrantDistance distance = QdrantDistance.COSINE;
 

Conceptually:

 query vector
      |
      v
 configured distance
      |
      v
 stored vectors
      |
      v
 nearest matches
 

Each value maps to the equivalent Qdrant client Collections.Distance.

  • Enum Constant Details

    • COSINE

      public static final QdrantDistance COSINE
      Cosine distance.

      Cosine focuses mainly on the direction of the vectors rather than their magnitude. This is useful when the relative pattern matters more than the absolute amount.

      Consider a recommendation system where vector dimensions represent movie genres:

                       Action  Comedy  Drama
      
       Alice              10       2      1
       Bob               100      20     10
       Carol               2      10      8
       

      Alice and Bob have very different numbers of watched movies, but their preference proportions are essentially the same. Both strongly prefer action movies over comedy and drama.

      Cosine therefore considers Alice and Bob highly similar because their vectors point in the same direction. Carol has a different preference pattern and would be considered less similar.

      This behavior is often useful for embeddings and recommendation systems, where the pattern or semantic direction matters more than the absolute magnitude.

                       A · B
       cosine(A,B) = ----------
                      |A| |B|
       
    • EUCLID

      public static final QdrantDistance EUCLID
      Euclidean distance, also known as L2 distance.

      Euclidean distance measures the straight-line distance between two vectors. Unlike cosine, the magnitude of the vectors matters.

      Consider the same movie-preference example:

                       Action  Comedy  Drama
      
       Alice              10       2      1
       Bob               100      20     10
       Carol              11       3      1
       

      Alice and Bob have essentially the same preference proportions, so cosine would consider them very similar.

      Euclidean distance behaves differently because it considers the absolute values. Bob is much farther from Alice because he watched many more movies in every category.

      Carol, on the other hand, is very close to Alice because their absolute values are also similar:

       Alice  [10, 2, 1]
       Carol  [11, 3, 1]
       

      Therefore, Euclidean distance is useful when the magnitude or intensity represented by the vector is meaningful, not only its direction.

       euclid(A,B) = sqrt(
           (A1 - B1)^2 +
           (A2 - B2)^2 +
           ... +
           (An - Bn)^2
       )
       
    • DOT

      public static final QdrantDistance DOT
      Dot-product similarity.

      Dot product considers both direction and magnitude. Two users with the same preference pattern can receive different scores if one has much stronger activity than the other.

      Consider:

                       Action  Comedy  Drama
      
       Query               1       1      1
       Alice              10       2      1
       Bob               100      20     10
       Carol               2      10      8
       

      Alice and Bob have the same preference proportions, but Bob has a much larger magnitude because he watched many more movies.

      With dot product, Bob produces a much larger score than Alice:

       Query · Alice = 1*10 + 1*2 + 1*1   = 13
       Query · Bob   = 1*100 + 1*20 + 1*10 = 130
       

      This means dot product can be useful when both the preference direction and the strength or intensity represented by the vector matter.

       dot(A,B) =
           A1 * B1 +
           A2 * B2 +
           ... +
           An * Bn
       
    • MANHATTAN

      public static final QdrantDistance MANHATTAN
      Manhattan distance, also known as L1 distance.

      Manhattan distance adds the absolute difference between each dimension. Each movie category contributes independently to the final distance.

      Consider:

                       Action  Comedy  Drama
      
       Alice              10       2      1
       Bob               100      20     10
       Carol              11       3      1
       

      Carol is close to Alice because the difference in each category is small:

       |10 - 11| + |2 - 3| + |1 - 1|
       = 1 + 1 + 0
       = 2
       

      Bob is much farther away:

       |10 - 100| + |2 - 20| + |1 - 10|
       = 90 + 18 + 9
       = 117
       

      Unlike cosine, Manhattan distance cares about the absolute difference in activity. Unlike Euclidean distance, it simply adds the differences instead of combining them using squared geometric distance.

      It is useful when each dimension represents an independent difference that should contribute directly to the total distance.

       manhattan(A,B) =
           |A1 - B1| +
           |A2 - B2| +
           ... +
           |An - Bn|
       
  • Method Details

    • values

      public static QdrantDistance[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared
    • valueOf

      public static QdrantDistance valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null
    • parse

      public static QdrantDistance parse(String value)
      Parses a configuration value, ignoring case and surrounding whitespace. The Qdrant name for the metric (Cosine, Euclid, Dot, Manhattan) is accepted.
      Parameters:
      value - the configuration value
      Returns:
      the matching metric
      Throws:
      NullPointerException - when the value is null
      IllegalArgumentException - when the value is not a supported metric