HNSW index: add nearest neighbor query condition

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/Property.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2019 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2024 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.
@@ -22,6 +22,7 @@
 
 import javax.annotation.Nullable;
 
+import io.objectbox.annotation.HnswIndex;
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.converter.PropertyConverter;
 import io.objectbox.exception.DbException;
@@ -33,6 +34,7 @@
 import io.objectbox.query.PropertyQueryConditionImpl.LongArrayCondition;
 import io.objectbox.query.PropertyQueryConditionImpl.LongCondition;
 import io.objectbox.query.PropertyQueryConditionImpl.LongLongCondition;
+import io.objectbox.query.PropertyQueryConditionImpl.NearestNeighborCondition;
 import io.objectbox.query.PropertyQueryConditionImpl.NullCondition;
 import io.objectbox.query.PropertyQueryConditionImpl.StringArrayCondition;
 import io.objectbox.query.PropertyQueryConditionImpl.StringCondition;
@@ -302,6 +304,22 @@ public PropertyQueryCondition<ENTITY> between(double lowerBoundary, double upper
                 lowerBoundary, upperBoundary);
     }
 
+    /**
+     * Performs an approximate nearest neighbor (ANN) search to find objects near to the given {@code queryVector}.
+     * <p>
+     * This requires the vector property to have an {@link HnswIndex}.
+     * <p>
+     * The dimensions of the query vector should be at least the dimensions of this vector property.
+     * <p>
+     * Use {@code maxResultCount} to set the maximum number of objects to return by the ANN condition. Hint: it can also
+     * be used as the "ef" HNSW parameter to increase the search quality in combination with a query limit. For example,
+     * use maxResultCount of 100 with a Query limit of 10 to have 10 results that are of potentially better quality than
+     * just passing in 10 for maxResultCount (quality/performance tradeoff).
+     */
+    public PropertyQueryCondition<ENTITY> nearestNeighborsF32(float[] queryVector, int maxResultCount) {
+        return new NearestNeighborCondition<>(this, queryVector, maxResultCount);
+    }
+
     /** Creates an "equal ('=')" condition for this property. */
     public PropertyQueryCondition<ENTITY> equal(Date value) {
         return new LongCondition<>(this, LongCondition.Operation.EQUAL, value);

objectbox-java/src/main/java/io/objectbox/query/PropertyQueryConditionImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2021 ObjectBox Ltd. All rights reserved.
+ * Copyright 2020-2024 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.
@@ -458,4 +458,24 @@ void applyCondition(QueryBuilder<T> builder) {
             }
         }
     }
+
+    /**
+     * Conditions for properties with an {@link io.objectbox.annotation.HnswIndex}.
+     */
+    public static class NearestNeighborCondition<T> extends PropertyQueryConditionImpl<T> {
+
+        private final float[] queryVector;
+        private final int maxResultCount;
+
+        public NearestNeighborCondition(Property<T> property, float[] queryVector, int maxResultCount) {
+            super(property);
+            this.queryVector = queryVector;
+            this.maxResultCount = maxResultCount;
+        }
+
+        @Override
+        void applyCondition(QueryBuilder<T> builder) {
+            builder.nearestNeighborsF32(property, queryVector, maxResultCount);
+        }
+    }
 }

objectbox-java/src/main/java/io/objectbox/query/QueryBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2018 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2024 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.
@@ -206,6 +206,8 @@ private native long nativeRelationCount(long handle, long storeHandle, int relat
 
     private native long nativeBetween(long handle, int propertyId, double value1, double value2);
 
+    private native long nativeNearestNeighborsF32(long handle, int propertyId, float[] queryVector, int maxResultCount);
+
     // ------------------------------ Bytes ------------------------------
 
     private native long nativeEqual(long handle, int propertyId, byte[] value);
@@ -896,6 +898,12 @@ public QueryBuilder<T> between(Property<T> property, double value1, double value
         return this;
     }
 
+    QueryBuilder<T> nearestNeighborsF32(Property<T> property, float[] queryVector, int maxResultCount) {
+        verifyHandle();
+        checkCombineCondition(nativeNearestNeighborsF32(handle, property.getId(), queryVector, maxResultCount));
+        return this;
+    }
+
     ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
     //                                                 Bytes
     ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////