VectorSimilarityFunction (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.index, enum: VectorSimilarityFunction

Package org.apache.lucene.index

# Enum Class VectorSimilarityFunction

java.lang.Object
java.lang.Enum<VectorSimilarityFunction>
org.apache.lucene.index.VectorSimilarityFunction

All Implemented Interfaces:
  `Serializable`, `Comparable<VectorSimilarityFunction>`, `Constable`

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.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class java.lang.Enum

  `Enum.EnumDesc<E extends Enum<E>>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `COSINE`
  Cosine similarity.
  `DOT_PRODUCT`
  Dot product.
  `EUCLIDEAN`
  Euclidean distance
  `MAXIMUM_INNER_PRODUCT`
  Maximum inner product.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract float`
  `compare(byte[] v1, byte[] v2)`
  Calculates a similarity score between the two vectors with a specified function.
  `abstract float`
  `compare(float[] v1, float[] v2)`
  Calculates a similarity score between the two vectors with a specified function.
  `static VectorSimilarityFunction`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static VectorSimilarityFunction[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.

  ### Methods inherited from class java.lang.Enum

  `clone, compareTo, describeConstable, 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 normalized, including both document and query vectors. Using dot product with vectors that are not normalized can result in errors or poor search results. Floating point vectors must be normalized to be of unit length, while byte vectors should simply all have the same norm.

  - ### 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. The similarity score is normalised to assure it is positive.

  - ### MAXIMUM_INNER_PRODUCT

    public static final VectorSimilarityFunction MAXIMUM_INNER_PRODUCT
    Maximum inner product. This is like `DOT_PRODUCT`, but does not require normalization of the inputs. Should be used when the embedding vectors store useful information within the vector magnitude

- ## Method Details

  - ### values

    public static VectorSimilarityFunction[] 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 VectorSimilarityFunction 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

  - ### compare

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

  - ### compare

    public abstract float compare(byte[] v1, byte[] v2)
    Calculates a similarity score between the two vectors with a specified function. Higher similarity scores correspond to closer vectors. Each (signed) byte represents a vector dimension.
    Parameters:
      `v1` - a vector
      `v2` - another vector, of the same dimension
    Returns:
      the value of the similarity function applied to the two vectors