Mark COSINE VectorSimilarity function as deprecated (#13473)

apache · Jun 11, 2024 · c45616a · c45616a
1 parent c6e604f
commit c45616a
Show file tree

Hide file tree

Showing 3 changed files with 13 additions and 2 deletions.
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt
@@ -7,7 +7,8 @@ http://s.apache.org/luceneversions
 
 API Changes
 ---------------------
-(No changes)
+
+* GITHUB#13281: Mark COSINE VectorSimilarityFunction as deprecated. (Pulkit Gupta)
 
 New Features
 ---------------------

diff --git a/lucene/core/src/java/org/apache/lucene/index/VectorSimilarityFunction.java b/lucene/core/src/java/org/apache/lucene/index/VectorSimilarityFunction.java
@@ -66,7 +66,10 @@ public float compare(byte[] v1, byte[] v2) {
    * vectors to unit length, and instead use {@link VectorSimilarityFunction#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.
+   *
+   * @deprecated Use MAXIMUM_INNER_PRODUCT or DOT_PRODUCT instead
    */
+  @Deprecated
   COSINE {
     @Override
     public float compare(float[] v1, float[] v2) {

diff --git a/lucene/core/src/java/org/apache/lucene/util/VectorUtil.java b/lucene/core/src/java/org/apache/lucene/util/VectorUtil.java
@@ -70,7 +70,9 @@ public static float dotProduct(float[] a, float[] b) {
    * Returns the cosine similarity between the two vectors.
    *
    * @throws IllegalArgumentException if the vectors' dimensions differ.
+   * @deprecated use dot-product instead using normalized vectors
    */
+  @Deprecated
   public static float cosine(float[] a, float[] b) {
     if (a.length != b.length) {
       throw new IllegalArgumentException("vector dimensions differ: " + a.length + "!=" + b.length);
@@ -80,7 +82,12 @@ public static float cosine(float[] a, float[] b) {
     return r;
   }
 
-  /** Returns the cosine similarity between the two vectors. */
+  /**
+   * Returns the cosine similarity between the two vectors.
+   *
+   * @deprecated use dot-product instead using normalized vectors
+   */
+  @Deprecated
   public static float cosine(byte[] a, byte[] b) {
     if (a.length != b.length) {
       throw new IllegalArgumentException("vector dimensions differ: " + a.length + "!=" + b.length);