Apache Lucene open-source search software
Avoid reconstructing HNSW graphs during segment merging. (#15003)
Pulkit Guptaef10476d98ab
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txtindex e34082d60ce..918901d2c77 100644--- a/lucene/CHANGES.txt+++ b/lucene/CHANGES.txt@@ -231,6 +231,8 @@ Optimizations# GITHUB#15303: Speed up NumericUtils#{add,subtract} by operating on integers instead of bytes. (Kaival Parikh)+* GITHUB#15003: Avoid reconstructing HNSW graph during merging (Pulkit Gupta)+Bug Fixes---------------------* GITHUB#14161: PointInSetQuery's constructor now throws IllegalArgumentExceptiondiff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.javaindex f6b88424a76..4b6244c1852 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.java@@ -19,7 +19,7 @@ package org.apache.lucene.util.hnsw;import static org.apache.lucene.search.DocIdSetIterator.NO_MORE_DOCS;import java.io.IOException;-import java.util.Comparator;+import java.util.Arrays;import org.apache.lucene.codecs.KnnVectorsReader;import org.apache.lucene.codecs.hnsw.HnswGraphProvider;import org.apache.lucene.index.FieldInfo;@@ -57,14 +57,12 @@ public class ConcurrentHnswMerger extends IncrementalHnswGraphMerger {OnHeapHnswGraph graph;BitSet initializedNodes = null;- if (graphReaders.size() == 0) {+ if (largestGraphReader == null) {graph = new OnHeapHnswGraph(M, maxOrd);} else {- graphReaders.sort(Comparator.comparingInt(GraphReader::graphSize).reversed());- GraphReader initGraphReader = graphReaders.get(0);- KnnVectorsReader initReader = initGraphReader.reader();- MergeState.DocMap initDocMap = initGraphReader.initDocMap();- int initGraphSize = initGraphReader.graphSize();+ KnnVectorsReader initReader = largestGraphReader.reader();+ MergeState.DocMap initDocMap = largestGraphReader.initDocMap();+ int initGraphSize = largestGraphReader.graphSize();HnswGraph initializerGraph = ((HnswGraphProvider) initReader).getGraph(fieldInfo.name);if (initializerGraph.size() == 0) {@@ -79,7 +77,9 @@ public class ConcurrentHnswMerger extends IncrementalHnswGraphMerger {initGraphSize,mergedVectorValues,initializedNodes);- graph = InitializedHnswGraphBuilder.initGraph(initializerGraph, oldToNewOrdinalMap, maxOrd);+ graph =+ InitializedHnswGraphBuilder.initGraph(+ initializerGraph, oldToNewOrdinalMap, maxOrd, beamWidth, scorerSupplier);}}return new HnswConcurrentMergeBuilder(@@ -117,6 +117,9 @@ public class ConcurrentHnswMerger extends IncrementalHnswGraphMerger {docId != NO_MORE_DOCS;docId = initializerIterator.nextDoc()) {int newId = initDocMap.get(docId);+ if (newId == -1) {+ continue;+ }maxNewDocID = Math.max(newId, maxNewDocID);assert newIdToOldOrdinal.containsKey(newId) == false;newIdToOldOrdinal.put(newId, initializerIterator.index());@@ -126,6 +129,7 @@ public class ConcurrentHnswMerger extends IncrementalHnswGraphMerger {return new int[0];}final int[] oldToNewOrdinalMap = new int[initGraphSize];+ Arrays.fill(oldToNewOrdinalMap, -1);KnnVectorValues.DocIndexIterator mergedVectorIterator = mergedVectorValues.iterator();for (int newDocId = mergedVectorIterator.nextDoc();newDocId <= maxNewDocID;diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphBuilder.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphBuilder.javaindex cd54443ab76..70f607d3b5d 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphBuilder.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphBuilder.java@@ -64,14 +64,14 @@ public class HnswGraphBuilder implements HnswBuilder {@SuppressWarnings("NonFinalStaticField")public static long randSeed = DEFAULT_RAND_SEED;- private final int M; // max number of connections on upper layers+ protected final int M; // max number of connections on upper layersprivate final double ml;private final SplittableRandom random;- private final UpdateableRandomVectorScorer scorer;- private final HnswGraphSearcher graphSearcher;+ protected final UpdateableRandomVectorScorer scorer;+ protected final HnswGraphSearcher graphSearcher;private final GraphBuilderKnnCollector entryCandidates; // for upper levels of graph search- private final GraphBuilderKnnCollector+ protected final GraphBuilderKnnCollectorbeamCandidates; // for levels of graph where we add the nodeprivate final GraphBuilderKnnCollector beamCandidates0;@@ -288,7 +288,7 @@ public class HnswGraphBuilder implements HnswBuilder {// then do connections from bottom upfor (int i = 0; i < scratchPerLevel.length; i++) {- addDiverseNeighbors(i + lowestUnsetLevel, node, scratchPerLevel[i], scorer);+ addDiverseNeighbors(i + lowestUnsetLevel, node, scratchPerLevel[i], scorer, false);}lowestUnsetLevel += scratchPerLevel.length;assert lowestUnsetLevel == Math.min(nodeLevel, curMaxLevel) + 1;@@ -344,17 +344,22 @@ public class HnswGraphBuilder implements HnswBuilder {return now;}- private void addDiverseNeighbors(- int level, int node, NeighborArray candidates, UpdateableRandomVectorScorer scorer)+ void addDiverseNeighbors(+ int level,+ int node,+ NeighborArray candidates,+ UpdateableRandomVectorScorer scorer,+ boolean outOfOrderInsertion)throws IOException {/* For each of the beamWidth nearest candidates (going from best to worst), select it only if it* is closer to target than it is to any of the already-selected neighbors (ie selected in this method,* since the node is new and has no prior neighbors).*/NeighborArray neighbors = hnsw.getNeighbors(level, node);- assert neighbors.size() == 0; // new nodeint maxConnOnLevel = level == 0 ? M * 2 : M;- boolean[] mask = selectAndLinkDiverse(neighbors, candidates, maxConnOnLevel, scorer);+ boolean[] mask =+ selectAndLinkDiverse(+ node, neighbors, candidates, maxConnOnLevel, scorer, outOfOrderInsertion);// Link the selected nodes to the new node, and the new node to the selected nodes (again// applying diversity heuristic)@@ -386,10 +391,12 @@ public class HnswGraphBuilder implements HnswBuilder {* are selected*/private boolean[] selectAndLinkDiverse(+ int node,NeighborArray neighbors,NeighborArray candidates,int maxConnOnLevel,- UpdateableRandomVectorScorer scorer)+ UpdateableRandomVectorScorer scorer,+ boolean outOfOrderInsertion)throws IOException {boolean[] mask = new boolean[candidates.size()];// Select the best maxConnOnLevel neighbors of the new node, applying the diversity heuristic@@ -397,6 +404,9 @@ public class HnswGraphBuilder implements HnswBuilder {// compare each neighbor (in distance order) against the closer neighbors selected so far,// only adding it if it is closer to the target than to any of the other selected neighborsint cNode = candidates.nodes()[i];+ if (node == cNode) {+ continue;+ }float cScore = candidates.getScores(i);assert cNode <= hnsw.maxNodeId();scorer.setScoringOrdinal(cNode);@@ -404,13 +414,17 @@ public class HnswGraphBuilder implements HnswBuilder {mask[i] = true;// here we don't need to lock, because there's no incoming link so no others is able to// discover this node such that no others will modify this neighbor array as well- neighbors.addInOrder(cNode, cScore);+ if (outOfOrderInsertion) {+ neighbors.addOutOfOrder(cNode, cScore);+ } else {+ neighbors.addInOrder(cNode, cScore);+ }}}return mask;}- private static void popToScratch(GraphBuilderKnnCollector candidates, NeighborArray scratch) {+ static void popToScratch(GraphBuilderKnnCollector candidates, NeighborArray scratch) {scratch.clear();int candidateCount = candidates.size();// extract all the Neighbors from the queue into an array; these will now bediff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.javaindex a29afeb615f..dfedb66feda 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.java@@ -20,16 +20,16 @@ import static org.apache.lucene.search.DocIdSetIterator.NO_MORE_DOCS;import java.io.IOException;import java.util.ArrayList;+import java.util.Arrays;import java.util.Comparator;import java.util.List;import org.apache.lucene.codecs.KnnVectorsReader;import org.apache.lucene.codecs.hnsw.HnswGraphProvider;-import org.apache.lucene.index.ByteVectorValues;import org.apache.lucene.index.FieldInfo;-import org.apache.lucene.index.FloatVectorValues;import org.apache.lucene.index.KnnVectorValues;import org.apache.lucene.index.MergeState;import org.apache.lucene.internal.hppc.IntIntHashMap;+import org.apache.lucene.search.DocIdSetIterator;import org.apache.lucene.util.BitSet;import org.apache.lucene.util.Bits;import org.apache.lucene.util.FixedBitSet;@@ -48,8 +48,20 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {protected final int beamWidth;protected List<GraphReader> graphReaders = new ArrayList<>();+ protected GraphReader largestGraphReader;+private int numReaders = 0;+ /**+ * The maximum acceptable deletion percentage for a graph to be considered as the base graph.+ * Graphs with deletion percentages above this threshold are not used for initialization as they+ * may have degraded connectivity.+ *+ * <p>A value of 40 means that if more than 40% of the graph's original vectors have been deleted,+ * the graph will not be selected as the base.+ */+ private final int DELETE_PCT_THRESHOLD = 40;+/** Represents a vector reader that contains graph info. */protected record GraphReader(KnnVectorsReader reader, MergeState.DocMap initDocMap, int graphSize) {}@@ -67,13 +79,13 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {/*** Adds a reader to the graph merger if it meets the following criteria: 1. does not contain any- * deleted docs 2. is a HnswGraphProvider+ * deleted vector 2. is a HnswGraphProvider*/@Overridepublic IncrementalHnswGraphMerger addReader(KnnVectorsReader reader, MergeState.DocMap docMap, Bits liveDocs) throws IOException {numReaders++;- if (hasDeletes(liveDocs) || !(reader instanceof HnswGraphProvider)) {+ if (!(reader instanceof HnswGraphProvider)) {return this;}HnswGraph graph = ((HnswGraphProvider) reader).getGraph(fieldInfo.name);@@ -81,24 +93,29 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {return this;}- int candidateVectorCount = 0;- switch (fieldInfo.getVectorEncoding()) {- case BYTE -> {- ByteVectorValues byteVectorValues = reader.getByteVectorValues(fieldInfo.name);- if (byteVectorValues == null) {- return this;- }- candidateVectorCount = byteVectorValues.size();- }- case FLOAT32 -> {- FloatVectorValues vectorValues = reader.getFloatVectorValues(fieldInfo.name);- if (vectorValues == null) {- return this;- }- candidateVectorCount = vectorValues.size();- }+ KnnVectorValues knnVectorValues =+ switch (fieldInfo.getVectorEncoding()) {+ case BYTE -> reader.getByteVectorValues(fieldInfo.name);+ case FLOAT32 -> reader.getFloatVectorValues(fieldInfo.name);+ };++ int candidateVectorCount = countLiveVectors(liveDocs, knnVectorValues);+ int graphSize = graph.size();++ GraphReader graphReader = new GraphReader(reader, docMap, graphSize);++ int deletePct = ((graphSize - candidateVectorCount) * 100) / graphSize;++ if (deletePct <= DELETE_PCT_THRESHOLD+ && (largestGraphReader == null || candidateVectorCount > largestGraphReader.graphSize)) {+ largestGraphReader = graphReader;}- graphReaders.add(new GraphReader(reader, docMap, candidateVectorCount));++ // if graph has no deletes+ if (candidateVectorCount == graphSize) {+ graphReaders.add(graphReader);+ }+return this;}@@ -112,11 +129,15 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {*/protected HnswBuilder createBuilder(KnnVectorValues mergedVectorValues, int maxOrd)throws IOException {- if (graphReaders.size() == 0) {+ if (largestGraphReader == null) {return HnswGraphBuilder.create(scorerSupplier, M, beamWidth, HnswGraphBuilder.randSeed, maxOrd);}- graphReaders.sort(Comparator.comparingInt(GraphReader::graphSize).reversed());+ if (!graphReaders.contains(largestGraphReader)) {+ graphReaders.addFirst(largestGraphReader);+ } else {+ graphReaders.sort(Comparator.comparingInt(GraphReader::graphSize).reversed());+ }final BitSet initializedNodes =graphReaders.size() == numReaders ? null : new FixedBitSet(maxOrd);@@ -163,6 +184,7 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {newDocIdToOldOrdinals[i].put(newDocId, vectorsIter.index());}oldToNewOrdinalMap[i] = new int[graphReaders.get(i).graphSize];+ Arrays.fill(oldToNewOrdinalMap[i], -1);}KnnVectorValues.DocIndexIterator mergedVectorIterator = mergedVectorValues.iterator();@@ -192,16 +214,21 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {return builder.build(maxOrd);}- private static boolean hasDeletes(Bits liveDocs) {+ private static int countLiveVectors(Bits liveDocs, KnnVectorValues knnVectorValues)+ throws IOException {if (liveDocs == null) {- return false;+ return knnVectorValues.size();}- for (int i = 0; i < liveDocs.length(); i++) {- if (!liveDocs.get(i)) {- return true;+ int count = 0;+ DocIdSetIterator docIdSetIterator = knnVectorValues.iterator();+ for (int doc = docIdSetIterator.nextDoc();+ doc != NO_MORE_DOCS;+ doc = docIdSetIterator.nextDoc()) {+ if (liveDocs.get(doc)) {+ count++;}}- return false;+ return count;}}diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/InitializedHnswGraphBuilder.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/InitializedHnswGraphBuilder.javaindex 7dff036ddde..511474b2f70 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/InitializedHnswGraphBuilder.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/InitializedHnswGraphBuilder.java@@ -20,29 +20,86 @@ package org.apache.lucene.util.hnsw;import static org.apache.lucene.search.DocIdSetIterator.NO_MORE_DOCS;import java.io.IOException;+import java.util.ArrayList;+import java.util.HashMap;+import java.util.Iterator;+import java.util.List;+import java.util.Map;+import java.util.SplittableRandom;+import org.apache.lucene.internal.hppc.IntArrayList;+import org.apache.lucene.internal.hppc.IntCursor;+import org.apache.lucene.util.ArrayUtil;import org.apache.lucene.util.BitSet;/*** This creates a graph builder that is initialized with the provided HnswGraph. This is useful for* merging HnswGraphs from multiple segments.*+ * <p>The builder performs the following operations:+ *+ * <ul>+ * <li>Copies the graph structure from the initializer graph with ordinal remapping+ * <li>Identifies and repairs disconnected nodes (nodes that lost a portion of their neighbors due+ * to deletions)+ * <li>Rebalances the graph hierarchy to maintain proper level distribution according to the HNSW+ * probabilistic model+ * <li>Allows incremental addition of new nodes while preserving initialized nodes+ * </ul>+ *+ * <p><b>Disconnected Node Detection:</b> A node is considered disconnected if it retains less than+ * {@link #DISCONNECTED_NODE_FACTOR} of its original neighbor count from the source graph. This+ * typically occurs when many of the node's neighbors were deleted documents that couldn't be+ * remapped.+ ** @lucene.experimental*/public final class InitializedHnswGraphBuilder extends HnswGraphBuilder {/**- * Create a new HnswGraphBuilder that is initialized with the provided HnswGraph.- *- * @param scorerSupplier the scorer to use for vectors- * @param beamWidth the number of nodes to explore in the search- * @param seed the seed for the random number generator- * @param initializerGraph the graph to initialize the new graph builder- * @param newOrdMap a mapping from the old node ordinal to the new node ordinal- * @param initializedNodes a bitset of nodes that are already initialized in the initializerGraph- * @param totalNumberOfVectors the total number of vectors in the new graph, this should include- * all vectors expected to be added to the graph in the future- * @return a new HnswGraphBuilder that is initialized with the provided HnswGraph- * @throws IOException when reading the graph fails+ * Tracks which nodes have already been initialized from the source graph. These nodes will be+ * skipped during subsequent {@link #addGraphNode(int)} calls to avoid duplicate processing.+ */+ private final BitSet initializedNodes;++ /**+ * Maps each level in the graph hierarchy to the list of node ordinals present at that level. Used+ * during graph rebalancing to identify candidates for promotion to higher levels.+ */+ private IntArrayList[] levelToNodes;++ /**+ * The threshold factor for determining if a node is disconnected. A node is considered+ * disconnected if its new neighbor count is less than {@code (old neighbor count *+ * DISCONNECTED_NODE_FACTOR)}.+ *+ * <p>This helps identify nodes that have lost a significant portion of their neighbors (typically+ * due to document deletions) and need additional connections to maintain graph connectivity and+ * search performance.+ */+ private final double DISCONNECTED_NODE_FACTOR = 0.85;++ // Tracks if the graph has deletes+ private boolean hasDeletes = false;++ /**+ * Creates an initialized HNSW graph builder from an existing graph.+ *+ * <p>This factory method constructs a new graph builder, initializes it with the structure from+ * the provided graph (applying ordinal remapping), and returns the builder ready for additional+ * operations.+ *+ * @param scorerSupplier provides vector similarity scoring for graph operations+ * @param beamWidth the search beam width for finding neighbors during graph construction+ * @param seed random seed for level assignment and node promotion during rebalancing+ * @param initializerGraph the source graph to copy structure from+ * @param newOrdMap maps old ordinals in the initializer graph to new ordinals in the merged+ * graph; -1 indicates a deleted document that should be skipped+ * @param initializedNodes bit set marking which nodes are already initialized (can be null if not+ * tracking)+ * @param totalNumberOfVectors the total number of vectors in the merged graph (used for+ * pre-allocation)+ * @return a new builder initialized with the provided graph structure+ * @throws IOException if an I/O error occurs during graph initialization*/public static InitializedHnswGraphBuilder fromGraph(RandomVectorScorerSupplier scorerSupplier,@@ -53,49 +110,338 @@ public final class InitializedHnswGraphBuilder extends HnswGraphBuilder {BitSet initializedNodes,int totalNumberOfVectors)throws IOException {- return new InitializedHnswGraphBuilder(- scorerSupplier,- beamWidth,- seed,- initGraph(initializerGraph, newOrdMap, totalNumberOfVectors),- initializedNodes);++ InitializedHnswGraphBuilder builder =+ new InitializedHnswGraphBuilder(+ scorerSupplier,+ beamWidth,+ seed,+ new OnHeapHnswGraph(initializerGraph.maxConn(), totalNumberOfVectors),+ initializedNodes);++ builder.initializeFromGraph(initializerGraph, newOrdMap);+ return builder;}+ /**+ * Convenience method to create a fully initialized on-heap HNSW graph without tracking+ * initialized nodes. This is useful when you just need the resulting graph structure without+ * planning to add additional nodes incrementally.+ *+ * @param initializerGraph the source graph to copy structure from+ * @param newOrdMap maps old ordinals to new ordinals; -1 indicates deleted documents+ * @param totalNumberOfVectors the total number of vectors in the merged graph+ * @param beamWidth the search beam width for graph construction+ * @param scorerSupplier provides vector similarity scoring+ * @return a fully initialized on-heap HNSW graph+ * @throws IOException if an I/O error occurs during graph initialization+ */public static OnHeapHnswGraph initGraph(- HnswGraph initializerGraph, int[] newOrdMap, int totalNumberOfVectors) throws IOException {- OnHeapHnswGraph hnsw = new OnHeapHnswGraph(initializerGraph.maxConn(), totalNumberOfVectors);- for (int level = initializerGraph.numLevels() - 1; level >= 0; level--) {+ HnswGraph initializerGraph,+ int[] newOrdMap,+ int totalNumberOfVectors,+ int beamWidth,+ RandomVectorScorerSupplier scorerSupplier)+ throws IOException {++ InitializedHnswGraphBuilder builder =+ fromGraph(+ scorerSupplier,+ beamWidth,+ randSeed,+ initializerGraph,+ newOrdMap,+ null,+ totalNumberOfVectors);+ return builder.getGraph();+ }++ private InitializedHnswGraphBuilder(+ RandomVectorScorerSupplier scorerSupplier,+ int beamWidth,+ long seed,+ OnHeapHnswGraph initializedGraph,+ BitSet initializedNodes)+ throws IOException {+ super(scorerSupplier, beamWidth, seed, initializedGraph);+ this.initializedNodes = initializedNodes;+ }++ /**+ * Initializes the graph from the provided initializer graph through a three-phase process:+ *+ * <ol>+ * <li>Copy the graph structure with ordinal remapping, identifying disconnected nodes+ * <li>If deletions occurred, repair disconnected nodes by finding additional neighbors+ * <li>If deletions occurred, rebalance the graph hierarchy to maintain proper level+ * distribution+ * </ol>+ *+ * @param initializerGraph the source graph to copy from+ * @param newOrdMap ordinal mapping from old to new ordinals+ * @throws IOException if an I/O error occurs during initialization+ */+ private void initializeFromGraph(HnswGraph initializerGraph, int[] newOrdMap) throws IOException {+ hasDeletes = false;+ // Phase 1: Copy structure and identify nodes that lost too many neighbors+ Map<Integer, List<Integer>> disconnectedNodesByLevel =+ copyGraphStructure(initializerGraph, newOrdMap);++ // Repair graph if it has deletes+ if (hasDeletes) {+ // Phase 2: Repair nodes with insufficient connections+ repairDisconnectedNodes(disconnectedNodesByLevel, initializerGraph.numLevels());++ // Phase 3: Rebalance graph to maintain proper level distribution+ rebalanceGraph();+ }+ }++ /**+ * Copies the graph structure from the initializer graph, applying ordinal remapping and+ * identifying nodes that have lost neighbors.+ *+ * <p>A node is considered disconnected if it retains less than {@link #DISCONNECTED_NODE_FACTOR}+ * of its original neighbors. This happens when many neighbors were deleted documents that+ * couldn't be remapped (indicated by -1 in newOrdMap).+ *+ * <p><b>Example:</b> With DISCONNECTED_NODE_FACTOR = 0.9, if a node had 20 neighbors in the+ * source graph but only 17 remain after remapping (17/20 = 0.85 < 0.9), it's marked as+ * disconnected and will be repaired.+ *+ * @param initializerGraph the source graph to copy from+ * @param newOrdMap maps old ordinals to new ordinals; -1 indicates deleted documents+ * @return map of level to list of disconnected node ordinals at that level+ * @throws IOException if an I/O error occurs during graph traversal+ */+ private Map<Integer, List<Integer>> copyGraphStructure(+ HnswGraph initializerGraph, int[] newOrdMap) throws IOException {+ int numLevels = initializerGraph.numLevels();+ levelToNodes = new IntArrayList[numLevels];+ Map<Integer, List<Integer>> disconnectedNodesByLevel = new HashMap<>(numLevels);++ for (int level = numLevels - 1; level >= 0; level--) {+ levelToNodes[level] = new IntArrayList();+ List<Integer> disconnectedNodes = new ArrayList<>();HnswGraph.NodesIterator it = initializerGraph.getNodesOnLevel(level);+while (it.hasNext()) {int oldOrd = it.nextInt();int newOrd = newOrdMap[oldOrd];++ // Skip deleted documents (mapped to -1)+ if (newOrd == -1) {+ hasDeletes = true;+ continue;+ }+hnsw.addNode(level, newOrd);+ levelToNodes[level].add(newOrd);hnsw.trySetNewEntryNode(newOrd, level);+ scorer.setScoringOrdinal(newOrd);++ // Copy neighborsNeighborArray newNeighbors = hnsw.getNeighbors(level, newOrd);initializerGraph.seek(level, oldOrd);+ int oldNeighbourCount = 0;for (int oldNeighbor = initializerGraph.nextNeighbor();oldNeighbor != NO_MORE_DOCS;oldNeighbor = initializerGraph.nextNeighbor()) {+ oldNeighbourCount++;int newNeighbor = newOrdMap[oldNeighbor];- // we will compute these scores later when we need to pop out the non-diverse nodes- newNeighbors.addOutOfOrder(newNeighbor, Float.NaN);++ // Only add neighbors that weren't deleted+ if (newNeighbor != -1) {+ newNeighbors.addOutOfOrder(newNeighbor, Float.NaN);+ }+ }++ // Mark as disconnected if node lost more than the acceptable threshold of neighbors+ if (newNeighbors.size() < oldNeighbourCount * DISCONNECTED_NODE_FACTOR) {+ disconnectedNodes.add(newOrd);}}+ disconnectedNodesByLevel.put(level, disconnectedNodes);}- return hnsw;+ return disconnectedNodesByLevel;}- private final BitSet initializedNodes;+ /**+ * Repairs disconnected nodes at all levels by finding additional neighbors to restore+ * connectivity.+ *+ * @param disconnectedNodesByLevel map of level to disconnected nodes at that level+ * @param numLevels total number of levels in the graph hierarchy+ * @throws IOException if an I/O error occurs during repair operations+ */+ private void repairDisconnectedNodes(+ Map<Integer, List<Integer>> disconnectedNodesByLevel, int numLevels) throws IOException {+ for (int level = numLevels - 1; level >= 0; level--) {+ fixDisconnectedNodes(disconnectedNodesByLevel.get(level), level, scorer);+ }+ }- public InitializedHnswGraphBuilder(- RandomVectorScorerSupplier scorerSupplier,- int beamWidth,- long seed,- OnHeapHnswGraph initializedGraph,- BitSet initializedNodes)+ /**+ * Fixes disconnected nodes at a specific level by performing graph searches from their existing+ * neighbors to find additional connections.+ *+ * <p>For each disconnected node:+ *+ * <ol>+ * <li>Use existing neighbors as entry points for graph search+ * <li>Search the level to find candidate neighbors+ * <li>Add diverse neighbors using the HNSW heuristic selection algorithm+ * </ol>+ *+ * <p>If a node has no neighbors at all, it cannot be repaired at this level and will rely on the+ * rebalancing phase.+ *+ * @param disconnectedNodes list of node ordinals that need additional neighbors+ * @param level the level at which to repair connections+ * @param scorer vector similarity scorer for distance calculations+ * @throws IOException if an I/O error occurs during search operations+ */+ private void fixDisconnectedNodes(+ List<Integer> disconnectedNodes, int level, UpdateableRandomVectorScorer scorer)throws IOException {- super(scorerSupplier, beamWidth, seed, initializedGraph);- this.initializedNodes = initializedNodes;+ if (disconnectedNodes.isEmpty()) return;++ int beamWidth = beamCandidates.k();+ GraphBuilderKnnCollector candidates = new GraphBuilderKnnCollector(beamWidth);+ NeighborArray scratchArray = new NeighborArray(beamWidth, false);++ for (int node : disconnectedNodes) {+ scorer.setScoringOrdinal(node);+ NeighborArray existingNeighbors = hnsw.getNeighbors(level, node);++ // Only repair if node has at least one neighbor to use as entry point+ if (existingNeighbors.size() > 0) {+ // Use all existing neighbors as entry points for search+ int[] entryPoints = new int[existingNeighbors.size()];+ System.arraycopy(existingNeighbors.nodes(), 0, entryPoints, 0, existingNeighbors.size());++ // Search from entry points to find candidate neighbors+ graphSearcher.searchLevel(candidates, scorer, level, entryPoints, hnsw, null);+ popToScratch(candidates, scratchArray);++ // Add diverse neighbors using HNSW heuristic (prunes similar neighbors)+ addDiverseNeighbors(level, node, scratchArray, scorer, true);+ } else {+ // Node has no nighbors, add connections from scratch+ addConnections(node, level, scorer);+ }++ // Clear for next iteration+ scratchArray.clear();+ candidates.clear();+ }+ }++ /**+ * Rebalances the graph hierarchy by promoting nodes from lower levels to higher levels to+ * maintain the expected exponential decay in level sizes according to the HNSW probabilistic+ * model.+ *+ * <p>The expected number of nodes at each level follows the formula: <br>+ * {@code maxNodesAtLevel = totalNodes * (1/M)^level}+ *+ * <p>For each level that has fewer nodes than expected, this method randomly promotes nodes from+ * the level below with probability 1/M until the target count is reached.+ *+ * <p>This rebalancing is necessary during merging graph where deletions may have disrupted the+ * proper hierarchical distribution, which could degrade semantic matches quality.+ *+ * @throws IOException if an I/O error occurs during node promotion+ */+ private void rebalanceGraph() throws IOException {+ SplittableRandom random = new SplittableRandom();+ int size = hnsw.size();+ double invMaxConn = 1.0 / M;++ // Process each level starting from level 1 (level 0 always contains all nodes)+ for (int level = 1; ; level++) {++ // Calculate expected number of nodes at this level+ int maxNodesAtLevel = (int) (size * Math.pow(invMaxConn, level));+ if (maxNodesAtLevel <= 0) break; // Stop when expected nodes drops to zero++ int currentNodesAtLevel = 0;++ // Expand levelToNodes array if we need to create new levels+ if (level >= levelToNodes.length) {+ levelToNodes = ArrayUtil.growExact(levelToNodes, level + 1);+ levelToNodes[level] = new IntArrayList();+ } else {+ currentNodesAtLevel = levelToNodes[level].size();+ }++ // Skip if this level already has enough nodes+ if (currentNodesAtLevel >= maxNodesAtLevel) continue;++ // Randomly promote nodes from the level below+ Iterator<IntCursor> it = levelToNodes[level - 1].iterator();++ while (it.hasNext() && currentNodesAtLevel < maxNodesAtLevel) {+ int node = it.next().value;++ // Promote with probability 1/M, matching HNSW's level assignment distribution+ if (random.nextDouble() < invMaxConn && !hnsw.nodeExistAtLevel(level, node)) {+ scorer.setScoringOrdinal(node);+ hnsw.addNode(level, node);++ // If this is the first node at this level, try to make it the entry point+ if (currentNodesAtLevel == 0) {+ hnsw.tryPromoteNewEntryNode(node, level, hnsw.numLevels() - 1);+ } else {+ // Add connections for non-first nodes+ addConnections(node, level, scorer);+ }++ levelToNodes[level].add(node);+ currentNodesAtLevel++;+ }+ }+ }+ }++ /**+ * Adds connections for an existing node at a specific level in the graph hierarchy.+ *+ * <p>The process involves:+ *+ * <ol>+ * <li>Navigate down from the top level to find the closest node at the target level+ * <li>Perform a full search at the target level to find neighbors+ * <li>Add diverse neighbors using the HNSW heuristic selection+ * </ol>+ *+ * @param node the node ordinal to add connections for+ * @param targetLevel the level to add connections at+ * @param scorer vector similarity scorer for distance calculations+ * @throws IOException if an I/O error occurs during search or neighbor addition+ */+ private void addConnections(int node, int targetLevel, UpdateableRandomVectorScorer scorer)+ throws IOException {++ int beamWidth = beamCandidates.k();+ GraphBuilderKnnCollector candidates = new GraphBuilderKnnCollector(beamWidth);+ int[] eps = {hnsw.entryNode()};++ // Navigate down from top to target level, greedily moving toward the new node+ for (int level = hnsw.numLevels() - 1; level > targetLevel; level--) {+ graphSearcher.searchLevel(candidates, scorer, level, eps, hnsw, null);+ eps[0] = candidates.popNode();+ candidates.clear();+ }++ // Perform full search at target level to find neighbors+ graphSearcher.searchLevel(candidates, scorer, targetLevel, eps, hnsw, null);++ NeighborArray scratchArray = new NeighborArray(beamWidth, false);+ popToScratch(candidates, scratchArray);++ // Add diverse neighbors and establish bidirectional connections+ addDiverseNeighbors(targetLevel, node, scratchArray, scorer, true);}@Overridediff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/MergingHnswGraphBuilder.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/MergingHnswGraphBuilder.javaindex ea02a4bfdb2..664ed67082b 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/MergingHnswGraphBuilder.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/MergingHnswGraphBuilder.java@@ -99,7 +99,8 @@ public final class MergingHnswGraphBuilder extends HnswGraphBuilder {BitSet initializedNodes)throws IOException {OnHeapHnswGraph graph =- InitializedHnswGraphBuilder.initGraph(graphs[0], ordMaps[0], totalNumberOfVectors);+ InitializedHnswGraphBuilder.initGraph(+ graphs[0], ordMaps[0], totalNumberOfVectors, beamWidth, scorerSupplier);return new MergingHnswGraphBuilder(scorerSupplier, beamWidth, seed, graph, graphs, ordMaps, initializedNodes);}diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/OnHeapHnswGraph.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/OnHeapHnswGraph.javaindex adda151df93..3165e90bc55 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/OnHeapHnswGraph.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/OnHeapHnswGraph.java@@ -151,13 +151,15 @@ public final class OnHeapHnswGraph extends HnswGraph implements Accountable {graph = ArrayUtil.grow(graph, node + 1);}- assert graph[node] == null || graph[node].length > level- : "node must be inserted from the top level";+ assert graph[node] == null || graph[node].length >= level+ : "node must be inserted from the top level: ";if (graph[node] == null) {- graph[node] =- new NeighborArray[level + 1]; // assumption: we always call this function from top level+ graph[node] = new NeighborArray[level + 1];size.incrementAndGet();+ } else if (graph[node].length <= level) {+ graph[node] = ArrayUtil.growExact(graph[node], level + 1);}+if (level == 0) {graph[node][level] =new NeighborArray(@@ -216,6 +218,10 @@ public final class OnHeapHnswGraph extends HnswGraph implements Accountable {return nsize - 1;}+ public boolean nodeExistAtLevel(int level, int node) {+ return graph[node] != null && graph[node].length > level;+ }+/*** Returns the graph's current entry node on the top level shown as ordinals of the nodes on 0th* leveldiff --git a/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java b/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.javaindex 8e8d27a185f..97ea04d2da8 100644--- a/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java+++ b/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java@@ -206,6 +206,77 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {}}+ @SuppressWarnings("unchecked")+ public void testGraphMergeWithDeletes() throws IOException {++ int M = 4;+ int beamWidth = 20;+ String vectorFieldName = "vec1";+ int numVectors = random().nextInt(1000);+ int deletionProbaility = random().nextInt(100);+ int dim = random().nextInt(64) + 1;+ if (dim % 2 == 1) {+ dim++;+ }+ KnnVectorValues vectors = vectorValues(numVectors, dim);+ int deleteCount = 0;++ try (Directory dir = newDirectory()) {+ IndexWriterConfig iwc =+ new IndexWriterConfig()+ .setCodec(+ TestUtil.alwaysKnnVectorsFormat(new Lucene99HnswVectorsFormat(M, beamWidth, 0)))+ // set a random merge policy+ .setMergePolicy(newMergePolicy(random()));+ try (IndexWriter w = new IndexWriter(dir, iwc)) {++ for (int i = 0; i < numVectors; i++) {+ Document doc = new Document();+ switch (vectors.getEncoding()) {+ case BYTE -> {+ doc.add(+ knnVectorField(+ vectorFieldName,+ (T) ((ByteVectorValues) vectors).vectorValue(i),+ similarityFunction));+ }+ case FLOAT32 -> {+ doc.add(+ knnVectorField(+ vectorFieldName,+ (T) ((FloatVectorValues) vectors).vectorValue(i),+ similarityFunction));+ }+ }+ doc.add(new StringField("id", Integer.toString(i), Field.Store.NO));+ w.addDocument(doc);+ }+ w.commit();++ for (int d = 0; d < numVectors; d++) {+ if (random().nextInt(100) < deletionProbaility) {+ deleteCount++;+ w.deleteDocuments(new Term("id", Integer.toString(d)));+ }+ }+ w.commit();+ w.forceMerge(1);+ }++ try (IndexReader reader = DirectoryReader.open(dir)) {+ for (LeafReaderContext ctx : reader.leaves()) {+ HnswGraph graphValues =+ ((Lucene99HnswVectorsReader)+ ((CodecReader) ctx.reader())+ .getVectorReader()+ .unwrapReaderForField(vectorFieldName))+ .getGraph(vectorFieldName);+ assertEquals(numVectors - deleteCount, graphValues.size());+ }+ }+ }+ }+@SuppressWarnings("unchecked")private T vectorValue(KnnVectorValues vectors, int ord) throws IOException {switch (vectors.getEncoding()) {@@ -546,12 +617,13 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {int initializerSize = random().nextInt(5, totalSize);int docIdOffset = 0;int dim = atLeast(10);+ int beamWidth = 30;long seed = random().nextLong();KnnVectorValues initializerVectors = vectorValues(initializerSize, dim);RandomVectorScorerSupplier initialscorerSupplier = buildScorerSupplier(initializerVectors);HnswGraphBuilder initializerBuilder =- HnswGraphBuilder.create(initialscorerSupplier, 10, 30, seed);+ HnswGraphBuilder.create(initialscorerSupplier, 10, beamWidth, seed);OnHeapHnswGraph initializerGraph = initializerBuilder.build(initializerVectors.size());KnnVectorValues finalVectorValues =@@ -566,7 +638,11 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {// another graph to do the assertionOnHeapHnswGraph graphAfterInit =InitializedHnswGraphBuilder.initGraph(- initializerGraph, initializerOrdMap, initializerGraph.size());+ initializerGraph,+ initializerOrdMap,+ initializerGraph.size(),+ beamWidth,+ initialscorerSupplier);HnswGraphBuilder finalBuilder =InitializedHnswGraphBuilder.fromGraph(diff --git a/lucene/core/src/test/org/apache/lucene/util/hnsw/TestOnHeapHnswGraph.java b/lucene/core/src/test/org/apache/lucene/util/hnsw/TestOnHeapHnswGraph.javaindex 082079deb8f..e11331b9db1 100644--- a/lucene/core/src/test/org/apache/lucene/util/hnsw/TestOnHeapHnswGraph.java+++ b/lucene/core/src/test/org/apache/lucene/util/hnsw/TestOnHeapHnswGraph.java@@ -33,16 +33,6 @@ public class TestOnHeapHnswGraph extends LuceneTestCase {expectThrows(IllegalStateException.class, () -> graph.addNode(1, 100));}- /* AssertionError will be thrown if we add a node not from top most level,- (likely NPE will be thrown in prod) */- public void testAddLevelOutOfOrder() {- OnHeapHnswGraph graph = new OnHeapHnswGraph(10, -1);- graph.addNode(0, 0);- if (TEST_ASSERTS_ENABLED) {- expectThrows(AssertionError.class, () -> graph.addNode(1, 0));- }- }-/* assert exception will be thrown when we call getNodeOnLevel for an incomplete graph */public void testIncompleteGraphThrow() {OnHeapHnswGraph graph = new OnHeapHnswGraph(10, -1);