fix: NPE in GraphSearcher.search() with deleted vectors

lvca · lvca · commit b18635ac199e · 2026-03-23T13:26:39.000-04:00
Fixed issue ArcadeData#3715 When vectors are deleted from the index, ArcadePageVectorValues.getVector() returned null for deleted/missing ordinals. However, the HNSW graph may still reference these deleted ordinals during search traversal. JVector's GraphSearcher calls .length() on the returned vector, causing NPE when it's null.
diff --git a/engine/src/main/java/com/arcadedb/index/vector/ArcadePageVectorValues.java b/engine/src/main/java/com/arcadedb/index/vector/ArcadePageVectorValues.java
@@ -56,6 +56,10 @@ public class ArcadePageVectorValues implements RandomAccessVectorValues {
   private final int[]                                            ordinalToVectorId;
   private final LSMVectorIndex                                   lsmIndex;         // Used for reading quantized vectors
 
+  // Sentinel vector returned for deleted/missing ordinals to prevent NPE in JVector's GraphSearcher (issue #3715).
+  // Uses Float.MIN_NORMAL to avoid division-by-zero with cosine similarity while giving very low similarity scores.
+  private final VectorFloat<?> deletedSentinelVector;
+
   // Cache for graph building - dramatically speeds up repeated vector access
   // Bounded LFU cache to prevent unbounded memory growth during graph construction
   private final MostUsedCache<Integer, VectorFloat<?>> vectorCache;
@@ -77,6 +81,7 @@ public ArcadePageVectorValues(final DatabaseInternal database, final int dimensi
     this.ordinalToVectorId = ordinalToVectorId;
     this.lsmIndex = lsmIndex;
     this.vectorCache = null; // No cache for live reads (search only reads each vector once)
+    this.deletedSentinelVector = createDeletedSentinelVector(dimensions);
   }
 
   // Constructor for graph building (uses immutable snapshot + cache for performance)
@@ -104,6 +109,7 @@ public ArcadePageVectorValues(final DatabaseInternal database, final int dimensi
     this.ordinalToVectorId = ordinalToVectorId;
     this.lsmIndex = lsmIndex;
     this.vectorCache = new MostUsedCache<>(cacheSize); // Bounded LFU cache for graph building
+    this.deletedSentinelVector = createDeletedSentinelVector(dimensions);
   }
 
   @Override
@@ -119,7 +125,7 @@ public int dimension() {
   @Override
   public VectorFloat<?> getVector(final int ordinal) {
     if (ordinal < 0 || ordinalToVectorId == null || ordinal >= ordinalToVectorId.length)
-      return null;
+      return deletedSentinelVector;
 
     final int vectorId = ordinalToVectorId[ordinal];
 
@@ -142,7 +148,10 @@ else if (vectorIndex != null)
       loc = null;
 
     if (loc == null || loc.deleted)
-      return null;
+      // Return sentinel instead of null for deleted/missing entries (issue #3715).
+      // JVector's GraphSearcher traverses deleted ordinals in the stale HNSW graph and
+      // calls .length() on the vector, causing NPE if null. Results are filtered in post-processing.
+      return deletedSentinelVector;
 
     // Phase 2: Try reading from graph file first if vectors are stored inline
     // Only during search (vectorSnapshot == null), NOT during graph building (vectorSnapshot != null)
@@ -215,22 +224,22 @@ else if (vectorIndex != null)
               "Vector property '%s' not found in document %s (ordinal=%d). Available properties: %s",
               vectorPropertyName, loc.rid, ordinal, doc.getPropertyNames());
         }
-        return null; // Property not found
+        return deletedSentinelVector;
       }
 
       final float[] vector = VectorUtils.convertToFloatArray(vectorObj);
       if (vector == null) {
         LogManager.instance().log(this, Level.WARNING,
             "Vector property '%s' is not float[] or List (type=%s, RID=%s)",
             vectorPropertyName, vectorObj.getClass().getName(), loc.rid);
-        return null;
+        return deletedSentinelVector;
       }
 
       if (vector.length != dimensions) {
         LogManager.instance().log(this, Level.WARNING,
             "Vector dimension mismatch: expected %d, got %d (RID=%s)",
             dimensions, vector.length, loc.rid);
-        return null;
+        return deletedSentinelVector;
       }
 
       // Safety check: Validate vector is not all zeros (would cause NaN in cosine similarity)
@@ -243,7 +252,7 @@ else if (vectorIndex != null)
       }
 
       if (!hasNonZero)
-        return null; // Zero vectors cause NaN in cosine similarity
+        return deletedSentinelVector;
 
       final VectorFloat<?> result = vts.createFloatVector(vector);
 
