From 4a4512564853a32550eea185c445cf2ff9578da9 Mon Sep 17 00:00:00 2001 From: Igor Motov Date: Tue, 8 Sep 2026 10:53:25 -1000 Subject: [PATCH] Sync up API docs with code (#2561) Unfortunately, when #2547 was merged, the docs had already managed to drift from the code. This commit catches them up. Authors: - Igor Motov (https://github.com/imotov) Approvers: - Corey J. Nolet (https://github.com/cjnolet) URL: https://github.com/NVIDIA/cuvs/pull/2561 --- fern/pages/c_api/c-api-neighbors-vamana.md | 3 +- .../java-api-com-nvidia-cuvs-cagraindex.md | 124 ++++++++++++------ ...va-api-com-nvidia-cuvs-spi-cuvsprovider.md | 123 +++++++---------- .../python_api/python-api-neighbors-vamana.md | 5 +- 4 files changed, 142 insertions(+), 113 deletions(-) diff --git a/fern/pages/c_api/c-api-neighbors-vamana.md b/fern/pages/c_api/c-api-neighbors-vamana.md index d70db45305..0f8c8e016c 100644 --- a/fern/pages/c_api/c-api-neighbors-vamana.md +++ b/fern/pages/c_api/c-api-neighbors-vamana.md @@ -178,7 +178,8 @@ The build uses the Vamana insertion-based algorithm to create the graph. The alg The following distance metrics are supported: -- L2 +- L2Expanded (sqeuclidean) +- L2SqrtExpanded (l2 / euclidean distance) Usage example: diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindex.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindex.md index 8c19be0b1b..0484513500 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindex.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindex.md @@ -29,7 +29,7 @@ public final void setDelegate(AutoCloseable delegate, long handleAddress) Internal wiring hook used by the Java wrapper implementation. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:33`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:34`_ ### isPresent @@ -39,7 +39,7 @@ public final boolean isPresent() Returns true when this view has a native handle. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:41`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:42`_ ### nativeHandleAddress @@ -49,7 +49,7 @@ public final long nativeHandleAddress() Internal accessor for native handle address. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:48`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:49`_ ### setDelegate @@ -59,7 +59,7 @@ public final void setDelegate(AutoCloseable delegate) Internal wiring hook used by the Java wrapper implementation. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:83`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:84`_ ### setDelegate @@ -69,7 +69,7 @@ public final void setDelegate(AutoCloseable delegate, long handleAddress) Internal wiring hook used by the Java wrapper implementation. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:90`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:91`_ ### isPresent @@ -79,7 +79,7 @@ public final boolean isPresent() Returns true when this handle owns native dataset storage. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:98`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:99`_ ### nativeHandleAddress @@ -89,7 +89,7 @@ public final long nativeHandleAddress() Internal accessor for native handle address. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:105`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:106`_ ### close @@ -99,7 +99,7 @@ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:105`_ Invokes the native destroy_cagra_index to de-allocate the CAGRA index -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:135`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:136`_ ### search @@ -120,7 +120,7 @@ CAGRA index. an instance of `SearchResults` containing the results -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:146`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:147`_ ### makePaddedDataset @@ -132,7 +132,7 @@ Create an owning padded dataset by allocating padded storage and copying `dataset`. Prefer this when the source matrix is not already padded to CAGRA's required row stride (e.g. unaligned dimensions). -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:153`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:154`_ ### makePaddedDatasetView @@ -144,7 +144,7 @@ Create a caller-owned padded dataset view handle from a matrix that is already padded to CAGRA's required row stride. For unpadded matrices use `#makePaddedDataset(CuVSMatrix)`. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:160`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:161`_ ### makeStandardDatasetView @@ -154,7 +154,7 @@ StandardDatasetView makeStandardDatasetView(CuVSMatrix dataset) throws Throwable Create a caller-owned standard dataset view handle from a matrix. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:163`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:164`_ ### updateDataset @@ -166,7 +166,7 @@ Update this index with a caller-provided padded device dataset view and leave it search-ready in padded-device layout. The caller retains ownership of the underlying padded storage and must keep it alive while this index uses it. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:170`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:171`_ ### updateDataset @@ -177,7 +177,7 @@ void updateDataset(PaddedDataset dataset) throws Throwable Update this index with a caller-owned padded device dataset. The dataset must remain alive while this index uses it. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:176`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:177`_ ### getGraph @@ -191,7 +191,7 @@ Returns the CAGRA graph a `CuVSDeviceMatrix` encapsulating the native int (uint32_t) array used to represent the cagra graph -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:183`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:184`_ ### getGraphDegree @@ -207,7 +207,21 @@ build truncated it. the built graph degree (`graph().extent(1)`) -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:192`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:193`_ + +### size + +```java +long size() +``` + +Returns the number of vectors in this index. + +**Returns** + +the number of rows of the indexed dataset + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:200`_ ### serialize @@ -224,7 +238,7 @@ for writing index bytes. | --- | --- | | `outputStream` | an instance of `OutputStream` to write the index bytes into | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:201`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:209`_ ### serialize @@ -242,7 +256,7 @@ for writing index bytes. | `outputStream` | an instance of `OutputStream` to write the index bytes into | | `bufferLength` | the length of buffer to use for writing bytes. Default value is 1024 | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:212`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:220`_ ### serialize @@ -260,7 +274,7 @@ for writing index bytes. | `outputStream` | an instance of `OutputStream` to write the index bytes into | | `tempFile` | an intermediate `Path` where CAGRA index is written temporarily | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:223`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:231`_ ### serialize @@ -279,7 +293,7 @@ and path to the intermediate temporary file. | `tempFile` | an intermediate `Path` where CAGRA index is written temporarily | | `bufferLength` | the length of buffer to use for writing bytes. Default value is 1024 | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:238`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:246`_ ### serializeToHNSW @@ -296,7 +310,7 @@ of `OutputStream` and path to the intermediate temporary file. | --- | --- | | `outputStream` | an instance of `OutputStream` to write the index bytes to | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:247`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:255`_ ### serializeToHNSW @@ -314,7 +328,7 @@ of `OutputStream` and path to the intermediate temporary file. | `outputStream` | an instance of `OutputStream` to write the index bytes to | | `bufferLength` | the length of buffer to use for writing bytes. Default value is 1024 | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:258`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:266`_ ### serializeToHNSW @@ -332,7 +346,7 @@ of `OutputStream` and path to the intermediate temporary file. | `outputStream` | an instance of `OutputStream` to write the index bytes to | | `tempFile` | an intermediate `Path` where CAGRA index is written temporarily | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:269`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:277`_ ### serializeToHNSW @@ -351,7 +365,7 @@ of `OutputStream` and path to the intermediate temporary file. | `tempFile` | an intermediate `Path` where CAGRA index is written temporarily | | `bufferLength` | the length of buffer to use for writing bytes. Default value is 1024 | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:284`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:292`_ ### getCuVSResources @@ -365,7 +379,7 @@ Gets an instance of `CuVSResources` an instance of `CuVSResources` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:291`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:299`_ ### newBuilder @@ -387,7 +401,7 @@ Creates a new Builder with an instance of `CuVSResources`. | --- | --- | | `UnsupportedOperationException` | if the provider does not cuvs | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:299`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:307`_ ### merge @@ -413,7 +427,7 @@ A new merged CAGRA index | --- | --- | | `Throwable` | if an error occurs during the merge operation | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:311`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:319`_ ### merge @@ -440,7 +454,43 @@ A new merged CAGRA index | --- | --- | | `Throwable` | if an error occurs during the merge operation | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:323`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:331`_ + +### merge + +```java +static CagraIndex merge(CagraIndex[] indexes, CagraIndexParams mergeParams, BitSet rowFilter) throws Throwable +``` + +Merges multiple CAGRA indexes into a single index, keeping only the rows selected by +`rowFilter`. + +The merge concatenates the input datasets in the order the indexes are given, so bit +`i` of the filter refers to row `i` of that concatenation: bits `0` to +`indexes[0].size() - 1` address the first index, the bits that follow address the second, +and so on. A set bit keeps the row; a clear bit drops it. The rows that survive keep +their relative order and are packed together, so the merged index has one row per set bit. + +**Parameters** + +| Name | Description | +| --- | --- | +| `indexes` | Array of CAGRA indexes to merge | +| `mergeParams` | Parameters to control the merge operation, or null to use defaults | +| `rowFilter` | The rows to keep, or null to keep all of them. A BitSet shorter than the total row count is valid: the rows beyond its logical length are treated as clear (dropped). A bit set at a position at or beyond the total row count throws `IllegalArgumentException`. | + +**Returns** + +A new merged CAGRA index + +**Throws** + +| Type | Description | +| --- | --- | +| `IllegalArgumentException` | if `rowFilter` has a bit set beyond the last row, or if it is non-null but keeps no rows at all | +| `Throwable` | if an error occurs during the merge operation | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:355`_ ### isPaddedDataset @@ -466,7 +516,7 @@ copy it into padded storage it already occupies, and one that is not has to go t true when the rows are already padded the way CAGRA requires -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:350`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:383`_ ### from @@ -487,7 +537,7 @@ needed. an instance of this Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:367`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:400`_ ### from @@ -510,7 +560,7 @@ serialized index. Keep `outDataset` alive while the built index is in use. an instance of this Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:378`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:411`_ ### from @@ -521,7 +571,7 @@ Builder from(CuVSMatrix graph) Sets a CAGRA graph instance to re-create an index from a previously built graph. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:384`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:417`_ ### withDataset @@ -541,7 +591,7 @@ Sets the dataset vectors for building the `CagraIndex`. an instance of this Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:392`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:425`_ ### withDataset @@ -561,7 +611,7 @@ Sets the dataset for building the `CagraIndex`. an instance of this Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:400`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:433`_ ### withIndexParams @@ -582,7 +632,7 @@ Builder. An instance of this Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:409`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:442`_ ### build @@ -596,6 +646,6 @@ Builds and returns an instance of CagraIndex. an instance of CagraIndex -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:416`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:449`_ -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:25`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:26`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsprovider.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsprovider.md index 3301bfa7ab..1e5018c3e7 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsprovider.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsprovider.md @@ -23,7 +23,7 @@ static Path tempDirectory() The temporary directory to use for intermediate operations. Defaults to \{@systemProperty java.io.tmpdir\}. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:24`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:25`_ ### nativeLibraryPath @@ -34,7 +34,7 @@ default Path nativeLibraryPath() The directory where to extract and install the native library. Defaults to \{@systemProperty java.io.tmpdir\}. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:32`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:33`_ ### newCuVSResources @@ -44,7 +44,7 @@ CuVSResources newCuVSResources(Path tempDirectory) throws Throwable Creates a new CuVSResources. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:37`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:38`_ ### newCuVSResources @@ -69,7 +69,7 @@ opt in. | `memoryTrackingCsvPath` | path to the output CSV file (created/truncated) | | `memoryTrackingSampleInterval` | minimum interval between successive CSV samples | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:56`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:57`_ ### newHostMatrixBuilder @@ -79,7 +79,7 @@ CuVSMatrix.Builder newHostMatrixBuilder( long size, long dimensi Create a `CuVSMatrix.Builder` instance for a host memory matrix * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:64`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:65`_ ### newHostMatrixBuilder @@ -89,7 +89,7 @@ CuVSMatrix.Builder newHostMatrixBuilder( long size, long columns Create a `CuVSMatrix.Builder` instance for a host memory matrix * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:68`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:69`_ ### newDeviceMatrixBuilder @@ -99,7 +99,7 @@ CuVSMatrix.Builder newDeviceMatrixBuilder( CuVSResources cuVSR Create a `CuVSMatrix.Builder` instance for a device memory matrix * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:72`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:73`_ ### newDeviceMatrixBuilder @@ -109,7 +109,7 @@ CuVSMatrix.Builder newDeviceMatrixBuilder( CuVSResources cuVSR Create a `CuVSMatrix.Builder` instance for a device memory matrix * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:76`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:77`_ ### newNativeMatrixBuilder @@ -133,7 +133,7 @@ The caller will need to invoke the factory via the `MethodHandle#invokeExact` me a MethodHandle which can be invoked to build a CuVSMatrix from an external `MemorySegment` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:99`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:100`_ ### newNativeMatrixBuilderWithStrides @@ -159,7 +159,7 @@ The caller will need to invoke the factory via the `MethodHandle#invokeExact` me a MethodHandle which can be invoked to build a CuVSMatrix from an external `MemorySegment` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:118`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:119`_ ### newMatrixFromArray @@ -169,7 +169,7 @@ CuVSMatrix newMatrixFromArray(float[][] vectors) Create a `CuVSMatrix` from an on-heap array * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:121`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:122`_ ### newMatrixFromArray @@ -179,7 +179,7 @@ CuVSMatrix newMatrixFromArray(int[][] vectors) Create a `CuVSMatrix` from an on-heap array * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:124`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:125`_ ### newMatrixFromArray @@ -189,7 +189,7 @@ CuVSMatrix newMatrixFromArray(byte[][] vectors) Create a `CuVSMatrix` from an on-heap array * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:127`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:128`_ ### newBruteForceIndexBuilder @@ -199,7 +199,7 @@ BruteForceIndex.Builder newBruteForceIndexBuilder(CuVSResources cuVSResources) t Creates a new BruteForceIndex Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:130`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:131`_ ### newCagraIndexBuilder @@ -209,7 +209,7 @@ CagraIndex.Builder newCagraIndexBuilder(CuVSResources cuVSResources) throws Unsu Creates a new CagraIndex Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:134`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:135`_ ### newHnswIndexBuilder @@ -219,7 +219,7 @@ HnswIndex.Builder newHnswIndexBuilder(CuVSResources cuVSResources) throws Unsupp Creates a new HnswIndex Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:138`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:139`_ ### hnswIndexFromCagra @@ -246,7 +246,7 @@ A new HNSW index | --- | --- | | `Throwable` | if an error occurs during conversion | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:149`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:150`_ ### hnswIndexBuild @@ -274,7 +274,7 @@ A new HNSW index ready for search | --- | --- | | `Throwable` | if an error occurs during building | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:160`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:161`_ ### newTieredIndexBuilder @@ -284,41 +284,50 @@ TieredIndex.Builder newTieredIndexBuilder(CuVSResources cuVSResources) throws Un Creates a new TieredIndex Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:164`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:165`_ -### mergeCagraIndexes +### isCagraPaddedDataset ```java -CagraIndex mergeCagraIndexes(CagraIndex[] indexes) throws Throwable +default boolean isCagraPaddedDataset(CuVSMatrix dataset) ``` -Merges multiple CAGRA indexes into a single index. +Reports whether the rows of `dataset` already sit at the row stride CAGRA requires, which +is the row length in bytes rounded up to a 16 byte boundary. + +This is the question that decides which of the two padded dataset factories a caller has to +use: `CagraIndex#makePaddedDatasetView(CuVSMatrix)` for a device matrix that is already at +that stride, and `CagraIndex#makePaddedDataset(CuVSMatrix)` for one that is not. Asking +for the wrong one is an error rather than an inefficiency, and the stride of a matrix is not +visible outside this library, so callers cannot answer it for themselves. **Parameters** | Name | Description | | --- | --- | -| `indexes` | Array of CAGRA indexes to merge | +| `dataset` | the matrix to inspect | **Returns** -A new merged CAGRA index +true when the rows are already padded the way CAGRA requires **Throws** | Type | Description | | --- | --- | -| `Throwable` | if an error occurs during the merge operation | +| `UnsupportedOperationException` | if this provider cannot answer | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:174`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:182`_ ### mergeCagraIndexes ```java -default CagraIndex mergeCagraIndexes(CagraIndex[] indexes, CagraIndexParams mergeParams) throws Throwable +CagraIndex mergeCagraIndexes(CagraIndex[] indexes, CagraIndexParams mergeParams, BitSet rowFilter) throws Throwable ``` -Merges multiple CAGRA indexes into a single index with the specified merge parameters. +Merges multiple CAGRA indexes into a single index, keeping only the rows selected by +`rowFilter`. See CagraIndexParams, BitSet) for the +meaning of the filter. **Parameters** @@ -326,6 +335,7 @@ Merges multiple CAGRA indexes into a single index with the specified merge param | --- | --- | | `indexes` | Array of CAGRA indexes to merge | | `mergeParams` | Parameters to control the merge operation, or null to use defaults | +| `rowFilter` | The rows to keep, or null to keep all of them | **Returns** @@ -337,40 +347,7 @@ A new merged CAGRA index | --- | --- | | `Throwable` | if an error occurs during the merge operation | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:184`_ - -### isCagraPaddedDataset - -```java -default boolean isCagraPaddedDataset(CuVSMatrix dataset) -``` - -Reports whether the rows of `dataset` already sit at the row stride CAGRA requires, which -is the row length in bytes rounded up to a 16 byte boundary. - -This is the question that decides which of the two padded dataset factories a caller has to -use: `CagraIndex#makePaddedDatasetView(CuVSMatrix)` for a device matrix that is already at -that stride, and `CagraIndex#makePaddedDataset(CuVSMatrix)` for one that is not. Asking -for the wrong one is an error rather than an inefficiency, and the stride of a matrix is not -visible outside this library, so callers cannot answer it for themselves. - -**Parameters** - -| Name | Description | -| --- | --- | -| `dataset` | the matrix to inspect | - -**Returns** - -true when the rows are already padded the way CAGRA requires - -**Throws** - -| Type | Description | -| --- | --- | -| `UnsupportedOperationException` | if this provider cannot answer | - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:204`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:198`_ ### newFilterBitsetHandle @@ -387,7 +364,7 @@ Per-partition bit offsets are recomputed inside cuVS from the index sizes. | --- | --- | | `combinedLongs` | packed bitset words for a single partition | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:215`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:207`_ ### searchCagraMultiPartition @@ -413,7 +390,7 @@ Searches multiple CAGRA index partitions for the global top-k nearest neighbors | --- | --- | | `Throwable` | if an error occurs during the search | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:228`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:220`_ ### gpuInfoProvider @@ -423,7 +400,7 @@ GPUInfoProvider gpuInfoProvider() Returns a `GPUInfoProvider` to query the system for GPU related information -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:237`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:229`_ ### enableRMMPooledMemory @@ -442,7 +419,7 @@ This operation has a global effect, and will affect all resources on the current | `initialPoolSizePercent` | The initial pool size, in percentage of the total GPU memory | | `maxPoolSizePercent` | The maximum pool size, in percentage of the total GPU memory | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:251`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:243`_ ### enableRMMManagedPooledMemory @@ -461,7 +438,7 @@ This operation has a global effect, and will affect all resources on the current | `initialPoolSizePercent` | The initial pool size, in percentage of the total GPU memory | | `maxPoolSizePercent` | The maximum pool size, in percentage of the total GPU memory | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:261`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:253`_ ### enableRMMAsyncMemory @@ -476,7 +453,7 @@ on deallocation. This is especially beneficial when multiple CAGRA searches run on separate CUDA streams, because internal workspace allocations no longer serialize kernel launches. This operation has a global effect and will affect all resources on the current device. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:271`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:263`_ ### resetRMMPooledMemory @@ -486,7 +463,7 @@ void resetRMMPooledMemory() Disables pooled memory on the current device, reverting back to the default setting. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:274`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:266`_ ### provider @@ -496,7 +473,7 @@ static CuVSProvider provider() Retrieves the system-wide provider. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:277`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:269`_ ### cagraIndexParamsFromHnswParams @@ -526,7 +503,7 @@ may be shifted along the curve right or left. See the heuristics descriptions fo A new CAGRA index parameters object -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:297`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:289`_ ### cagraIndexParamsFromDataset @@ -550,6 +527,6 @@ Create CAGRA index parameters heuristically tuned for a dataset. A new CAGRA index parameters object -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:315`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:307`_ -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:17`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:18`_ diff --git a/fern/pages/python_api/python-api-neighbors-vamana.md b/fern/pages/python_api/python-api-neighbors-vamana.md index f0f5c6aae6..aeb8d2af9f 100644 --- a/fern/pages/python_api/python-api-neighbors-vamana.md +++ b/fern/pages/python_api/python-api-neighbors-vamana.md @@ -142,14 +142,15 @@ and robustPrune is applied to improve graph quality. The index_params struct controls the degree of the final graph. The following distance metrics are supported: -- L2Expanded +- L2Expanded (sqeuclidean) +- L2SqrtExpanded (l2 / euclidean distance) **Parameters** | Name | Type | Description | | --- | --- | --- | | `index_params` | `IndexParams object` | | -| `dataset` | `CUDA array interface compliant matrix shape (n_samples, dim)` | Supported dtype [float, int8, uint8] | +| `dataset` | `CUDA array interface compliant matrix shape (n_samples, dim)` | Supported dtype [float, float16, int8, uint8] | | `resources` | `cuvs.common.Resources, optional` | | **Returns**