From d68175ebf5ed8babf501607f9c78fd81798d1830 Mon Sep 17 00:00:00 2001 From: Stephen Xie Date: Fri, 13 Dec 2024 13:18:32 -0500 Subject: [PATCH] Return id(s) when calling Index::addItem and Index::addItems in Java bindings (#94) * Return id(s) when calling Index::addItem and Index::addItems in Java bindings * Update Java docs * Update tests * Update java/com_spotify_voyager_jni_Index.cpp Co-authored-by: Peter Sobot * Update java/com_spotify_voyager_jni_Index.cpp Co-authored-by: Peter Sobot * Format C++ * Return a non-void value to ensure every possible control path has a return statement --------- Co-authored-by: Peter Sobot --- docs/java/apidocs/allclasses-index.html | 4 +- docs/java/apidocs/allpackages-index.html | 4 +- .../voyager/jni/Index.QueryResults.html | 4 +- .../spotify/voyager/jni/Index.SpaceType.html | 4 +- .../voyager/jni/Index.StorageDataType.html | 4 +- .../com/spotify/voyager/jni/Index.html | 34 +++++++----- .../voyager/jni/StringIndex.QueryResults.html | 4 +- .../com/spotify/voyager/jni/StringIndex.html | 4 +- .../jni/class-use/Index.QueryResults.html | 4 +- .../jni/class-use/Index.SpaceType.html | 4 +- .../jni/class-use/Index.StorageDataType.html | 4 +- .../spotify/voyager/jni/class-use/Index.html | 4 +- .../class-use/StringIndex.QueryResults.html | 4 +- .../voyager/jni/class-use/StringIndex.html | 4 +- .../jni/exception/RecallException.html | 4 +- .../exception/class-use/RecallException.html | 4 +- .../jni/exception/package-summary.html | 4 +- .../voyager/jni/exception/package-tree.html | 4 +- .../voyager/jni/exception/package-use.html | 4 +- .../spotify/voyager/jni/package-summary.html | 4 +- .../com/spotify/voyager/jni/package-tree.html | 4 +- .../com/spotify/voyager/jni/package-use.html | 4 +- .../voyager/jni/utils/JniLibExtractor.html | 4 +- .../spotify/voyager/jni/utils/TinyJson.html | 4 +- .../jni/utils/class-use/JniLibExtractor.html | 4 +- .../voyager/jni/utils/class-use/TinyJson.html | 4 +- .../voyager/jni/utils/package-summary.html | 4 +- .../voyager/jni/utils/package-tree.html | 4 +- .../voyager/jni/utils/package-use.html | 4 +- .../com/spotify/voyager/package-summary.html | 4 +- .../com/spotify/voyager/package-tree.html | 4 +- .../com/spotify/voyager/package-use.html | 4 +- docs/java/apidocs/help-doc.html | 4 +- docs/java/apidocs/index-all.html | 6 +-- docs/java/apidocs/index.html | 4 +- docs/java/apidocs/overview-summary.html | 4 +- docs/java/apidocs/overview-tree.html | 4 +- docs/java/apidocs/serialized-form.html | 4 +- java/com_spotify_voyager_jni_Index.cpp | 52 +++++++++++++------ java/com_spotify_voyager_jni_Index.h | 23 ++++---- .../java/com/spotify/voyager/jni/Index.java | 16 ++++-- .../com/spotify/voyager/jni/IndexTest.java | 6 ++- 42 files changed, 162 insertions(+), 119 deletions(-) diff --git a/docs/java/apidocs/allclasses-index.html b/docs/java/apidocs/allclasses-index.html index 617f9710..a8678393 100644 --- a/docs/java/apidocs/allclasses-index.html +++ b/docs/java/apidocs/allclasses-index.html @@ -1,11 +1,11 @@ - + All Classes and Interfaces (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/allpackages-index.html b/docs/java/apidocs/allpackages-index.html index 74958e9b..ff4b3523 100644 --- a/docs/java/apidocs/allpackages-index.html +++ b/docs/java/apidocs/allpackages-index.html @@ -1,11 +1,11 @@ - + All Packages (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/Index.QueryResults.html b/docs/java/apidocs/com/spotify/voyager/jni/Index.QueryResults.html index 9fe1e888..a3bb50f8 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/Index.QueryResults.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/Index.QueryResults.html @@ -1,11 +1,11 @@ - + Index.QueryResults (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/Index.SpaceType.html b/docs/java/apidocs/com/spotify/voyager/jni/Index.SpaceType.html index 4222ec98..29a137dd 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/Index.SpaceType.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/Index.SpaceType.html @@ -1,11 +1,11 @@ - + Index.SpaceType (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/Index.StorageDataType.html b/docs/java/apidocs/com/spotify/voyager/jni/Index.StorageDataType.html index 0ee4065b..1a16fa83 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/Index.StorageDataType.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/Index.StorageDataType.html @@ -1,11 +1,11 @@ - + Index.StorageDataType (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/Index.html b/docs/java/apidocs/com/spotify/voyager/jni/Index.html index 24589aa8..71937f1a 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/Index.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/Index.html @@ -1,11 +1,11 @@ - + Index (voyager 2.0.10 API) - + @@ -175,29 +175,29 @@

Method Summary

Modifier and Type
Method
Description
-
void
+
long
addItem(float[] vector)
Add an item (a vector) to this Index.
-
void
+
long
addItem(float[] vector, long id)
Add an item (a vector) to this Index with the provided identifier.
-
void
+
long[]
addItems(float[][] vectors, int numThreads)
Add multiple items (vectors) to this Index.
-
void
+
long[]
addItems(float[][] vectors, long[] ids, int numThreads)
-
Add multiple items (vectors) to this Index.
+
Add multiple items (vectors) to this Index with the provided identifiers.
byte[]
asBytes()
@@ -669,12 +669,14 @@

asBytes

  • addItem

    -
    public void addItem(float[] vector)
    +
    public long addItem(float[] vector)
    Add an item (a vector) to this Index. The item will automatically be given an identifier equal to the return value of getNumElements().
    Parameters:
    vector - The vector to add to the index.
    +
    Returns:
    +
    The long ID that was assigned to this vector.
    Throws:
    RuntimeException - If the provided vector does not contain exactly getNumDimensions() dimensions.
    @@ -683,13 +685,15 @@

    addItem

  • addItem

    -
    public void addItem(float[] vector, +
    public long addItem(float[] vector, long id)
    Add an item (a vector) to this Index with the provided identifier.
    Parameters:
    vector - The vector to add to the index.
    id - The 64-bit integer denoting the identifier of this vector.
    +
    Returns:
    +
    The long ID that was assigned to this vector.
    Throws:
    RuntimeException - If the provided vector does not contain exactly getNumDimensions() dimensions.
    @@ -698,7 +702,7 @@

    addItem

  • addItems

    -
    public void addItems(float[][] vectors, +
    public long[] addItems(float[][] vectors, int numThreads)
    Add multiple items (vectors) to this Index.
    @@ -706,6 +710,9 @@

    addItems

    vectors - The vectors to add to the index.
    numThreads - The number of threads to use when adding the provided vectors. If -1 (the default), the number of CPUs available on the current machine will be used.
    +
    Returns:
    +
    The auto-generated long IDs that were assigned to the provided vectors, in the + same order as the provided vectors.
    Throws:
    RuntimeException - If any of the provided vectors do not contain exactly getNumDimensions() dimensions.
    @@ -714,10 +721,10 @@

    addItems

  • addItems

    -
    public void addItems(float[][] vectors, +
    public long[] addItems(float[][] vectors, long[] ids, int numThreads)
    -
    Add multiple items (vectors) to this Index.
    +
    Add multiple items (vectors) to this Index with the provided identifiers.
    Parameters:
    vectors - The vectors to add to the index.
    @@ -727,6 +734,9 @@

    addItems

    causes a temporary C++ thread pool to be used. Instead of calling addItems(float[][],int) in a tight loop, consider passing more data to each addItems(float[][],int) call instead to reduce overhead. +
    Returns:
    +
    The long IDs that were assigned to the provided vectors, in the same order as + the provided vectors.
    Throws:
    RuntimeException - If any of the provided vectors do not contain exactly getNumDimensions() dimensions.
    RuntimeException - If the list of IDs does not have the same length as the list of diff --git a/docs/java/apidocs/com/spotify/voyager/jni/StringIndex.QueryResults.html b/docs/java/apidocs/com/spotify/voyager/jni/StringIndex.QueryResults.html index 91a97834..bdff9550 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/StringIndex.QueryResults.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/StringIndex.QueryResults.html @@ -1,11 +1,11 @@ - + StringIndex.QueryResults (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/StringIndex.html b/docs/java/apidocs/com/spotify/voyager/jni/StringIndex.html index 1bdb1d68..f7d37526 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/StringIndex.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/StringIndex.html @@ -1,11 +1,11 @@ - + StringIndex (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.QueryResults.html b/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.QueryResults.html index 134ba344..e08b2943 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.QueryResults.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.QueryResults.html @@ -1,11 +1,11 @@ - + Uses of Class com.spotify.voyager.jni.Index.QueryResults (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.SpaceType.html b/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.SpaceType.html index 8a4bb7ee..9814a945 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.SpaceType.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.SpaceType.html @@ -1,11 +1,11 @@ - + Uses of Enum com.spotify.voyager.jni.Index.SpaceType (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.StorageDataType.html b/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.StorageDataType.html index 3235cc74..996c02a5 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.StorageDataType.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.StorageDataType.html @@ -1,11 +1,11 @@ - + Uses of Enum com.spotify.voyager.jni.Index.StorageDataType (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.html b/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.html index 75d2d58f..c7b5d10c 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/class-use/Index.html @@ -1,11 +1,11 @@ - + Uses of Class com.spotify.voyager.jni.Index (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/class-use/StringIndex.QueryResults.html b/docs/java/apidocs/com/spotify/voyager/jni/class-use/StringIndex.QueryResults.html index d6ffcfcd..fbdedb84 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/class-use/StringIndex.QueryResults.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/class-use/StringIndex.QueryResults.html @@ -1,11 +1,11 @@ - + Uses of Class com.spotify.voyager.jni.StringIndex.QueryResults (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/class-use/StringIndex.html b/docs/java/apidocs/com/spotify/voyager/jni/class-use/StringIndex.html index cb1e5afe..c8b65d69 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/class-use/StringIndex.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/class-use/StringIndex.html @@ -1,11 +1,11 @@ - + Uses of Class com.spotify.voyager.jni.StringIndex (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/exception/RecallException.html b/docs/java/apidocs/com/spotify/voyager/jni/exception/RecallException.html index c9c6ac5f..819f4cdf 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/exception/RecallException.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/exception/RecallException.html @@ -1,11 +1,11 @@ - + RecallException (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/exception/class-use/RecallException.html b/docs/java/apidocs/com/spotify/voyager/jni/exception/class-use/RecallException.html index c463492b..854c2970 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/exception/class-use/RecallException.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/exception/class-use/RecallException.html @@ -1,11 +1,11 @@ - + Uses of Class com.spotify.voyager.jni.exception.RecallException (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/exception/package-summary.html b/docs/java/apidocs/com/spotify/voyager/jni/exception/package-summary.html index dd496855..1b718990 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/exception/package-summary.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/exception/package-summary.html @@ -1,11 +1,11 @@ - + com.spotify.voyager.jni.exception (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/exception/package-tree.html b/docs/java/apidocs/com/spotify/voyager/jni/exception/package-tree.html index 926077e4..0734888b 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/exception/package-tree.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/exception/package-tree.html @@ -1,11 +1,11 @@ - + com.spotify.voyager.jni.exception Class Hierarchy (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/exception/package-use.html b/docs/java/apidocs/com/spotify/voyager/jni/exception/package-use.html index 7aeaf74b..1fb88251 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/exception/package-use.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/exception/package-use.html @@ -1,11 +1,11 @@ - + Uses of Package com.spotify.voyager.jni.exception (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/package-summary.html b/docs/java/apidocs/com/spotify/voyager/jni/package-summary.html index b15f706b..bac0688f 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/package-summary.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/package-summary.html @@ -1,11 +1,11 @@ - + com.spotify.voyager.jni (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/package-tree.html b/docs/java/apidocs/com/spotify/voyager/jni/package-tree.html index db2ea1c8..94fc30df 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/package-tree.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/package-tree.html @@ -1,11 +1,11 @@ - + com.spotify.voyager.jni Class Hierarchy (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/package-use.html b/docs/java/apidocs/com/spotify/voyager/jni/package-use.html index 95cba3c8..3daf2493 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/package-use.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/package-use.html @@ -1,11 +1,11 @@ - + Uses of Package com.spotify.voyager.jni (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/utils/JniLibExtractor.html b/docs/java/apidocs/com/spotify/voyager/jni/utils/JniLibExtractor.html index 81ad1cd4..2d673230 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/utils/JniLibExtractor.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/utils/JniLibExtractor.html @@ -1,11 +1,11 @@ - + JniLibExtractor (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/utils/TinyJson.html b/docs/java/apidocs/com/spotify/voyager/jni/utils/TinyJson.html index 0ae8859b..2e035460 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/utils/TinyJson.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/utils/TinyJson.html @@ -1,11 +1,11 @@ - + TinyJson (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/utils/class-use/JniLibExtractor.html b/docs/java/apidocs/com/spotify/voyager/jni/utils/class-use/JniLibExtractor.html index 8c3ff6b8..e42e18cb 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/utils/class-use/JniLibExtractor.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/utils/class-use/JniLibExtractor.html @@ -1,11 +1,11 @@ - + Uses of Class com.spotify.voyager.jni.utils.JniLibExtractor (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/utils/class-use/TinyJson.html b/docs/java/apidocs/com/spotify/voyager/jni/utils/class-use/TinyJson.html index d163b1e9..34ca0298 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/utils/class-use/TinyJson.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/utils/class-use/TinyJson.html @@ -1,11 +1,11 @@ - + Uses of Class com.spotify.voyager.jni.utils.TinyJson (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/utils/package-summary.html b/docs/java/apidocs/com/spotify/voyager/jni/utils/package-summary.html index 9b9f8227..0fb717a3 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/utils/package-summary.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/utils/package-summary.html @@ -1,11 +1,11 @@ - + com.spotify.voyager.jni.utils (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/utils/package-tree.html b/docs/java/apidocs/com/spotify/voyager/jni/utils/package-tree.html index 33970e54..5eca6f2f 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/utils/package-tree.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/utils/package-tree.html @@ -1,11 +1,11 @@ - + com.spotify.voyager.jni.utils Class Hierarchy (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/jni/utils/package-use.html b/docs/java/apidocs/com/spotify/voyager/jni/utils/package-use.html index 343b2c63..6bd171dd 100644 --- a/docs/java/apidocs/com/spotify/voyager/jni/utils/package-use.html +++ b/docs/java/apidocs/com/spotify/voyager/jni/utils/package-use.html @@ -1,11 +1,11 @@ - + Uses of Package com.spotify.voyager.jni.utils (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/package-summary.html b/docs/java/apidocs/com/spotify/voyager/package-summary.html index eb054743..ad813286 100644 --- a/docs/java/apidocs/com/spotify/voyager/package-summary.html +++ b/docs/java/apidocs/com/spotify/voyager/package-summary.html @@ -1,11 +1,11 @@ - + com.spotify.voyager (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/package-tree.html b/docs/java/apidocs/com/spotify/voyager/package-tree.html index 8e24ec09..bcd961a5 100644 --- a/docs/java/apidocs/com/spotify/voyager/package-tree.html +++ b/docs/java/apidocs/com/spotify/voyager/package-tree.html @@ -1,11 +1,11 @@ - + com.spotify.voyager Class Hierarchy (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/com/spotify/voyager/package-use.html b/docs/java/apidocs/com/spotify/voyager/package-use.html index 6fea9e9a..5ca882d4 100644 --- a/docs/java/apidocs/com/spotify/voyager/package-use.html +++ b/docs/java/apidocs/com/spotify/voyager/package-use.html @@ -1,11 +1,11 @@ - + Uses of Package com.spotify.voyager (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/help-doc.html b/docs/java/apidocs/help-doc.html index 02b18c69..dd00e6b3 100644 --- a/docs/java/apidocs/help-doc.html +++ b/docs/java/apidocs/help-doc.html @@ -1,11 +1,11 @@ - + API Help (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/index-all.html b/docs/java/apidocs/index-all.html index 1807baf0..d50c8284 100644 --- a/docs/java/apidocs/index-all.html +++ b/docs/java/apidocs/index-all.html @@ -1,11 +1,11 @@ - + Index (voyager 2.0.10 API) - + @@ -72,7 +72,7 @@

    A

    addItems(float[][], long[], int) - Method in class com.spotify.voyager.jni.Index
    -
    Add multiple items (vectors) to this Index.
    +
    Add multiple items (vectors) to this Index with the provided identifiers.
    addItems(Map<String, List<Float>>) - Method in class com.spotify.voyager.jni.StringIndex
     
    diff --git a/docs/java/apidocs/index.html b/docs/java/apidocs/index.html index fa65563a..3eb6c68b 100644 --- a/docs/java/apidocs/index.html +++ b/docs/java/apidocs/index.html @@ -1,11 +1,11 @@ - + Overview (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/overview-summary.html b/docs/java/apidocs/overview-summary.html index 07a1d579..68ea68d7 100644 --- a/docs/java/apidocs/overview-summary.html +++ b/docs/java/apidocs/overview-summary.html @@ -1,11 +1,11 @@ - + voyager 2.0.10 API - + diff --git a/docs/java/apidocs/overview-tree.html b/docs/java/apidocs/overview-tree.html index af4f13d5..c47a4562 100644 --- a/docs/java/apidocs/overview-tree.html +++ b/docs/java/apidocs/overview-tree.html @@ -1,11 +1,11 @@ - + Class Hierarchy (voyager 2.0.10 API) - + diff --git a/docs/java/apidocs/serialized-form.html b/docs/java/apidocs/serialized-form.html index 3329cbd2..f0e41597 100644 --- a/docs/java/apidocs/serialized-form.html +++ b/docs/java/apidocs/serialized-form.html @@ -1,11 +1,11 @@ - + Serialized Form (voyager 2.0.10 API) - + diff --git a/java/com_spotify_voyager_jni_Index.cpp b/java/com_spotify_voyager_jni_Index.cpp index d03cba12..a5035882 100644 --- a/java/com_spotify_voyager_jni_Index.cpp +++ b/java/com_spotify_voyager_jni_Index.cpp @@ -343,57 +343,79 @@ void Java_com_spotify_voyager_jni_Index_nativeConstructor( } } -void Java_com_spotify_voyager_jni_Index_addItem___3F(JNIEnv *env, jobject self, - jfloatArray vector) { +jlong Java_com_spotify_voyager_jni_Index_addItem___3F(JNIEnv *env, jobject self, + jfloatArray vector) { try { std::shared_ptr index = getHandle(env, self); - index->addItem(toStdVector(env, vector), {}); + return index->addItem(toStdVector(env, vector), {}); } catch (std::exception const &e) { if (!env->ExceptionCheck()) { env->ThrowNew(env->FindClass("java/lang/RuntimeException"), e.what()); } } + return -1; } -void Java_com_spotify_voyager_jni_Index_addItem___3FJ(JNIEnv *env, jobject self, - jfloatArray vector, - jlong id) { +jlong Java_com_spotify_voyager_jni_Index_addItem___3FJ(JNIEnv *env, + jobject self, + jfloatArray vector, + jlong id) { try { std::shared_ptr index = getHandle(env, self); - index->addItem(toStdVector(env, vector), {id}); + return index->addItem(toStdVector(env, vector), {id}); } catch (std::exception const &e) { if (!env->ExceptionCheck()) { env->ThrowNew(env->FindClass("java/lang/RuntimeException"), e.what()); } } + return -1; } -void Java_com_spotify_voyager_jni_Index_addItems___3_3FI(JNIEnv *env, - jobject self, - jobjectArray vectors, - jint numThreads) { +jlongArray Java_com_spotify_voyager_jni_Index_addItems___3_3FI( + JNIEnv *env, jobject self, jobjectArray vectors, jint numThreads) { try { std::shared_ptr index = getHandle(env, self); - index->addItems(toNDArray(env, vectors), {}, numThreads); + std::vector nativeIds = + index->addItems(toNDArray(env, vectors), {}, numThreads); + + // Allocate a Java long array for the IDs: + static_assert( + sizeof(hnswlib::labeltype) == sizeof(jlong), + "addItems expects hnswlib::labeltype to be a 64-bit integer."); + jlongArray javaIds = env->NewLongArray(nativeIds.size()); + env->SetLongArrayRegion(javaIds, 0, nativeIds.size(), + (jlong *)nativeIds.data()); + return javaIds; } catch (std::exception const &e) { if (!env->ExceptionCheck()) { env->ThrowNew(env->FindClass("java/lang/RuntimeException"), e.what()); } } + return nullptr; } -void Java_com_spotify_voyager_jni_Index_addItems___3_3F_3JI( +jlongArray Java_com_spotify_voyager_jni_Index_addItems___3_3F_3JI( JNIEnv *env, jobject self, jobjectArray vectors, jlongArray ids, jint numThreads) { try { std::shared_ptr index = getHandle(env, self); - index->addItems(toNDArray(env, vectors), toUnsignedStdVector(env, ids), - numThreads); + std::vector nativeIds = index->addItems( + toNDArray(env, vectors), toUnsignedStdVector(env, ids), numThreads); + + // Allocate a Java long array for the IDs: + static_assert( + sizeof(hnswlib::labeltype) == sizeof(jlong), + "addItems expects hnswlib::labeltype to be a 64-bit integer."); + jlongArray javaIds = env->NewLongArray(nativeIds.size()); + env->SetLongArrayRegion(javaIds, 0, nativeIds.size(), + (jlong *)nativeIds.data()); + return javaIds; } catch (std::exception const &e) { if (!env->ExceptionCheck()) { env->ThrowNew(env->FindClass("java/lang/RuntimeException"), e.what()); } } + return nullptr; } //////////////////////////////////////////////////////////////////////////////////////////////////// diff --git a/java/com_spotify_voyager_jni_Index.h b/java/com_spotify_voyager_jni_Index.h index 25587917..1c0c1320 100644 --- a/java/com_spotify_voyager_jni_Index.h +++ b/java/com_spotify_voyager_jni_Index.h @@ -132,34 +132,37 @@ Java_com_spotify_voyager_jni_Index_saveIndex__Ljava_io_OutputStream_2(JNIEnv *, /* * Class: com_spotify_voyager_jni_Index * Method: addItem - * Signature: ([F)V + * Signature: ([F)J */ -JNIEXPORT void JNICALL +JNIEXPORT jlong JNICALL Java_com_spotify_voyager_jni_Index_addItem___3F(JNIEnv *, jobject, jfloatArray); /* * Class: com_spotify_voyager_jni_Index * Method: addItem - * Signature: ([FJ)V + * Signature: ([FJ)J */ -JNIEXPORT void JNICALL Java_com_spotify_voyager_jni_Index_addItem___3FJ( +JNIEXPORT jlong JNICALL Java_com_spotify_voyager_jni_Index_addItem___3FJ( JNIEnv *, jobject, jfloatArray, jlong); /* * Class: com_spotify_voyager_jni_Index * Method: addItems - * Signature: ([[FI)V + * Signature: ([[FI)[J */ -JNIEXPORT void JNICALL Java_com_spotify_voyager_jni_Index_addItems___3_3FI( - JNIEnv *, jobject, jobjectArray, jint); +JNIEXPORT jlongArray JNICALL +Java_com_spotify_voyager_jni_Index_addItems___3_3FI(JNIEnv *, jobject, + jobjectArray, jint); /* * Class: com_spotify_voyager_jni_Index * Method: addItems - * Signature: ([[F[JI)V + * Signature: ([[F[JI)[J */ -JNIEXPORT void JNICALL Java_com_spotify_voyager_jni_Index_addItems___3_3F_3JI( - JNIEnv *, jobject, jobjectArray, jlongArray, jint); +JNIEXPORT jlongArray JNICALL +Java_com_spotify_voyager_jni_Index_addItems___3_3F_3JI(JNIEnv *, jobject, + jobjectArray, jlongArray, + jint); /* * Class: com_spotify_voyager_jni_Index diff --git a/java/src/main/java/com/spotify/voyager/jni/Index.java b/java/src/main/java/com/spotify/voyager/jni/Index.java index f634a092..8bc7fdea 100644 --- a/java/src/main/java/com/spotify/voyager/jni/Index.java +++ b/java/src/main/java/com/spotify/voyager/jni/Index.java @@ -437,20 +437,22 @@ public byte[] asBytes() { * identifier equal to the return value of {@link Index#getNumElements()}. * * @param vector The vector to add to the index. + * @return The {@link long} ID that was assigned to this vector. * @throws RuntimeException If the provided vector does not contain exactly {@link * Index#getNumDimensions()} dimensions. */ - public native void addItem(float[] vector); + public native long addItem(float[] vector); /** * Add an item (a vector) to this {@link Index} with the provided identifier. * * @param vector The vector to add to the index. * @param id The 64-bit integer denoting the identifier of this vector. + * @return The {@link long} ID that was assigned to this vector. * @throws RuntimeException If the provided vector does not contain exactly {@link * Index#getNumDimensions()} dimensions. */ - public native void addItem(float[] vector, long id); + public native long addItem(float[] vector, long id); /** * Add multiple items (vectors) to this {@link Index}. @@ -458,13 +460,15 @@ public byte[] asBytes() { * @param vectors The vectors to add to the index. * @param numThreads The number of threads to use when adding the provided vectors. If -1 (the * default), the number of CPUs available on the current machine will be used. + * @return The auto-generated {@link long} IDs that were assigned to the provided vectors, in the + * same order as the provided vectors. * @throws RuntimeException If any of the provided vectors do not contain exactly {@link * Index#getNumDimensions()} dimensions. */ - public native void addItems(float[][] vectors, int numThreads); + public native long[] addItems(float[][] vectors, int numThreads); /** - * Add multiple items (vectors) to this {@link Index}. + * Add multiple items (vectors) to this {@link Index} with the provided identifiers. * * @param vectors The vectors to add to the index. * @param ids The 64-bit identifiers that correspond with each of the provided vectors. @@ -473,12 +477,14 @@ public byte[] asBytes() { * causes a temporary C++ thread pool to be used. Instead of calling {@link addItems} in a * tight loop, consider passing more data to each {@link addItems} call instead to reduce * overhead. + * @return The {@link long} IDs that were assigned to the provided vectors, in the same order as + * the provided vectors. * @throws RuntimeException If any of the provided vectors do not contain exactly {@link * Index#getNumDimensions()} dimensions. * @throws RuntimeException If the list of IDs does not have the same length as the list of * provided vectors. */ - public native void addItems(float[][] vectors, long[] ids, int numThreads); + public native long[] addItems(float[][] vectors, long[] ids, int numThreads); /** * Get the vector for the provided identifier. diff --git a/java/src/test/java/com/spotify/voyager/jni/IndexTest.java b/java/src/test/java/com/spotify/voyager/jni/IndexTest.java index 8963b6b2..889d350d 100644 --- a/java/src/test/java/com/spotify/voyager/jni/IndexTest.java +++ b/java/src/test/java/com/spotify/voyager/jni/IndexTest.java @@ -122,10 +122,12 @@ private void runTestWith( if (testSingleVectorMethods) { for (int i = 0; i < inputData.length; i++) { - index.addItem(inputData[i], ids[i]); + long addedId = index.addItem(inputData[i], ids[i]); + assertEquals(ids[i], addedId); } } else { - index.addItems(inputData, ids, -1); + long[] addedIds = index.addItems(inputData, ids, -1); + assertArrayEquals(ids, addedIds); } // Test property methods