@@ -261,12 +270,12 @@ else if (vectorIndex != null)
       return result;
 
     } catch (final RecordNotFoundException e) {
-      // DELETED RECORD
-      return null;
+      // DELETED RECORD — return sentinel to avoid NPE in JVector (issue #3715)
+      return deletedSentinelVector;
     } catch (final Exception e) {
       LogManager.instance().log(this, Level.WARNING,
           "Error reading vector from document (ordinal=%d, RID=%s): %s", ordinal, loc.rid, e.getMessage());
-      return null;
+      return deletedSentinelVector;
     }
   }
 
@@ -295,4 +304,15 @@ public RandomAccessVectorValues copy() {
     // This implementation is thread-safe for reads (PageManager handles concurrency)
     return this;
   }
+
+  /**
+   * Creates a sentinel vector for deleted/missing ordinals with small non-zero values.
+   * Uses Float.MIN_NORMAL to avoid division-by-zero in cosine similarity while producing
+   * very low similarity scores that effectively push deleted nodes to the bottom of results.
+   */
+  private static VectorFloat<?> createDeletedSentinelVector(final int dimensions) {
+    final float[] sentinel = new float[dimensions];
+    Arrays.fill(sentinel, Float.MIN_NORMAL);
+    return vts.createFloatVector(sentinel);
+  }
 }
