Package org.apache.lucene.index

Enum VectorSimilarityFunction

java.lang.Object
java.lang.Enum<VectorSimilarityFunction>
org.apache.lucene.index.VectorSimilarityFunction
All Implemented Interfaces:
Serializable, Comparable<VectorSimilarityFunction>
public enum VectorSimilarityFunction extends Enum<VectorSimilarityFunction>
Vector similarity function; used in search to return top K most similar vectors to a target vector. This is a label describing the method used during indexing and searching of the vectors in order to determine the nearest neighbors.

  • Enum Constant Summary

    Enum Constants
    Enum Constant
    Description
    COSINE
    Cosine similarity.
    DOT_PRODUCT
    Dot product.
    EUCLIDEAN
    Euclidean distance

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final boolean
    reversed
    If true, the scores associated with vector comparisons are nonnegative and in reverse order; that is, lower scores represent more similar vectors.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract float
    compare(float[] v1, float[] v2)
    Calculates a similarity score between the two vectors with a specified function.
    abstract float
    convertToScore(float similarity)
    Converts similarity scores used (may be negative, reversed, etc) into document scores, which must be positive, with higher scores representing better matches.
    static VectorSimilarityFunction
    valueOf(String name)
    Returns the enum constant of this type with the specified name.
    static VectorSimilarityFunction[]
    values()
    Returns an array containing the constants of this enum type, in the order they are declared.

    Methods inherited from class java.lang.Enum

    clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Enum Constant Details

    • EUCLIDEAN

      public static final VectorSimilarityFunction EUCLIDEAN
      Euclidean distance

    • DOT_PRODUCT

      public static final VectorSimilarityFunction DOT_PRODUCT
      Dot product. NOTE: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results.

    • COSINE

      public static final VectorSimilarityFunction COSINE
      Cosine similarity. NOTE: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.

  • Field Details

    • reversed

      public final boolean reversed
      If true, the scores associated with vector comparisons are nonnegative and in reverse order; that is, lower scores represent more similar vectors. Otherwise, if false, higher scores represent more similar vectors, and scores may be negative or positive.

  • Method Details

    • values

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

    • valueOf

      public static VectorSimilarityFunction valueOf(String name)
      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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 type has no constant with the specified name
      NullPointerException - if the argument is null

    • compare

      public abstract float compare(float[] v1, float[] v2)
      Calculates a similarity score between the two vectors with a specified function.
      Parameters:
      v1 - a vector
      v2 - another vector, of the same dimension
      Returns:
      the value of the similarity function applied to the two vectors

    • convertToScore

      public abstract float convertToScore(float similarity)
      Converts similarity scores used (may be negative, reversed, etc) into document scores, which must be positive, with higher scores representing better matches.
      Parameters:
      similarity - the raw internal score as returned by compare(float[], float[]).
      Returns:
      normalizedSimilarity