Lucene: Fix GPU search failing on segments with no live vectors

Searching a segment where every document with a vector was deleted threw
an exception instead of returning no hits. The reader now skips such a
segment, and no longer assumes a search always comes back with results.
The same assumption is fixed in cuvs-java.

Fixes #2599

Author: imotov

fern/pages/lucene_api/lucene-api-com-nvidia-cuvs-lucene-cuvs2510gpuvectorsreader.md

@@ -229,7 +229,7 @@ Return the k nearest neighbor documents as determined by comparison of their vec
 
 This is not supported.
 
-_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:598`_
+_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:609`_
 
 ### readEntry
 
@@ -257,7 +257,7 @@ an instance of FieldEntry
 | --- | --- |
 | `IOException` | I/O Exceptions |
 
-_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:626`_
+_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:637`_
 
 ### getCagraIndexForField
 
@@ -278,7 +278,7 @@ Returns the `CagraIndex` for the given field, or `null` if unavailable
 
 the CAGRA index, or `null`
 
-_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:678`_
+_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:689`_
 
 ### getFilterBitsetCache
 
@@ -288,7 +288,7 @@ FilterBitsetCache getFilterBitsetCache()
 
 Returns the filter cache owned by the vectors format that created this reader.
 
-_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:688`_
+_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:699`_
 
 ### getFieldInfos
 
@@ -302,7 +302,7 @@ Gets the instance of FieldInfos.
 
 the instance of FieldInfos
 
-_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:697`_
+_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:708`_
 
 ### getCuvsIndexes
 
@@ -316,7 +316,7 @@ Gets the map of `GPUIndex` objects.
 
 the map of GPU index objects
 
-_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:706`_
+_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:717`_
 
 ### getFieldEntries
 
@@ -330,6 +330,6 @@ Gets the map of FieldEntry objects that hold the meta information for the field.
 
 the map of FieldEntry objects
 
