perf: massive improvement with vector indexes

Fixed issue ArcadeData#3721

Author: lvca

engine/src/main/java/com/arcadedb/function/sql/vector/SQLFunctionVectorNeighbors.java

@@ -49,7 +49,7 @@ public SQLFunctionVectorNeighbors() {
 
   public Object execute(final Object self, final Identifiable currentRecord, final Object currentResult, final Object[] params,
       final CommandContext context) {
-    if (params == null || params.length != 3)
+    if (params == null || params.length < 3 || params.length > 4)
       throw new CommandSQLParsingException(getSyntax());
 
     final String indexSpec = params[0].toString();
@@ -63,6 +63,10 @@ public Object execute(final Object self, final Identifiable currentRecord, final
 
     final int limit = params[2] instanceof Number n ? n.intValue() : Integer.parseInt(params[2].toString());
 
+    // Optional 4th parameter: efSearch (search beam width for recall tuning)
+    final int efSearch = params.length >= 4 && params[3] != null ?
+        (params[3] instanceof Number n ? n.intValue() : Integer.parseInt(params[3].toString())) : -1;
+
     // Parse the index specification: TYPE[property] or just index name
     final String specifiedTypeName;
     final String propertyName;
@@ -74,7 +78,7 @@ public Object execute(final Object self, final Identifiable currentRecord, final
       // Assume it's just an index name
       final Index directIndex = context.getDatabase().getSchema().getIndexByName(indexSpec);
       if (directIndex instanceof TypeIndex typeIndex) {
-        return executeWithTypeIndex(typeIndex, null, key, limit, context);
+        return executeWithTypeIndex(typeIndex, null, key, limit, efSearch, context);
       }
       throw new CommandSQLParsingException(
           "Index '" + indexSpec + "' is not a vector index (found: " + (directIndex != null ? directIndex.getClass().getSimpleName() : "null") + ")");
@@ -97,11 +101,11 @@ public Object execute(final Object self, final Identifiable currentRecord, final
       allowedBucketIds.add(bucket.getFileId());
     }
 
-    return executeWithTypeIndex(typeIndex, allowedBucketIds, key, limit, context);
+    return executeWithTypeIndex(typeIndex, allowedBucketIds, key, limit, efSearch, context);
   }
 
   private Object executeWithTypeIndex(final TypeIndex typeIndex, final Set<Integer> allowedBucketIds, final Object key,
-      final int limit, final CommandContext context) {
+      final int limit, final int efSearch, final CommandContext context) {
     final var bucketIndexes = typeIndex.getIndexesOnBuckets();
     if (bucketIndexes == null || bucketIndexes.length == 0) {
       throw new CommandSQLParsingException("Index '" + typeIndex.getName() + "' has no bucket indexes");
@@ -127,15 +131,15 @@ private Object executeWithTypeIndex(final TypeIndex typeIndex, final Set<Integer
     }
 
     // Search across all matching vector indexes and merge results
-    return executeWithLSMVectorIndexes(vectorIndexes, key, limit, context);
+    return executeWithLSMVectorIndexes(vectorIndexes, key, limit, efSearch, context);
   }
 
   /**
    * Search across multiple vector indexes and merge the results.
    * This is used when searching within a specific type that may have multiple buckets.
    */
   private Object executeWithLSMVectorIndexes(final List<LSMVectorIndex> vectorIndexes, final Object key, final int limit,
-      final CommandContext context) {
+      final int efSearch, final CommandContext context) {
     // Get the query vector
     final float[] queryVector = extractQueryVector(key, vectorIndexes.getFirst(), context);
 
@@ -144,7 +148,7 @@ private Object executeWithLSMVectorIndexes(final List<LSMVectorIndex> vectorInde
 
     for (final LSMVectorIndex lsmIndex : vectorIndexes) {
       // Request more results from each index to ensure we have enough after merging
-      final List<Pair<RID, Float>> neighbors = lsmIndex.findNeighborsFromVector(queryVector, limit);
+      final List<Pair<RID, Float>> neighbors = lsmIndex.findNeighborsFromVector(queryVector, limit, efSearch);
       allNeighbors.addAll(neighbors);
     }
 
@@ -226,6 +230,6 @@ private float[] extractQueryVector(final Object key, final LSMVectorIndex lsmInd
   }
 
   public String getSyntax() {
-    return NAME + "(<index-name>, <key-or-vector>, <k>)";
+    return NAME + "(<index-name>, <key-or-vector>, <k>[, <efSearch>])";
   }
 }

engine/src/main/java/com/arcadedb/index/vector/ArcadePageVectorValues.java

@@ -23,8 +23,6 @@
 import com.arcadedb.database.Record;
 import com.arcadedb.exception.RecordNotFoundException;
 import com.arcadedb.log.LogManager;
-import com.arcadedb.utility.MostUsedCache;
-
 import io.github.jbellis.jvector.graph.ImmutableGraphIndex;
 import io.github.jbellis.jvector.graph.RandomAccessVectorValues;
 import io.github.jbellis.jvector.graph.disk.OnDiskGraphIndex;
@@ -33,6 +31,7 @@
 import io.github.jbellis.jvector.vector.types.VectorTypeSupport;
 
 import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.logging.*;
 
 /**
@@ -61,8 +60,9 @@ public class ArcadePageVectorValues implements RandomAccessVectorValues {
   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;
+  // Lock-free concurrent map to avoid mutex contention during parallel JVector graph build
+  private final ConcurrentHashMap<Integer, VectorFloat<?>> vectorCache;
+  private final int maxCacheSize;
 
   // Constructor for live reads (uses shared vectorIndex, no cache needed)
   public ArcadePageVectorValues(final DatabaseInternal database, final int dimensions, final String vectorPropertyName,
@@ -71,6 +71,7 @@ public ArcadePageVectorValues(final DatabaseInternal database, final int dimensi
   }
 
   // Constructor for live reads with LSM index reference (for quantization support)
+  // Includes a small bounded cache for search — JVector revisits nodes during beam search
   public ArcadePageVectorValues(final DatabaseInternal database, final int dimensions, final String vectorPropertyName,
       final VectorLocationIndex vectorIndex, final int[] ordinalToVectorId, final LSMVectorIndex lsmIndex) {
     this.database = database;
@@ -80,7 +81,9 @@ public ArcadePageVectorValues(final DatabaseInternal database, final int dimensi
     this.vectorSnapshot = null;
     this.ordinalToVectorId = ordinalToVectorId;
     this.lsmIndex = lsmIndex;
-    this.vectorCache = null; // No cache for live reads (search only reads each vector once)
+    // Small search-time cache: beam search revisits nodes during graph traversal
+    this.vectorCache = new ConcurrentHashMap<>(512);
+    this.maxCacheSize = 1024;
     this.deletedSentinelVector = createDeletedSentinelVector(dimensions);
   }
 
@@ -108,7 +111,9 @@ public ArcadePageVectorValues(final DatabaseInternal database, final int dimensi
     this.vectorSnapshot = vectorSnapshot;
     this.ordinalToVectorId = ordinalToVectorId;
     this.lsmIndex = lsmIndex;
-    this.vectorCache = new MostUsedCache<>(cacheSize); // Bounded LFU cache for graph building
+    final int effectiveCacheSize = cacheSize <= 0 ? DEFAULT_CACHE_SIZE : cacheSize;
+    this.vectorCache = new ConcurrentHashMap<>(Math.min(effectiveCacheSize, 1_000_000)); // Lock-free cache for parallel graph building
+    this.maxCacheSize = effectiveCacheSize;
     this.deletedSentinelVector = createDeletedSentinelVector(dimensions);
   }
 
@@ -131,11 +136,9 @@ public VectorFloat<?> getVector(final int ordinal) {
 
     // Check cache first (for graph building - dramatically speeds up repeated access)
     if (vectorCache != null) {
-      synchronized (vectorCache) {
-        final VectorFloat<?> cached = vectorCache.get(vectorId);
-        if (cached != null)
-          return cached;
-      }
+      final VectorFloat<?> cached = vectorCache.get(vectorId);
+      if (cached != null)
+        return cached;
     }
 
     // Use snapshot if available (during graph building), otherwise use live vectorIndex
@@ -167,11 +170,8 @@ else if (vectorIndex != null)
             // Track fetch source for metrics
             lsmIndex.metrics.incrementVectorFetchFromGraph();
 
-            if (vectorCache != null) {
-              synchronized (vectorCache) {
-                vectorCache.put(vectorId, vector);
-              }
-            }
+            if (vectorCache != null && vectorCache.size() < maxCacheSize)
+              vectorCache.put(vectorId, vector);
 
             return vector;
           }
@@ -242,16 +242,7 @@ else if (vectorIndex != null)
         return deletedSentinelVector;
       }
 
-      // Safety check: Validate vector is not all zeros (would cause NaN in cosine similarity)
-      boolean hasNonZero = false;
-      for (float v : vector) {
-        if (v != 0.0f) {
-          hasNonZero = true;
-          break;
-        }
-      }
-
-      if (!hasNonZero)
+      if (VectorUtils.isZeroVector(vector))
         return deletedSentinelVector;
 
       final VectorFloat<?> result = vts.createFloatVector(vector);
@@ -261,11 +252,8 @@ else if (vectorIndex != null)
         lsmIndex.metrics.incrementVectorFetchFromDocuments();
 
       // Cache the result if caching is enabled (for graph building performance)
-      if (vectorCache != null) {
-        synchronized (vectorCache) {
-          vectorCache.put(vectorId, result);
-        }
-      }
+      if (vectorCache != null && vectorCache.size() < maxCacheSize)
+        vectorCache.put(vectorId, result);
 
       return result;
 
@@ -286,11 +274,8 @@ else if (vectorIndex != null)
    * without needing their own database context for lookupByRID.
    */
   public void putInCache(final int vectorId, final VectorFloat<?> vector) {
-    if (vectorCache != null && vector != null) {
-      synchronized (vectorCache) {
-        vectorCache.put(vectorId, vector);
-      }
-    }
+    if (vectorCache != null && vector != null)
+      vectorCache.put(vectorId, vector);
   }
 
   @Override

engine/src/main/java/com/arcadedb/index/vector/GrowableVectorValues.java

@@ -0,0 +1,163 @@
+/*
+ * 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.database.DatabaseInternal;
+import com.arcadedb.database.Document;
+import com.arcadedb.log.LogManager;
+
+import io.github.jbellis.jvector.graph.RandomAccessVectorValues;
+import io.github.jbellis.jvector.vector.VectorizationProvider;
+import io.github.jbellis.jvector.vector.types.VectorFloat;
+import io.github.jbellis.jvector.vector.types.VectorTypeSupport;
+
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.logging.Level;
+
+/**
+ * A growable RandomAccessVectorValues with lazy disk fallback.
+ * <p>
+ * New vectors inserted via {@link #addVector} are cached in memory (ConcurrentHashMap).
+ * Existing vectors not in the cache are loaded lazily from ArcadeDB pages/documents
+ * on first access and then cached. This avoids pre-loading all vectors at startup
+ * while keeping frequently-accessed vectors fast.
+ * <p>
+ * Thread-safe for concurrent reads and writes.
+ *
+ * @author Luca Garulli (l.garulli@arcadedata.com)
+ */
+class GrowableVectorValues implements RandomAccessVectorValues {
+  private static final VectorTypeSupport vts = VectorizationProvider.getInstance().getVectorTypeSupport();
+
+  private final int dimensions;
+  private final ConcurrentHashMap<Integer, VectorFloat<?>> vectors;
+  private final AtomicInteger count = new AtomicInteger(0);
+
+  // Lazy-load support: when a vector is not in the map, read from disk
+  private final VectorLocationIndex vectorIndex;
+  private final LSMVectorIndex lsmIndex;
+  private final DatabaseInternal database;
+  private final String vectorPropertyName;
+
+  /**
+   * Simple mode: no disk fallback (used in tests and when all vectors are in memory).
+   */
+  GrowableVectorValues(final int dimensions) {
+    this(dimensions, 1024, null, null, null, null);
+  }
+
+  /**
+   * Simple mode with initial capacity.
+   */
+  GrowableVectorValues(final int dimensions, final int initialCapacity) {
+    this(dimensions, initialCapacity, null, null, null, null);
+  }
+
+  /**
+   * Full mode with lazy disk fallback for existing vectors.
+   */
+  GrowableVectorValues(final int dimensions, final int initialCapacity,
+      final VectorLocationIndex vectorIndex, final LSMVectorIndex lsmIndex,
+      final DatabaseInternal database, final String vectorPropertyName) {
+    this.dimensions = dimensions;
+    this.vectors = new ConcurrentHashMap<>(Math.max(16, initialCapacity));
+    this.vectorIndex = vectorIndex;
+    this.lsmIndex = lsmIndex;
+    this.database = database;
+    this.vectorPropertyName = vectorPropertyName;
+  }
+
+  void addVector(final int ordinal, final VectorFloat<?> vector) {
+    vectors.put(ordinal, vector);
+    int current;
+    while ((current = count.get()) <= ordinal)
+      count.compareAndSet(current, ordinal + 1);
+  }
+
+  void removeVector(final int ordinal) {
+    vectors.remove(ordinal);
+  }
+
+  @Override
+  public int size() {
+    return count.get();
+  }
+
+  @Override
+  public int dimension() {
+    return dimensions;
+  }
+
+  @Override
+  public VectorFloat<?> getVector(final int ordinal) {
+    // Fast path: check in-memory cache
+    final VectorFloat<?> cached = vectors.get(ordinal);
+    if (cached != null)
+      return cached;
+
+    // Slow path: lazy-load from disk and cache
+    if (vectorIndex == null || database == null)
+      return null;
+
+    final VectorLocationIndex.VectorLocation loc = vectorIndex.getLocation(ordinal);
+    if (loc == null || loc.deleted)
+      return null;
+
+    try {
+      float[] vector = null;
+
+      // Try quantized pages first (INT8/BINARY)
+      if (lsmIndex != null)
+        vector = lsmIndex.readVectorFromOffset(loc.absoluteFileOffset, loc.isCompacted);
+
+      // Fall back to document lookup
+      if (vector == null && vectorPropertyName != null) {
+        final var record = database.lookupByRID(loc.rid, false);
+        final Document doc = (Document) record;
+        vector = VectorUtils.convertToFloatArray(doc.get(vectorPropertyName));
+      }
+
+      if (vector != null && vector.length == dimensions && !VectorUtils.isZeroVector(vector)) {
+        final VectorFloat<?> vf = vts.createFloatVector(vector);
+        vectors.put(ordinal, vf); // Cache for next access
+        return vf;
+      }
+    } catch (final Exception e) {
+      LogManager.instance().log(this, Level.FINE,
+          "Could not lazy-load vector ordinal=%d: %s", ordinal, e.getMessage());
+    }
+
+    return null;
+  }
+
+  @Override
+  public boolean isValueShared() {
+    return false;
+  }
+
+  @Override
+  public RandomAccessVectorValues copy() {
+    return this;
+  }
+
+  int vectorCount() {
+    return vectors.size();
+  }
+}