Merge branch '246-add-geo-vector-distance-type' into 'dev'

Add 'Geo' vector distance type #246

See merge request objectbox/objectbox-java!149

Author: greenrobot-team

CHANGELOG.md

@@ -9,6 +9,8 @@ For more insights into what changed in the ObjectBox C++ core, [check the Object
 - Android: require Android 5.0 (API level 21) or higher.
 - JVM: ObjectBox might crash on Windows when creating a BoxStore. To resolve this, make sure to update your JDK to the
   latest patch release (8.0.432+6, 11.0.25+9, 17.0.13+11 and 21.0.5+11-LTS are known to work).
+- Vector Search: add new `VectorDistanceType.GEO` distance type to perform vector searches on geographical coordinates.
+  This is particularly useful for location-based applications.
 
 ## 4.0.3 - 2024-10-15
 

objectbox-java-api/src/main/java/io/objectbox/annotation/VectorDistanceType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2024-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -49,6 +49,19 @@ public enum VectorDistanceType {
      */
     DOT_PRODUCT,
 
+    /**
+     * For geospatial coordinates, more specifically latitude and longitude pairs.
+     * <p>
+     * Note, the vector dimension should be 2, with the latitude being the first element and longitude the second.
+     * If the vector has more than 2 dimensions, only the first 2 dimensions are used.
+     * If the vector has fewer than 2 dimensions, the distance is always zero.
+     * <p>
+     * Internally, this uses haversine distance.
+     * <p>
+     * Value range: 0 km - 6371 * π km (approx. 20015.09 km; half the Earth's circumference)
+     */
+    GEO,
+
     /**
      * A custom dot product similarity measure that does not require the vectors to be normalized.
      * <p>

objectbox-java/src/main/java/io/objectbox/model/HnswDistanceType.java

@@ -44,6 +44,12 @@ private HnswDistanceType() { }
    * Value range (normalized vectors): 0.0 - 2.0 (0.0: same direction, 1.0: orthogonal, 2.0: opposite direction)
    */
   public static final short DotProduct = 3;
+  /**
+   * For geospatial coordinates aka latitude/longitude pairs.
+   * Note, that the vector dimension must be 2, with the latitude being the first element and longitude the second.
+   * Internally, this uses haversine distance.
+   */
+  public static final short Geo = 6;
   /**
    * A custom dot product similarity measure that does not require the vectors to be normalized.
    * Note: this is no replacement for cosine similarity (like DotProduct for normalized vectors is).
@@ -54,7 +60,7 @@ private HnswDistanceType() { }
    */
   public static final short DotProductNonNormalized = 10;
 
-  public static final String[] names = { "Unknown", "Euclidean", "Cosine", "DotProduct", "", "", "", "", "", "", "DotProductNonNormalized", };
+  public static final String[] names = { "Unknown", "Euclidean", "Cosine", "DotProduct", "", "", "Geo", "", "", "", "DotProductNonNormalized", };
 
   public static String name(int e) { return names[e]; }
 }