-_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:715`_
+_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:726`_
 
 _Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java:59`_

java/cuvs-java/src/main/java22/com/nvidia/cuvs/internal/CagraSearchResults.java

@@ -37,29 +37,28 @@ static SearchResults create(
       long numberOfQueries) {
 
     List<Map<Integer, Float>> results = new LinkedList<>();
-    Map<Integer, Float> intermediateResultMap = new LinkedHashMap<>();
     var neighboursVarHandle =
         neighboursSequenceLayout.varHandle(MemoryLayout.PathElement.sequenceElement());
     var distancesVarHandle =
         distancesSequenceLayout.varHandle(MemoryLayout.PathElement.sequenceElement());
 
-    int count = 0;
-    for (long i = 0; i < topK * numberOfQueries; i++) {
-      long id = (long) neighboursVarHandle.get(neighboursMemorySegment, 0, i);
-      float dst = (float) distancesVarHandle.get(distancesMemorySegment, 0L, i);
-      // Empty top-k slots (fewer than k passing candidates) carry a sentinel distance of FLT_MAX.
-      // Prefer this over the neighbor-index sentinel: the index sentinel is not uniform across
-      // CAGRA search algorithms (single-CTA emits 0x7FFFFFFF, multi-CTA 0xFFFFFFFF), so the
-      // distance is the reliable, algorithm-independent signal for an empty slot.
-      if (dst != Float.MAX_VALUE) {
-        intermediateResultMap.put(mapping.applyAsInt(id), dst);
-      }
-      count += 1;
-      if (count == topK) {
-        results.add(intermediateResultMap);
-        intermediateResultMap = new LinkedHashMap<>();
-        count = 0;
+    // One map per query, so callers can rely on the result list holding exactly numberOfQueries
+    // entries even when topK is 0 and no map has any content.
+    for (long query = 0; query < numberOfQueries; query++) {
+      Map<Integer, Float> resultMap = new LinkedHashMap<>();
+      for (int j = 0; j < topK; j++) {
+        long i = query * topK + j;
+        long id = (long) neighboursVarHandle.get(neighboursMemorySegment, 0, i);
+        float dst = (float) distancesVarHandle.get(distancesMemorySegment, 0L, i);
+        // Empty top-k slots (fewer than k passing candidates) carry a sentinel distance of
+        // FLT_MAX. Prefer this over the neighbor-index sentinel: the index sentinel is not uniform
+        // across CAGRA search algorithms (single-CTA emits 0x7FFFFFFF, multi-CTA 0xFFFFFFFF), so
+        // the distance is the reliable, algorithm-independent signal for an empty slot.
+        if (dst != Float.MAX_VALUE) {
+          resultMap.put(mapping.applyAsInt(id), dst);
+        }
       }
+      results.add(resultMap);
     }
     return new SearchResultsImpl(results);
   }

java/cuvs-java/src/main/java22/com/nvidia/cuvs/internal/SearchResultsImpl.java

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 package com.nvidia.cuvs.internal;
@@ -35,23 +35,22 @@ static SearchResults create(
       LongToIntFunction mapping,
       long numberOfQueries) {
     List<Map<Integer, Float>> results = new LinkedList<>();
-    Map<Integer, Float> intermediateResultMap = new LinkedHashMap<>();
     var neighboursVarHandle =
         neighboursSequenceLayout.varHandle(MemoryLayout.PathElement.sequenceElement());
     var distancesVarHandle =
         distancesSequenceLayout.varHandle(MemoryLayout.PathElement.sequenceElement());
 
-    int count = 0;
-    for (long i = 0; i < topK * numberOfQueries; i++) {
-      long id = (long) neighboursVarHandle.get(neighboursMemorySegment, 0L, i);
-      float dst = (float) distancesVarHandle.get(distancesMemorySegment, 0L, i);
-      intermediateResultMap.put(mapping != null ? mapping.applyAsInt((int) id) : (int) id, dst);
-      count += 1;
-      if (count == topK) {
-        results.add(intermediateResultMap);
-        intermediateResultMap = new LinkedHashMap<>();
-        count = 0;
+    // One map per query, so callers can rely on the result list holding exactly numberOfQueries
+    // entries even when topK is 0 and no map has any content.
+    for (long query = 0; query < numberOfQueries; query++) {
+      Map<Integer, Float> resultMap = new LinkedHashMap<>();
+      for (int j = 0; j < topK; j++) {
+        long i = query * topK + j;
+        long id = (long) neighboursVarHandle.get(neighboursMemorySegment, 0L, i);
+        float dst = (float) distancesVarHandle.get(distancesMemorySegment, 0L, i);
+        resultMap.put(mapping != null ? mapping.applyAsInt((int) id) : (int) id, dst);
       }
+      results.add(resultMap);
     }
 
     return new SearchResultsImpl(results);

java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/CuVS2510GPUVectorsReader.java

@@ -487,7 +487,14 @@ public void search(String field, float[] target, KnnCollector knnCollector, Bits
           mask[0].set(i);
         }
       }
-      topK = Math.min(knnCollector.k() + 10, mask[0].cardinality());
+      int cardinality = mask[0].cardinality();
+      if (cardinality == 0) {
+        // Every vector in this segment is deleted or filtered out. cuVS cannot be asked for zero
+        // neighbours, and Lucene's contract for such a leaf is to collect nothing, so return
+        // before touching the GPU.
+        return;
+      }
+      topK = Math.min(knnCollector.k() + 10, cardinality);
       // numDocs must be the total vector count so cuVS sizes the prefilter to cover every ordinal.
       // BitSet.length() is (highest set bit + 1), which under a selective filter is smaller than
       // the
@@ -562,7 +569,11 @@ public void search(String field, float[] target, KnnCollector knnCollector, Bits
         searchResult = bruteforceIndex.search(query).getResults();
       }
 
-      // List expected to have only one entry because of single query "target".
+      // List expected to have only one entry because of single query "target". A zero-row
+      // response can only mean no neighbours were produced, so there is nothing to collect.
+      if (searchResult.isEmpty()) {
+        return;
+      }
       assert searchResult.size() == 1;
       final IntToIntFunction ordToDocFunction = (IntToIntFunction) rawValues::ordToDoc;
       final FloatToFloatFunction scoreCorrectionFunction =

java/cuvs-lucene/src/test/java/com/nvidia/cuvs/lucene/TestCuVSDeletedDocuments.java

@@ -24,20 +24,25 @@
 import org.apache.lucene.index.DirectoryReader;
 import org.apache.lucene.index.IndexWriter;
 import org.apache.lucene.index.IndexWriterConfig;
+import org.apache.lucene.index.LeafReaderContext;
+import org.apache.lucene.index.NoMergePolicy;
 import org.apache.lucene.index.Term;
 import org.apache.lucene.index.VectorSimilarityFunction;
 import org.apache.lucene.search.IndexSearcher;
+import org.apache.lucene.search.KnnFloatVectorQuery;
 import org.apache.lucene.search.Query;
 import org.apache.lucene.search.ScoreDoc;
 import org.apache.lucene.search.TermQuery;
 import org.apache.lucene.search.TopDocs;
+import org.apache.lucene.search.TopKnnCollector;
 import org.apache.lucene.store.Directory;
 import org.apache.lucene.tests.analysis.MockAnalyzer;
 import org.apache.lucene.tests.analysis.MockTokenizer;
 import org.apache.lucene.tests.index.RandomIndexWriter;
 import org.apache.lucene.tests.util.LuceneTestCase;
 import org.apache.lucene.tests.util.LuceneTestCase.SuppressSysoutChecks;
 import org.apache.lucene.tests.util.TestUtil;
+import org.apache.lucene.util.Bits;
 import org.junit.BeforeClass;
 import org.junit.Test;
 
@@ -320,6 +325,131 @@ public void testVectorSearchWithPartialDeletionAndReindexing() throws IOExceptio
     }
   }
 
+  /**
+   * A segment whose vector-bearing documents are all deleted must contribute zero hits rather than
+   * failing. Such a segment still reaches the reader as long as it keeps at least one live document
+   * without a vector, so Lucene does not drop it. See
+   * <a href="https://github.com/NVIDIA/cuvs/issues/2599">issue 2599</a>: the accepted-ordinal set is
+   * empty, which used to clamp the cuVS top-k to zero and yield a result list with no rows at all.
+   */
+  @Test
+  public void testSearchSegmentWithAllVectorsDeleted() throws IOException {
+
+    final int dimensions = 64;
+    final int liveDocs = 16;
+    final int topK = 5;
+
+    try (Directory directory = newDirectory()) {
+      float[][] dataset = generateDataset(random, liveDocs + 1, dimensions);
+
+      // NoMergePolicy keeps the two commits as two separate segments, so the first one survives as
+      // a leaf with a single, deleted vector.
+      try (IndexWriter writer =
+          new IndexWriter(directory, createWriterConfig().setMergePolicy(NoMergePolicy.INSTANCE))) {
+
+        // Segment 1: one document with a vector (deleted below) and one live document without a
+        // vector, which is what keeps the segment from being dropped once the first is deleted.
+        Document withVector = new Document();
+        withVector.add(new StringField("id", "deleted-vector", Field.Store.YES));
+        withVector.add(
+            new KnnFloatVectorField("vector", dataset[0], VectorSimilarityFunction.EUCLIDEAN));
+        writer.addDocument(withVector);
+
+        Document withoutVector = new Document();
+        withoutVector.add(new StringField("id", "no-vector", Field.Store.YES));
+        writer.addDocument(withoutVector);
+        writer.commit();
+
+        // Segment 2: live vectors, so the query still has something to return.
+        for (int i = 0; i < liveDocs; i++) {
+          Document doc = new Document();
+          doc.add(new StringField("id", "live-" + i, Field.Store.YES));
+          doc.add(
+              new KnnFloatVectorField(
+                  "vector", dataset[i + 1], VectorSimilarityFunction.EUCLIDEAN));
+          writer.addDocument(doc);
+        }
+        writer.commit();
+
+        writer.deleteDocuments(new Term("id", "deleted-vector"));
+        writer.commit();
+      }
+
+      try (DirectoryReader reader = DirectoryReader.open(directory)) {
+        assertTrue("Expected more than one segment", reader.leaves().size() > 1);
+        IndexSearcher searcher = new IndexSearcher(reader);
+        float[] queryVector = generateRandomVector(dimensions, random);
+
+        // KnnFloatVectorQuery always goes through the per-segment reader path, which is where the
+        // empty accepted-ordinal set is handled.
+        assertOnlyLiveHits(
+            reader, searcher.search(new KnnFloatVectorQuery("vector", queryVector, topK), topK));
+
+        // GPUKnnFloatVectorQuery may take either the multi-partition or the per-segment path
+        // depending on whether every segment has a usable CAGRA index; both must behave the same.
+        assertOnlyLiveHits(
+            reader,
+            searcher.search(
+                new GPUKnnFloatVectorQuery("vector", queryVector, topK, null, topK, 1), topK));
+      }
+    }
+  }
+
+  /**
+   * The reader must treat any empty accepted-ordinal set as "no hits", whatever produced it.
+   *
+   * <p>Going through {@link KnnFloatVectorQuery} with an explicit filter cannot reach this state:
+   * Lucene ANDs every user filter with a {@code FieldExistsQuery} on the vector field, so the
+   * accepted set always holds at least one vector-bearing document. This test therefore drives
+   * {@link org.apache.lucene.index.LeafReader#searchNearestVectors} directly with an all-false
+   * {@link Bits}, pinning the reader's own contract independently of the query layer.
+   */
+  @Test
+  public void testSearchWithAcceptDocsMatchingNoVectors() throws IOException {
+
+    final int dimensions = 64;
+    final int vectorDocs = 16;
+    final int topK = 5;
+
+    try (Directory directory = newDirectory()) {
+      float[][] dataset = generateDataset(random, vectorDocs, dimensions);
+
+      try (IndexWriter writer = new IndexWriter(directory, createWriterConfig())) {
+        for (int i = 0; i < vectorDocs; i++) {
+          Document doc = new Document();
+          doc.add(new StringField("id", String.valueOf(i), Field.Store.YES));
+          doc.add(
+              new KnnFloatVectorField("vector", dataset[i], VectorSimilarityFunction.EUCLIDEAN));
+          writer.addDocument(doc);
+        }
+        writer.commit();
+      }
+
+      try (DirectoryReader reader = DirectoryReader.open(directory)) {
+        float[] queryVector = generateRandomVector(dimensions, random);
+        for (LeafReaderContext ctx : reader.leaves()) {
+          TopKnnCollector collector = new TopKnnCollector(topK, Integer.MAX_VALUE);
+          ctx.reader()
+              .searchNearestVectors(
+                  "vector", queryVector, collector, new Bits.MatchNoBits(ctx.reader().maxDoc()));
+          assertEquals(
+              "An empty accepted-ordinal set should collect nothing",
+              0,
+              collector.topDocs().scoreDocs.length);
+        }
+      }
+    }
+  }
+
+  /** Asserts every hit comes from a live, vector-bearing document. */
+  private void assertOnlyLiveHits(DirectoryReader reader, TopDocs topDocs) throws IOException {
+    assertTrue("Expected hits from the live segment", topDocs.scoreDocs.length > 0);
+    for (ScoreDoc hit : topDocs.scoreDocs) {
+      String id = reader.storedFields().document(hit.doc).get("id");
+      assertTrue("Unexpected hit: " + id, id.startsWith("live-"));
+    }
+  }
+
   private RandomIndexWriter createWriter(Directory directory) throws IOException {
     return new RandomIndexWriter(
         random(),