NVIDIA · imotov · Jun 5, 2025 · Jul 2, 2025 · Jul 2, 2025 · Jul 2, 2025
@@ -11,6 +11,10 @@ examples/cpp/      @NVIDIA/cuvs-cpp-codeowners
 java/              @NVIDIA/cuvs-java-codeowners
 examples/java/     @NVIDIA/cuvs-java-codeowners
 
+#cuvs lucene code owners
+# TODO: should we have this?
+#java/cuvs-lucene   @NVIDIA/cuvs-lucene-write
+
 #python code owners
 python/            @NVIDIA/cuvs-python-codeowners
 

@@ -184,6 +184,39 @@ jobs:
       artifact-name: "cuvs-java-cuda${{ matrix.CUDA_VER }}"
       file_to_upload: "java/cuvs-java/target/"
       sha: ${{ inputs.sha }}
+  lucene-build-matrix:
+    needs: cpp-build
+    permissions:
+      contents: read
+    uses: rapidsai/shared-workflows/.github/workflows/compute-matrix.yaml@main
+    with:
+      build_type: pull-request
+      matrix_name: conda-cpp-build
+      matrix_filter: map(select(.ARCH == "amd64"))
+  lucene-build:
+    # Consumes the cuvs-java artifact uploaded by java-build instead of rebuilding cuvs-java.
+    needs: [lucene-build-matrix, java-build]
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+      packages: read
+      pull-requests: read
+    secrets: inherit # zizmor: ignore[secrets-inherit]
+    uses: rapidsai/shared-workflows/.github/workflows/custom-job.yaml@main
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.lucene-build-matrix.outputs.matrix) }}
+    with:
+      build_type: ${{ inputs.build_type || 'branch' }}
+      branch: ${{ inputs.branch }}
+      arch: "amd64"
+      date: ${{ inputs.date }}
+      container_image: "rapidsai/ci-conda:26.10-cuda${{ matrix.CUDA_VER }}-${{ matrix.LINUX_VER }}-py${{ matrix.PY_VER }}"
+      script: "ci/build_lucene.sh"
+      artifact-name: "cuvs-lucene-cuda${{ matrix.CUDA_VER }}"
+      file_to_upload: "java/cuvs-lucene/target/"
+      sha: ${{ inputs.sha }}
   python-build:
     needs: [cpp-build]
     permissions:

@@ -25,6 +25,8 @@ jobs:
       - rocky8-clib-tests
       - conda-java-build-and-tests-matrix
       - conda-java-build-and-tests
+      - conda-lucene-build-and-tests-matrix
+      - conda-lucene-build-and-tests
       - rust-build-matrix
       - rust-build
       - go-build-matrix
@@ -548,6 +550,40 @@ jobs:
       script: "ci/test_java.sh"
       artifact-name: "cuvs-java-cuda${{ matrix.CUDA_VER }}"
       file_to_upload: "java/cuvs-java/target/"
+  conda-lucene-build-and-tests-matrix:
+    needs: [conda-cpp-build, changed-files]
+    permissions:
+      contents: read
+    uses: rapidsai/shared-workflows/.github/workflows/compute-matrix.yaml@main
+    # cuvs-lucene lives under java/, so java/cuvs-lucene changes trigger the test_java group.
+    if: fromJSON(needs.changed-files.outputs.changed_file_groups).test_java || fromJSON(needs.changed-files.outputs.changed_file_groups).test_cpp
+    with:
+      build_type: pull-request
+      matrix_name: conda-cpp-build
+      matrix_filter: map(select(.ARCH == "amd64"))
+  conda-lucene-build-and-tests:
+    # Depends on conda-java-build-and-tests to consume its uploaded cuvs-java artifact
+    # (installed into the local Maven repo) instead of rebuilding cuvs-java.
+    needs: [conda-java-build-and-tests, conda-lucene-build-and-tests-matrix]
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+      packages: read
+      pull-requests: read
+    secrets: inherit # zizmor: ignore[secrets-inherit]
+    uses: rapidsai/shared-workflows/.github/workflows/custom-job.yaml@main
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.conda-lucene-build-and-tests-matrix.outputs.matrix) }}
+    with:
+      build_type: pull-request
+      node_type: "gpu-l4-latest-1"
+      arch: "amd64"
+      container_image: "rapidsai/ci-conda:26.10-cuda${{ matrix.CUDA_VER }}-${{ matrix.LINUX_VER }}-py${{ matrix.PY_VER }}"
+      script: "ci/test_lucene.sh"
+      artifact-name: "cuvs-lucene-cuda${{ matrix.CUDA_VER }}"
+      file_to_upload: "java/cuvs-lucene/target/"
   rust-build-matrix:
     needs: [conda-cpp-build, changed-files]
     permissions:

