Implement v_hamming (#132959)

Implements #132056

Author: svilen-mihaylov-elastic

docs/changelog/132959.yaml

@@ -0,0 +1,5 @@
+pr: 132959
+summary: Adds the `v_hamming` function for calculating the Hamming distance between two dense vectors
+area: ES|QL
+type: feature
+issues: [132056]

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

@@ -0,0 +1,103 @@
+ # Tests for hamming similarity function
+ 
+ similarityWithVectorField
+ required_capability: hamming_vector_similarity_function
+ 
+// tag::vector-hamming[]
+ from colors
+ | eval similarity = v_hamming(rgb_vector, [0, 255, 255]) 
+ | sort similarity desc, color asc 
+// end::vector-hamming[]
+ | limit 10
+ | keep color, similarity
+ ;
+ 
+// tag::vector-hamming-result[]
+color:text | similarity:double
+red        | 24.0
+orange     | 20.0
+gold       | 18.0
+indigo     | 18.0
+bisque     | 17.0
+maroon     | 17.0
+pink       | 17.0
+salmon     | 17.0
+black      | 16.0
+firebrick  | 16.0
+// end::vector-hamming-result[] 
+;
+
+similarityAsPartOfExpression
+required_capability: hamming_vector_similarity_function
+
+from colors
+| eval score = round((1 + v_hamming(rgb_vector, [0, 255, 255]) / 2), 3) 
+| sort score desc, color asc 
+| limit 10
+| keep color, score
+;
+
+color:text | score:double
+red        | 13.0
+orange     | 11.0
+gold       | 10.0
+indigo     | 10.0
+bisque     | 9.5
+maroon     | 9.5
+pink       | 9.5
+salmon     | 9.5
+black      | 9.0
+firebrick  | 9.0
+;
+
+similarityWithLiteralVectors
+required_capability: hamming_vector_similarity_function
+ 
+row a = 1
+| eval similarity = round(v_hamming([1, 2, 3], [0, 1, 2]), 3) 
+| keep similarity
+;
+
+similarity:double
+4.0
+;
+
+similarityWithStats
+required_capability: hamming_vector_similarity_function
+
+from colors
+| eval similarity = round(v_hamming(rgb_vector, [0, 255, 255]), 3) 
+| stats avg = round(avg(similarity), 3), min = min(similarity), max = max(similarity)
+;
+
+avg:double | min:double | max:double
+13.322     | 0.0        | 24.0
+;
+
+similarityWithNull
+required_capability: hamming_vector_similarity_function
+required_capability: vector_similarity_functions_support_null
+
+from colors
+| eval similarity = v_hamming(rgb_vector, null) 
+| stats total_null = count(*) where similarity is null
+;
+
+total_null:long
+59
+;
+
+# TODO Need to implement a conversion function to convert a non-foldable row to a dense_vector
+similarityWithRow-Ignore
+required_capability: hamming_vector_similarity_function
+ 
+row vector = [1, 2, 3] 
+| eval similarity = round(v_hamming(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_hamming.md

@@ -24,6 +24,7 @@
 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.Hamming;
 import org.elasticsearch.xpack.esql.expression.function.vector.L1Norm;
 import org.elasticsearch.xpack.esql.expression.function.vector.L2Norm;
 import org.elasticsearch.xpack.esql.expression.function.vector.VectorSimilarityFunction.SimilarityEvaluatorFunction;
@@ -56,6 +57,9 @@ public static Iterable<Object[]> parameters() throws Exception {
         if (EsqlCapabilities.Cap.L2_NORM_VECTOR_SIMILARITY_FUNCTION.isEnabled()) {
             params.add(new Object[] { "v_l2_norm", (SimilarityEvaluatorFunction) L2Norm::calculateSimilarity });
         }
+        if (EsqlCapabilities.Cap.HAMMING_VECTOR_SIMILARITY_FUNCTION.isEnabled()) {
+            params.add(new Object[] { "v_hamming", (SimilarityEvaluatorFunction) Hamming::calculateSimilarity });
+        }
 
         return params;
     }