ES|QL brute force l1_norm vector function (#131768)

Author: tteofili

docs/reference/query-languages/esql/_snippets/functions/description/v_l1_norm.md

@@ -0,0 +1,90 @@
+ # Tests for l1_norm similarity function
+ 
+ similarityWithVectorField
+ required_capability: l1_norm_vector_similarity_function
+ 
+// tag::vector-l1-norm-similarity[]
+ from colors
+ | eval similarity = v_l1_norm(rgb_vector, [0, 255, 255]) 
+ | sort similarity desc, color asc 
+// end::vector-l1-norm-similarity[]
+ | limit 10
+ | keep color, similarity
+ ;
+ 
+// tag::vector-l1-norm-similarity-result[]
+color:text | similarity:double
+red        | 765.0
+crimson    | 650.0
+maroon     | 638.0
+firebrick  | 620.0
+orange     | 600.0
+tomato     | 595.0
+brown      | 591.0
+chocolate  | 585.0
+coral      | 558.0
+gold       | 550.0
+// end::vector-l1-norm-similarity-result[] 
+;
+
+ similarityAsPartOfExpression
+ required_capability: l1_norm_vector_similarity_function
+ 
+ from colors
+ | eval score = round((1 + v_l1_norm(rgb_vector, [0, 255, 255]) / 2), 3) 
+ | sort score desc, color asc 
+ | limit 10
+ | keep color, score
+ ;
+
+color:text | score:double
+red        | 383.5
+crimson    | 326.0
+maroon     | 320.0
+firebrick  | 311.0
+orange     | 301.0
+tomato     | 298.5
+brown      | 296.5
+chocolate  | 293.5
+coral      | 280.0
+gold       | 276.0
+;
+
+similarityWithLiteralVectors
+required_capability: l1_norm_vector_similarity_function
+ 
+row a = 1
+| eval similarity = round(v_l1_norm([1, 2, 3], [0, 1, 2]), 3) 
+| keep similarity
+;
+
+similarity:double
+3.0
+;
+
+ similarityWithStats
+ required_capability: l1_norm_vector_similarity_function
+ 
+ from colors
+ | eval similarity = round(v_l1_norm(rgb_vector, [0, 255, 255]), 3) 
+ | stats avg = round(avg(similarity), 3), min = min(similarity), max = max(similarity)
+ ;
+
+avg:double | min:double | max:double
+391.254    | 0.0        | 765.0
+;
+
+# TODO Need to implement a conversion function to convert a non-foldable row to a dense_vector
+similarityWithRow-Ignore
+required_capability: l1_norm_vector_similarity_function
+ 
+row vector = [1, 2, 3] 
+| eval similarity = round(v_l1_norm(vector, [0, 1, 2]), 3) 
+| sort similarity desc, color asc 
+| limit 10
+| keep color, similarity
+;
+
+similarity:double
+0.978  
+;

docs/reference/query-languages/esql/_snippets/functions/examples/v_l1_norm.md

@@ -20,6 +20,8 @@
 import org.elasticsearch.xpack.esql.EsqlTestUtils;
 import org.elasticsearch.xpack.esql.action.AbstractEsqlIntegTestCase;
 import org.elasticsearch.xpack.esql.action.EsqlCapabilities;
+import org.elasticsearch.xpack.esql.expression.function.vector.L1Norm;
+import org.elasticsearch.xpack.esql.expression.function.vector.VectorSimilarityFunction.SimilarityEvaluatorFunction;
 import org.junit.Before;
 
 import java.io.IOException;
@@ -37,22 +39,25 @@ public static Iterable<Object[]> parameters() throws Exception {
         List<Object[]> params = new ArrayList<>();
 
         if (EsqlCapabilities.Cap.COSINE_VECTOR_SIMILARITY_FUNCTION.isEnabled()) {
-            params.add(new Object[] { "v_cosine", VectorSimilarityFunction.COSINE });
+            params.add(new Object[] { "v_cosine", (SimilarityEvaluatorFunction) VectorSimilarityFunction.COSINE::compare });
         }
         if (EsqlCapabilities.Cap.DOT_PRODUCT_VECTOR_SIMILARITY_FUNCTION.isEnabled()) {
-            params.add(new Object[] { "v_dot_product", VectorSimilarityFunction.DOT_PRODUCT });
+            params.add(new Object[] { "v_dot_product", (SimilarityEvaluatorFunction) VectorSimilarityFunction.DOT_PRODUCT::compare });
+        }
+        if (EsqlCapabilities.Cap.L1_NORM_VECTOR_SIMILARITY_FUNCTION.isEnabled()) {
+            params.add(new Object[] { "v_l1_norm", (SimilarityEvaluatorFunction) L1Norm::calculateSimilarity });
         }
 
         return params;
     }
 
     private final String functionName;
-    private final VectorSimilarityFunction similarityFunction;
+    private final SimilarityEvaluatorFunction similarityFunction;
     private int numDims;
 
     public VectorSimilarityFunctionsIT(
         @Name("functionName") String functionName,
-        @Name("similarityFunction") VectorSimilarityFunction similarityFunction
+        @Name("similarityFunction") SimilarityEvaluatorFunction similarityFunction
     ) {
         this.functionName = functionName;
         this.similarityFunction = similarityFunction;
@@ -74,7 +79,7 @@ public void testSimilarityBetweenVectors() {
                 Double similarity = (Double) values.get(2);
 
                 assertNotNull(similarity);
-                float expectedSimilarity = similarityFunction.compare(left, right);
+                float expectedSimilarity = similarityFunction.calculateSimilarity(left, right);
                 assertEquals(expectedSimilarity, similarity, 0.0001);
             });
         }
@@ -96,7 +101,7 @@ public void testSimilarityBetweenConstantVectorAndField() {
                 Double similarity = (Double) values.get(1);
 
                 assertNotNull(similarity);
-                float expectedSimilarity = similarityFunction.compare(left, randomVector);
+                float expectedSimilarity = similarityFunction.calculateSimilarity(left, randomVector);
                 assertEquals(expectedSimilarity, similarity, 0.0001);
             });
         }
@@ -130,7 +135,7 @@ public void testSimilarityBetweenConstantVectors() {
 
             Double similarity = (Double) valuesList.get(0).get(0);
             assertNotNull(similarity);
-            float expectedSimilarity = similarityFunction.compare(vectorLeft, vectorRight);
+            float expectedSimilarity = similarityFunction.calculateSimilarity(vectorLeft, vectorRight);
             assertEquals(expectedSimilarity, similarity, 0.0001);
         }
     }

docs/reference/query-languages/esql/_snippets/functions/layout/v_l1_norm.md

@@ -1296,6 +1296,11 @@ public enum Cap {
          */
         DOT_PRODUCT_VECTOR_SIMILARITY_FUNCTION(Build.current().isSnapshot()),
 
+        /**
+         * l1 norm vector similarity function
+         */
+        L1_NORM_VECTOR_SIMILARITY_FUNCTION(Build.current().isSnapshot()),
+
         /**
          * Support for the options field of CATEGORIZE.
          */