@@ -104,6 +104,40 @@ jobs:
       script: "ci/test_java.sh"
       artifact-name: "cuvs-java-cuda${{ matrix.CUDA_VER }}"
       file_to_upload: "java/cuvs-java/target/"
+  conda-lucene-build-and-tests-matrix:
+    permissions:
+      contents: read
+    uses: rapidsai/shared-workflows/.github/workflows/compute-matrix.yaml@main
+    with:
+      build_type: ${{ inputs.build_type }}
+      matrix_name: conda-cpp-build
+      matrix_filter: map(select(.ARCH == "amd64"))
+  conda-lucene-build-and-tests:
+    # Consumes the cuvs-java artifact uploaded by conda-java-build-and-tests instead of
+    # rebuilding cuvs-java.
+    needs: [conda-java-build-and-tests, conda-lucene-build-and-tests-matrix]
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+      packages: read
+      pull-requests: read
+    secrets: inherit # zizmor: ignore[secrets-inherit]
+    uses: rapidsai/shared-workflows/.github/workflows/custom-job.yaml@main
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.conda-lucene-build-and-tests-matrix.outputs.matrix) }}
+    with:
+      build_type: ${{ inputs.build_type }}
+      branch: ${{ inputs.branch }}
+      date: ${{ inputs.date }}
+      sha: ${{ inputs.sha }}
+      node_type: "gpu-l4-latest-1"
+      arch: "amd64"
+      container_image: "rapidsai/ci-conda:26.10-cuda${{ matrix.CUDA_VER }}-${{ matrix.LINUX_VER }}-py${{ matrix.PY_VER }}"
+      script: "ci/test_lucene.sh"
+      artifact-name: "cuvs-lucene-cuda${{ matrix.CUDA_VER }}"
+      file_to_upload: "java/cuvs-lucene/target/"
   wheel-tests-cuvs:
     permissions:
       actions: read

@@ -19,7 +19,7 @@ ARGS=$*
 # scripts, and that this script resides in the repo dir!
 REPODIR=$(cd "$(dirname "$0")"; pwd)
 
-VALIDARGS="clean libcuvs python rust go java docs tests bench-ann examples --uninstall  -v -g -n --allgpuarch --no-mg --mnmg-tests --no-cpu --cpu-only --no-shared-libs --no-nvtx --show_depr_warn --incl-cache-stats --time -h --run-java-tests"
+VALIDARGS="clean libcuvs python rust go java lucene docs tests bench-ann examples --uninstall  -v -g -n --allgpuarch --no-mg --mnmg-tests --no-cpu --cpu-only --no-shared-libs --no-nvtx --show_depr_warn --incl-cache-stats --time -h --run-java-tests"
 HELP="$0 [<target> ...] [<flag> ...] [--cmake-args=\"<args>\"] [--cache-tool=<tool>] [--limit-tests=<targets>] [--limit-bench-ann=<targets>] [--build-metrics=<filename>]
  where <target> is:
    clean            - remove all existing build artifacts and configuration (start over)
@@ -29,6 +29,7 @@ HELP="$0 [<target> ...] [<flag> ...] [--cmake-args=\"<args>\"] [--cache-tool=<to
    rust             - build the cuvs Rust bindings
    go               - build the cuvs Go bindings
    java             - build the cuvs Java bindings
+   lucene           - build the cuVS Lucene library
    docs             - build the documentation
    tests            - build the tests
    bench-ann        - build end-to-end ann benchmarks
@@ -74,7 +75,8 @@ FERN_DOCS_DIR=${REPODIR}/fern
 PYTHON_BUILD_DIR=${REPODIR}/python/cuvs/_skbuild
 RUST_BUILD_DIR=${REPODIR}/rust/target
 JAVA_BUILD_DIR=${REPODIR}/java/cuvs-java/target