diff --git a/engine/src/test/java/com/arcadedb/index/vector/Issue3715VectorSearchAfterDeleteTest.java b/engine/src/test/java/com/arcadedb/index/vector/Issue3715VectorSearchAfterDeleteTest.java
@@ -0,0 +1,202 @@
+/*
+ * Copyright © 2021-present Arcade Data Ltd (info@arcadedata.com)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-FileCopyrightText: 2021-present Arcade Data Ltd (info@arcadedata.com)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package com.arcadedb.index.vector;
+
+import com.arcadedb.GlobalConfiguration;
+import com.arcadedb.TestHelper;
+import com.arcadedb.database.RID;
+import com.arcadedb.query.sql.executor.Result;
+import com.arcadedb.query.sql.executor.ResultSet;
+import com.arcadedb.schema.Type;
+import com.arcadedb.schema.VertexType;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Test to reproduce issue #3715: NullPointerException in GraphSearcher.search() when
+ * searching a vector index that contains deleted entries.
+ * <p>
+ * The HNSW graph still references ordinals of deleted vectors. When JVector traverses the
+ * graph during search, it calls getVector() on deleted ordinals, gets null, and throws NPE.
+ * <p>
+ * The bug manifests with large graphs (>=1000 vectors) where the rebuild is async and may not
+ * happen before the next search. With few deletions (below the mutations threshold), no rebuild
+ * is triggered at all, and the stale graph is used directly.
+ * <p>
+ * <a href="https://github.com/ArcadeData/arcadedb/issues/3715">GitHub Issue #3715</a>
+ *
+ * @author Luca Garulli (l.garulli@arcadedata.com)
+ */
+class Issue3715VectorSearchAfterDeleteTest extends TestHelper {
+
+  private static final int DIMENSIONS = 64;
+  // Must be >= 1000 to trigger async rebuild path (ASYNC_REBUILD_MIN_GRAPH_SIZE)
+  private static final int TOTAL_VECTORS = 1500;
+  // Delete a large portion to maximize chance of search traversing through deleted ordinals.
+  // Even if this exceeds the mutation threshold, the async rebuild won't complete before search.
+  private static final int VECTORS_TO_DELETE = 500;
+
+  @Test
+  void vectorSearchAfterDeleteShouldNotThrowNPE() {
+    // Set very high mutation threshold so the graph is NOT rebuilt after deletions.
+    // This forces the search to use the stale graph with edges to deleted ordinals.
+    database.getConfiguration().setValue(GlobalConfiguration.VECTOR_INDEX_MUTATIONS_BEFORE_REBUILD, 100_000);
+
+    // Phase 1: Create schema with vector index
+    database.transaction(() -> {
+      final VertexType type = database.getSchema().createVertexType("VectorDoc");
+      type.createProperty("name", Type.STRING);
+      type.createProperty("embedding", Type.ARRAY_OF_FLOATS);
+
+      database.getSchema().buildTypeIndex("VectorDoc", new String[] { "embedding" })
+          .withLSMVectorType()
+          .withDimensions(DIMENSIONS)
+          .withSimilarity("COSINE")
+          .withMaxConnections(16)
+          .withBeamWidth(100)
+          .create();
+    });
+
+    // Phase 2: Insert enough vectors to exceed ASYNC_REBUILD_MIN_GRAPH_SIZE (1000)
+    final List<RID> insertedRIDs = new ArrayList<>();
+    database.transaction(() -> {
+      for (int i = 0; i < TOTAL_VECTORS; i++) {
+        final var vertex = database.newVertex("VectorDoc");
+        vertex.set("name", "doc" + i);
+        final float[] vector = new float[DIMENSIONS];
+        for (int j = 0; j < DIMENSIONS; j++)
+          vector[j] = (float) Math.random();
+        vertex.set("embedding", vector);
+        vertex.save();
+        insertedRIDs.add(vertex.getIdentity());
+      }
+    });
+
+    // Phase 3: Force graph build by doing a search first
+    database.transaction(() -> {
+      final float[] queryVector = new float[DIMENSIONS];
+      Arrays.fill(queryVector, 0.5f);
+      final ResultSet rs = database.query("sql",
+          "SELECT vectorNeighbors('VectorDoc[embedding]', ?, 10) AS neighbors",
+          queryVector);
+      assertThat(rs.hasNext()).isTrue();
+      rs.close();
+    });
+
+    // Phase 4: Delete vectors (below the mutation threshold so NO rebuild is triggered)
+    // This leaves the HNSW graph with stale edges to deleted ordinals
+    database.transaction(() -> {
+      for (int i = 0; i < VECTORS_TO_DELETE; i++)
+        insertedRIDs.get(i).asDocument().delete();
+    });
+
+    // Phase 5: Search multiple times with different query vectors.
+    // The HNSW graph still has edges to deleted ordinals. Before the fix,
+    // getVector() returned null for deleted ordinals, causing NPE in JVector.
+    database.transaction(() -> {
+      for (int s = 0; s < 20; s++) {
+        final float[] queryVector = new float[DIMENSIONS];
+        for (int j = 0; j < DIMENSIONS; j++)
+          queryVector[j] = (float) Math.random();
+        final ResultSet rs = database.query("sql",
+            "SELECT vectorNeighbors('VectorDoc[embedding]', ?, 10) AS neighbors",
+            queryVector);
+        assertThat(rs.hasNext()).isTrue();
+        final Result result = rs.next();
+        final List<?> neighbors = result.getProperty("neighbors");
+        assertThat(neighbors).isNotNull();
+        assertThat(neighbors.size()).isGreaterThan(0);
+        assertThat(neighbors.size()).isLessThanOrEqualTo(10);
+        rs.close();
+      }
+    });
+  }
+
+  @Test
+  void vectorSearchAfterDeleteWithReopenShouldNotThrowNPE() {
+    // Same scenario but with database reopen between delete and search
+    database.transaction(() -> {
+      final VertexType type = database.getSchema().createVertexType("VectorDoc2");
+      type.createProperty("name", Type.STRING);
+      type.createProperty("embedding", Type.ARRAY_OF_FLOATS);
+
+      database.getSchema().buildTypeIndex("VectorDoc2", new String[] { "embedding" })
+          .withLSMVectorType()
+          .withDimensions(DIMENSIONS)
+          .withSimilarity("COSINE")
+          .withMaxConnections(16)
+          .withBeamWidth(100)
+          .create();
+    });
+
+    final List<RID> insertedRIDs = new ArrayList<>();
+    database.transaction(() -> {
+      for (int i = 0; i < TOTAL_VECTORS; i++) {
+        final var vertex = database.newVertex("VectorDoc2");
+        vertex.set("name", "doc" + i);
+        final float[] vector = new float[DIMENSIONS];
+        for (int j = 0; j < DIMENSIONS; j++)
+          vector[j] = (float) Math.random();
+        vertex.set("embedding", vector);
+        vertex.save();
+        insertedRIDs.add(vertex.getIdentity());
+      }
+    });
+
+    // Force graph build
+    database.transaction(() -> {
+      final float[] queryVector = new float[DIMENSIONS];
+      Arrays.fill(queryVector, 0.5f);
+      final ResultSet rs = database.query("sql",
+          "SELECT vectorNeighbors('VectorDoc2[embedding]', ?, 10) AS neighbors",
+          queryVector);
+      assertThat(rs.hasNext()).isTrue();
+      rs.close();
+    });
+
+    // Delete vectors
+    database.transaction(() -> {
+      for (int i = 0; i < VECTORS_TO_DELETE; i++)
+        insertedRIDs.get(i).asDocument().delete();
+    });
+
+    // Reopen database (simulates the user's scenario where deletions persist on disk)
+    reopenDatabase();
+
+    // Search after reopen — should NOT throw NPE
+    database.transaction(() -> {
+      final float[] queryVector = new float[DIMENSIONS];
+      Arrays.fill(queryVector, 0.5f);
+      final ResultSet rs = database.query("sql",
+          "SELECT vectorNeighbors('VectorDoc2[embedding]', ?, 10) AS neighbors",
+          queryVector);
+      assertThat(rs.hasNext()).isTrue();
+      final Result result = rs.next();
+      final List<?> neighbors = result.getProperty("neighbors");
+      assertThat(neighbors).isNotNull();
+      assertThat(neighbors.size()).isGreaterThan(0);
+      rs.close();
+    });
+  }
+}
