HNSW index: add find with score query methods

Author: greenrobot-team

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

@@ -0,0 +1,49 @@
+/*
+ * Copyright 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.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.objectbox.query;
+
+/**
+ * Wraps the ID of a matching object and a score when using {@link Query#findIdsWithScores}.
+ */
+public class IdWithScore {
+
+    private final long id;
+    private final double score;
+
+    // Note: this constructor is called by JNI, check before modifying/removing it.
+    public IdWithScore(long id, double score) {
+        this.id = id;
+        this.score = score;
+    }
+
+    /**
+     * The object ID.
+     */
+    public long getId() {
+        return id;
+    }
+
+    /**
+     * The query score for the {@link #getId() id}.
+     * <p>
+     * The query score indicates some quality measurement. E.g. for vector nearest neighbor searches, the score is the
+     * distance to the given vector.
+     */
+    public double getScore() {
+        return score;
+    }
+}

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

@@ -0,0 +1,49 @@
+/*
+ * Copyright 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.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.objectbox.query;
+
+/**
+ * Wraps a matching object and a score when using {@link Query#findWithScores}.
+ */
+public class ObjectWithScore<T> {
+
+    private final T object;
+    private final double score;
+
+    // Note: this constructor is called by JNI, check before modifying/removing it.
+    public ObjectWithScore(T object, double score) {
+        this.object = object;
+        this.score = score;
+    }
+
+    /**
+     * The object.
+     */
+    public T getObject() {
+        return object;
+    }
+
+    /**
+     * The query score for the {@link #getObject() object}.
+     * <p>
+     * The query score indicates some quality measurement. E.g. for vector nearest neighbor searches, the score is the
+     * distance to the given vector.
+     */
+    public double getScore() {
+        return score;
+    }
+}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2020 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.
@@ -31,6 +31,7 @@
 import io.objectbox.BoxStore;
 import io.objectbox.InternalAccess;
 import io.objectbox.Property;
+import io.objectbox.annotation.HnswIndex;
 import io.objectbox.exception.NonUniqueResultException;
 import io.objectbox.reactive.DataObserver;
 import io.objectbox.reactive.DataSubscriptionList;
@@ -71,6 +72,10 @@ public class Query<T> implements Closeable {
 
     native long[] nativeFindIds(long handle, long cursorHandle, long offset, long limit);
 
+    native List<ObjectWithScore<T>> nativeFindWithScores(long handle, long cursorHandle, long offset, long limit);
+
+    native List<IdWithScore> nativeFindIdsWithScores(long handle, long cursorHandle, long offset, long limit);
+
     native long nativeCount(long handle, long cursorHandle);
 
     native long nativeRemove(long handle, long cursorHandle);
@@ -380,6 +385,68 @@ public LazyList<T> findLazyCached() {
         return new LazyList<>(box, findIds(), true);
     }
 
+    /**
+     * Like {@link #findIdsWithScores()}, but can skip and limit results.
+     * <p>
+     * Use to get a slice of the whole result, e.g. for "result paging".
+     *
+     * @param offset If greater than 0, skips this many results.
+     * @param limit If greater than 0, returns at most this many results.
+     */
+    @Nonnull
+    public List<IdWithScore> findIdsWithScores(final long offset, final long limit) {
+        checkOpen();
+        return box.internalCallWithReaderHandle(cursorHandle -> nativeFindIdsWithScores(handle, cursorHandle, offset, limit));
+    }
+
+    /**
+     * Finds IDs of objects matching the query associated to their query score (e.g. distance in NN search).
+     * <p>
+     * This only works on objects with a property with an {@link HnswIndex}.
+     *
+     * @return A list of {@link IdWithScore} that wraps IDs of matching objects and their score, sorted by score in
+     * ascending order.
+     */
+    @Nonnull
+    public List<IdWithScore> findIdsWithScores() {
+        return findIdsWithScores(0, 0);
+    }
+
+    /**
+     * Like {@link #findWithScores()}, but can skip and limit results.
+     * <p>
+     * Use to get a slice of the whole result, e.g. for "result paging".
+     *
+     * @param offset If greater than 0, skips this many results.
+     * @param limit If greater than 0, returns at most this many results.
+     */
+    @Nonnull
+    public List<ObjectWithScore<T>> findWithScores(final long offset, final long limit) {
+        ensureNoFilterNoComparator();
+        return callInReadTx(() -> {
+            List<ObjectWithScore<T>> results = nativeFindWithScores(handle, cursorHandle(), offset, limit);
+            if (eagerRelations != null) {
+                for (int i = 0; i < results.size(); i++) {
+                    resolveEagerRelationForNonNullEagerRelations(results.get(i).getObject(), i);
+                }
+            }
+            return results;
+        });
+    }
+
+    /**
+     * Finds objects matching the query associated to their query score (e.g. distance in NN search).
+     * <p>
+     * This only works on objects with a property with an {@link HnswIndex}.
+     *
+     * @return A list of {@link ObjectWithScore} that wraps matching objects and their score, sorted by score in
+     * ascending order.
+     */
+    @Nonnull
+    public List<ObjectWithScore<T>> findWithScores() {
+        return findWithScores(0, 0);
+    }
+
     /**
      * Creates a {@link PropertyQuery} for the given property.
      * <p>