-BUILD_DIRS="${LIBCUVS_BUILD_DIR} ${PYTHON_BUILD_DIR} ${RUST_BUILD_DIR} ${JAVA_BUILD_DIR}"
+LUCENE_BUILD_DIR=${REPODIR}/java/cuvs-lucene/target
+BUILD_DIRS="${LIBCUVS_BUILD_DIR} ${PYTHON_BUILD_DIR} ${RUST_BUILD_DIR} ${JAVA_BUILD_DIR} ${LUCENE_BUILD_DIR}"
 
 # Set defaults for vars modified by flags to this script
 CMAKE_LOG_LEVEL=""
@@ -555,6 +557,19 @@ if (( NUMARGS == 0 )) || hasArg java; then
     fi
 fi
 
+# Build the cuVS Lucene library
+if (( NUMARGS == 0 )) || hasArg lucene; then
+    if ! hasArg java; then
+        echo "Note: 'lucene' builds against the already-installed cuvs-java artifact. Add 'java' (ex. './build.sh java lucene') if cuvs-java has changed and needs rebuilding."
+    fi
+    cd "${REPODIR}"/java/cuvs-lucene
+    if hasArg --run-java-tests; then
+        ./build.sh --run-java-tests
+    else
+        ./build.sh
+    fi
+fi
+
 RAPIDS_VERSION="$(sed -E -e 's/^([0-9]{2})\.([0-9]{2})\.([0-9]{2}).*$/\1.\2.\3/' "${REPODIR}/VERSION")"
 export RAPIDS_VERSION
 RAPIDS_VERSION_MAJOR_MINOR="$(sed -E -e 's/^([0-9]{2})\.([0-9]{2})\.([0-9]{2}).*$/\1.\2/' "${REPODIR}/VERSION")"

@@ -270,6 +270,16 @@ CUVS_EXPORT cuvsError_t cuvsRMMHostFree(void* ptr, size_t bytes);
  */
 CUVS_EXPORT cuvsError_t cuvsVersionGet(uint16_t* major, uint16_t* minor, uint16_t* patch);
 
