VECTOR_DISTANCE

Purpose

VECTOR_DISTANCE is the main function that you can use to calculate the distance between two vectors.

VECTOR_DISTANCE takes two vectors as parameters. You can optionally specify a distance metric to calculate the distance. If you do not specify a distance metric, then the default distance metric is Cosine distance.

You can optionally use the following shorthand vector distance functions:

  • L1_DISTANCE

  • L2_DISTANCE

  • COSINE_DISTANCE

  • INNER_PRODUCT

All the vector distance functions take two vectors as input and return the distance between them as a BINARY_DOUBLE.

Note the following caveats, if you use VECTOR_DISTANCE to perform a similarity search:
  • If you do not specify a distance metric, then the default distance metric COSINE is used for both exact and approximate (index-based) searches.

  • If you specify a distance metric that conflicts with the distance metric specified in a vector index, then the distance metric that you specify is used to perform the exact search.

  • If you specify a distance metric that matches the distance metric specified in a vector index, then distance metric specified in the vector index is used for both exact and approximate (index-based) searches.

Parameters

  • expr1 and expr2 must evaluate to vectors and have the same number of dimensions. This function returns NULL if either expr1 or expr2 is NULL or if the dimensions between the two vectors do not match up.

  • metric must be one of the following tokens :

    • COSINE metric is the default metric. It calculates the cosine distane between two vectors.

    • DOT metric, also called the inner product, calculates the negated dot product of two vectors.

    • EUCLIDEAN metric, also called L2_DISTANCE, calculates the Euclidean distance between two vectors.

    • EUCLIDEAN_SQUARED metric, also called L2_SQUARED is the Euclidean distance without taking the square root.

    • HAMMING metric calculates the hamming distance between two vectors.

    • MANHATTAN metric, also called L1_DISTANCE or taxicab distance, calculates the Manhattan distance.

Shorthand Operators for Distances

Oracle provides the following shorthand distance operators that you can use instead of their corresponding distance functions:

  • <-> is the Euclidian distance operator: expr1 <-> expr2 is equivalent to L2_DISTANCE(expr1, expr2) or VECTOR_DISTANCE(expr1, expr2, EUCLIDEAN)
  • <=> is the cosine distance operator: expr1 <=> expr2 is equivalent toCOSINE_DISTANCE(expr1, expr2) or VECTOR_DISTANCE(expr1, expr2, COSINE)
  • <#> is the negative dot product operator: expr1 <#> expr2 is equivalent to -1*INNER_PRODUCT(expr1, expr2) or VECTOR_DISTANCE(expr1, expr2, DOT)

Examples

VECTOR_DISTANCE with metric EUCLIDEAN is equivalent to L2_DISTANCE:

VECTOR_DISTANCE(expr1, expr2, EUCLIDEAN);
L2_DISTANCE(expr1, expr2);

VECTOR_DISTANCE with metric COSINE is equivalent to COSINE_DISTANCE:

VECTOR_DISTANCE(expr1, expr2, COSINE);
COSINE_DISTANCE(expr1, expr2);

VECTOR_DISTANCE with metric DOT is equivalent to -1 * INNER_PRODUCT:

VECTOR_DISTANCE(expr1, expr2, DOT);
-1*INNER_PRODUCT(expr1, expr2);

VECTOR_DISTANCE with metric MANHATTAN is equivalent to L1_DISTANCE:

VECTOR_DISTANCE(expr1, expr2, MANHATTAN);
L1_DISTANCE(expr1, expr2);