+/**
+ * @brief Bogus function used to verify end-to-end build propagation from the cuVS C
+ *        layer, through the cuvs-java bindings, to cuvs-lucene. Returns the sum of its
+ *        two arguments.
+ * @param[in] a First addend
+ * @param[in] b Second addend
+ * @return The sum @p a + @p b
+ */
+CUVS_EXPORT int cuvsBogusAddV1(int a, int b);
+
 /**
  * @brief Copy a matrix
  *

@@ -257,6 +257,8 @@ extern "C" cuvsError_t cuvsVersionGet(uint16_t* major, uint16_t* minor, uint16_t
   return CUVS_SUCCESS;
 }
 
+extern "C" int cuvsBogusAddV1(int a, int b) { return a + b; }
+
 namespace {
 template <typename T>
 void _copy_matrix(cuvsResources_t res, DLManagedTensor* src_managed, DLManagedTensor* dst_managed)

@@ -0,0 +1,76 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: Copyright (c) 2020-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+
+# TODO: Remove this argument-handling when build and test workflows are separated,
+#       and test_lucene.sh no longer calls build_lucene.sh
+#       ref: https://github.com/rapidsai/cuvs/issues/868
+EXTRA_BUILD_ARGS=()
+if [[ "${1:-}" == "--run-java-tests" ]]; then
+  EXTRA_BUILD_ARGS+=("--run-java-tests")
+fi
+
+if [ -e "/opt/conda/etc/profile.d/conda.sh" ]; then
+  . /opt/conda/etc/profile.d/conda.sh
+fi
+
+rapids-logger "Configuring conda strict channel priority"
+conda config --set channel_priority strict
+
+rapids-logger "Downloading artifacts from previous jobs"
+# libcuvs C++ conda package (provides libcuvs.so / libcuvs_c.so used at test time)
+CPP_CHANNEL=$(rapids-download-from-github "$(rapids-artifact-name conda_cpp libcuvs cuvs --cuda "$RAPIDS_CUDA_VERSION")")
+# cuvs-java jar built by the java-build job (avoids rebuilding cuvs-java here)
+CUVS_JAVA_ARTIFACT_DIR=$(rapids-download-from-github "cuvs-java-cuda${RAPIDS_CUDA_VERSION}")
+
+rapids-logger "Generate Java testing dependencies"
+
+ENV_YAML_DIR="$(mktemp -d)"
+
+rapids-dependency-file-generator \
+  --output conda \
+  --file-key java \
+  --prepend-channel "${CPP_CHANNEL}" \
+  --matrix "cuda=${RAPIDS_CUDA_VERSION%.*};arch=$(arch)" | tee "${ENV_YAML_DIR}/env.yaml"
+
+rapids-mamba-retry env create --yes -f "${ENV_YAML_DIR}/env.yaml" -n java
+
+# Temporarily allow unbound variables for conda activation.
+set +u
+conda activate java
+set -u
+
+rapids-print-env
+
+# cuvs-lucene depends on the plain cuvs-java jar (no bundled native libraries), so it loads
+# libcuvs through the system loader. Make the conda-provided libcuvs discoverable at test time.
+export LD_LIBRARY_PATH="${CONDA_PREFIX}/lib:${LD_LIBRARY_PATH:-}"
+
+# Install the cuvs-java artifact built by the java-build job into the local Maven repository
+# so that cuvs-lucene resolves com.nvidia.cuvs:cuvs-java without rebuilding it. The GAV is
+# taken from the artifact's own pom.xml (bundled alongside the jar by java/build.sh).
+VERSION=$(grep -oP 'VERSION="\K[^"]+' java/build.sh)
+CUVS_JAVA_JAR=$(find "${CUVS_JAVA_ARTIFACT_DIR}" -name "cuvs-java-${VERSION}.jar" | head -1)
+CUVS_JAVA_POM=$(find "${CUVS_JAVA_ARTIFACT_DIR}" -name "pom.xml" | head -1)
+if [[ -z "${CUVS_JAVA_JAR}" || -z "${CUVS_JAVA_POM}" ]]; then
+  echo "Error: could not locate cuvs-java-${VERSION}.jar and/or pom.xml in ${CUVS_JAVA_ARTIFACT_DIR}"
+  exit 1
+fi
+rapids-logger "Installing cuvs-java ${VERSION} from ${CUVS_JAVA_JAR}"
+mvn install:install-file -Dfile="${CUVS_JAVA_JAR}" -DpomFile="${CUVS_JAVA_POM}"
+
+EXITCODE=0
+trap "EXITCODE=1" ERR
+set +e
+
+rapids-logger "Run cuVS Lucene build"
+
+RAPIDS_CUDA_MAJOR="${RAPIDS_CUDA_VERSION%%.*}"
+export RAPIDS_CUDA_MAJOR
+
+bash ./build.sh lucene "${EXTRA_BUILD_ARGS[@]}"
+
+rapids-logger "Build script exiting with value: $EXITCODE"
+exit ${EXITCODE}
@@ -1,5 +1,5 @@
 #!/bin/bash
-# SPDX-FileCopyrightText: Copyright (c) 2020-2026, NVIDIA CORPORATION.
+# SPDX-FileCopyrightText: Copyright (c) 2020-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 ########################
 # CUVS Version Updater #
@@ -175,3 +175,11 @@ done
 sed_runner "s| CuVS [[:digit:]]\{2\}\.[[:digit:]]\{2\} | CuVS ${NEXT_SHORT_TAG} |g" java/README.md
 sed_runner "s|-[[:digit:]]\{2\}\.[[:digit:]]\{2\}\.[[:digit:]]\{1,2\}\.jar|-${NEXT_FULL_JAVA_TAG}\.jar|g" java/examples/README.md
 sed_runner "s|/[[:digit:]]\{2\}\.[[:digit:]]\{2\}\.[[:digit:]]\{1,2\}/|/${NEXT_FULL_JAVA_TAG}/|g" java/examples/README.md
+
+# Update cuvs-lucene (integrated Java subproject; uses its own CUVS_LUCENE# markers)
+sed_runner "s/VERSION=\".*\"/VERSION=\"${NEXT_FULL_JAVA_TAG}\"/g" java/cuvs-lucene/build.sh
+for FILE in java/cuvs-lucene/pom.xml java/cuvs-lucene/examples/pom.xml java/cuvs-lucene/bench/pom.xml; do
+  sed_runner "/<!--CUVS_LUCENE#VERSION_UPDATE_MARKER_START-->.*<!--CUVS_LUCENE#VERSION_UPDATE_MARKER_END-->/s//<!--CUVS_LUCENE#VERSION_UPDATE_MARKER_START--><version>${NEXT_FULL_JAVA_TAG}<\/version><!--CUVS_LUCENE#VERSION_UPDATE_MARKER_END-->/g" "${FILE}"
+done
+sed_runner "s|rapidsai/ci-conda:[\.0-9]*-cuda|rapidsai/ci-conda:${NEXT_SHORT_TAG}-cuda|g" java/cuvs-lucene/examples/README.md
+sed_runner "s|target/examples-[\.0-9]*-jar|target/examples-${NEXT_FULL_JAVA_TAG}-jar|g" java/cuvs-lucene/examples/README.md
@@ -0,0 +1,24 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: Copyright (c) 2020-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+
+EXITCODE=0
+trap "EXITCODE=1" ERR
+set +e
+
+rapids-logger "Check GPU usage"
+nvidia-smi
+
+rapids-logger "Run cuVS Lucene build and tests"
+
+RAPIDS_CUDA_MAJOR="${RAPIDS_CUDA_VERSION%%.*}"
+export RAPIDS_CUDA_MAJOR
+
+# TODO: switch to installing pre-built artifacts instead of rebuilding in test jobs
+#       ref: https://github.com/rapidsai/cuvs/issues/868
+ci/build_lucene.sh --run-java-tests
+
+rapids-logger "Test script exiting with value: $EXITCODE"
+exit ${EXITCODE}
@@ -7,3 +7,5 @@ openjdk-22-jextract*
 /cuvs-java/bin/
 /cuvs-java/src/main/java22/com/nvidia/cuvs/internal/panama/
 /cuvs-java/*.cag
+# cuvs-lucene
+/cuvs-lucene/bin/
@@ -59,3 +59,13 @@ times, by passing `-Dtests.iters=10` through the command line.
 ## Examples
 
 A few starter examples of CAGRA, HNSW, and Bruteforce indexing and searching are provided in the `examples` directory.
+
+## cuVS Lucene
+
+The [`cuvs-lucene`](cuvs-lucene) directory contains the cuVS integration for
+[Apache Lucene](https://github.com/apache/lucene) — a pluggable `KnnVectorsFormat` that enables
+GPU-accelerated vector search. It depends on the `cuvs-java` bindings described above.
+
+`lucene` is a separate top-level build target: build it with `./build.sh lucene` (or
+`./build.sh java lucene` to rebuild `cuvs-java` first, or `./build.sh libcuvs java lucene` to build
+everything from scratch). See [`cuvs-lucene/README.md`](cuvs-lucene/README.md) for details.
@@ -218,6 +218,18 @@ default CagraIndex mergeCagraIndexes(CagraIndex[] indexes, CagraIndexParams merg
   /** Disables pooled memory on the current device, reverting back to the default setting.  */
   void resetRMMPooledMemory();
 
+  /**
+   * Bogus method used to verify end-to-end build propagation from the cuVS C layer, through the
+   * cuvs-java bindings, to cuvs-lucene. Returns the sum of its two arguments.
+   *
+   * @param a first addend
+   * @param b second addend
+   * @return the sum {@code a + b}
+   */
+  default int bogusAddV1(int a, int b) {
+    throw new UnsupportedOperationException("bogusAddV1 is not supported by this provider");
+  }
+
   /** Retrieves the system-wide provider. */
   static CuVSProvider provider() {
     return CuVSServiceProvider.Holder.INSTANCE;

@@ -473,6 +473,11 @@ public void resetRMMPooledMemory() {
     checkCuVSError(cuvsRMMMemoryResourceResetInvoker.apply(), "cuvsRMMMemoryResourceReset");
   }
 
+  @Override
+  public int bogusAddV1(int a, int b) {
+    return cuvsBogusAddV1(a, b);
+  }
+
   @Override
   public CuVSMatrix.Builder<CuVSHostMatrix> newHostMatrixBuilder(
       long size, long columns, CuVSMatrix.DataType dataType) {

@@ -0,0 +1,6 @@
+-e
+-B
+-Daether.connector.basic.downstreamThreads=1
+-Daether.transport.http.retryHandler.count=5
+-Daether.transport.http.retryHandler.interval=10000
+-Dmaven.wagon.http.retryHandler.count=5