Skip to content

Apache Lucene open-source search software

HNSW BP reordering (#14097)

Michael Sokolov02a09f6ab124
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt
index 786c511b1de..2e574668a27 100644
--- a/lucene/CHANGES.txt
+++ b/lucene/CHANGES.txt
@@ -11,7 +11,7 @@ API Changes
New Features
---------------------
-(No changes)
+* GITHUB#14097: Binary partitioning merge policy over float-valued vector field. (Mike Sokolov)
Improvements
---------------------
diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsReader.java
index 015fad7490c..698ccff49f7 100644
--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsReader.java
+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsReader.java
@@ -488,6 +488,11 @@ public final class Lucene90HnswVectorsReader extends KnnVectorsReader {
throw new UnsupportedOperationException();
}
+ @Override
+ public int maxConn() {
+ throw new UnsupportedOperationException();
+ }
+
@Override
public NodesIterator getNodesOnLevel(int level) {
throw new UnsupportedOperationException();
diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90OnHeapHnswGraph.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90OnHeapHnswGraph.java
index 845987c2957..835293946dd 100644
--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90OnHeapHnswGraph.java
+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90OnHeapHnswGraph.java
@@ -198,6 +198,11 @@ public final class Lucene90OnHeapHnswGraph extends HnswGraph {
throw new UnsupportedOperationException();
}
+ @Override
+ public int maxConn() {
+ return maxConn;
+ }
+
@Override
public NodesIterator getNodesOnLevel(int level) {
throw new UnsupportedOperationException();
diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsReader.java
index e71fa66719f..80a71196c44 100644
--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsReader.java
+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsReader.java
@@ -548,6 +548,11 @@ public final class Lucene91HnswVectorsReader extends KnnVectorsReader {
return entryNode;
}
+ @Override
+ public int maxConn() {
+ return (int) bytesForConns / Integer.BYTES - 1;
+ }
+
@Override
public NodesIterator getNodesOnLevel(int level) {
if (level == 0) {
diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91OnHeapHnswGraph.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91OnHeapHnswGraph.java
index e762e016bbf..3ebbeee8d8a 100644
--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91OnHeapHnswGraph.java
+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91OnHeapHnswGraph.java
@@ -160,6 +160,11 @@ public final class Lucene91OnHeapHnswGraph extends HnswGraph {
return entryNode;
}
+ @Override
+ public int maxConn() {
+ return maxConn;
+ }
+
@Override
public NodesIterator getNodesOnLevel(int level) {
if (level == 0) {
diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsReader.java
index 034967efbaa..213b3fff4f2 100644
--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsReader.java
+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsReader.java
@@ -459,6 +459,11 @@ public final class Lucene92HnswVectorsReader extends KnnVectorsReader {
return entryNode;
}
+ @Override
+ public int maxConn() {
+ return (int) bytesForConns / Integer.BYTES - 1;
+ }
+
@Override
public NodesIterator getNodesOnLevel(int level) {
if (level == 0) {
diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsReader.java
index 1ad2e302364..e386c2126be 100644
--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsReader.java
+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsReader.java
@@ -448,6 +448,7 @@ public final class Lucene94HnswVectorsReader extends KnnVectorsReader {
final int size;
final long bytesForConns;
final long bytesForConns0;
+ final int maxConn;
int arcCount;
int arcUpTo;
@@ -463,6 +464,7 @@ public final class Lucene94HnswVectorsReader extends KnnVectorsReader {
this.bytesForConns = Math.multiplyExact(Math.addExact(entry.M, 1L), Integer.BYTES);
this.bytesForConns0 =
Math.multiplyExact(Math.addExact(Math.multiplyExact(entry.M, 2L), 1), Integer.BYTES);
+ maxConn = entry.M;
}
@Override
@@ -501,6 +503,11 @@ public final class Lucene94HnswVectorsReader extends KnnVectorsReader {
return numLevels;
}
+ @Override
+ public int maxConn() {
+ return maxConn;
+ }
+
@Override
public int entryNode() {
return entryNode;
diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsReader.java
index b5859daf9f2..99fc82bfc54 100644
--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsReader.java
+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsReader.java
@@ -537,6 +537,11 @@ public final class Lucene95HnswVectorsReader extends KnnVectorsReader implements
return entryNode;
}
+ @Override
+ public int maxConn() {
+ return currentNeighborsBuffer.length / 2;
+ }
+
@Override
public NodesIterator getNodesOnLevel(int level) {
if (level == 0) {
diff --git a/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsWriter.java b/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsWriter.java
index 01698da7989..ec7eb048c8f 100644
--- a/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsWriter.java
+++ b/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsWriter.java
@@ -334,6 +334,11 @@ public final class Lucene94HnswVectorsWriter extends KnnVectorsWriter {
return graph.numLevels();
}
+ @Override
+ public int maxConn() {
+ return graph.maxConn();
+ }
+
@Override
public int entryNode() {
throw new UnsupportedOperationException("Not supported on a mock graph");
diff --git a/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsWriter.java b/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsWriter.java
index c855d8f5e07..55fb3e8ea3e 100644
--- a/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsWriter.java
+++ b/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsWriter.java
@@ -366,6 +366,11 @@ public final class Lucene95HnswVectorsWriter extends KnnVectorsWriter {
throw new UnsupportedOperationException("Not supported on a mock graph");
}
+ @Override
+ public int maxConn() {
+ throw new UnsupportedOperationException("Not supported on a mock graph");
+ }
+
@Override
public NodesIterator getNodesOnLevel(int level) {
if (level == 0) {
diff --git a/lucene/core/src/java/org/apache/lucene/codecs/KnnVectorsReader.java b/lucene/core/src/java/org/apache/lucene/codecs/KnnVectorsReader.java
index 54d070fa599..1a3a5319efa 100644
--- a/lucene/core/src/java/org/apache/lucene/codecs/KnnVectorsReader.java
+++ b/lucene/core/src/java/org/apache/lucene/codecs/KnnVectorsReader.java
@@ -75,7 +75,7 @@ public abstract class KnnVectorsReader implements Closeable {
* TotalHits.Relation.GREATER_THAN_OR_EQUAL_TO}.
*
* <p>The behavior is undefined if the given field doesn't have KNN vectors enabled on its {@link
- * FieldInfo}. The return value is never {@code null}.
+ * FieldInfo}.
*
* @param field the vector field to search
* @param target the vector-valued query
@@ -103,7 +103,7 @@ public abstract class KnnVectorsReader implements Closeable {
* TotalHits.Relation.GREATER_THAN_OR_EQUAL_TO}.
*
* <p>The behavior is undefined if the given field doesn't have KNN vectors enabled on its {@link
- * FieldInfo}. The return value is never {@code null}.
+ * FieldInfo}.
*
* @param field the vector field to search
* @param target the vector-valued query
diff --git a/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsReader.java b/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsReader.java
index ed6388b53cb..b29f9da5b41 100644
--- a/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsReader.java
+++ b/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsReader.java
@@ -491,7 +491,8 @@ public final class Lucene99HnswVectorsReader extends KnnVectorsReader
level == 0
? targetOrd
: Arrays.binarySearch(nodesByLevel[level], 0, nodesByLevel[level].length, targetOrd);
- assert targetIndex >= 0;
+ assert targetIndex >= 0
+ : "seek level=" + level + " target=" + targetOrd + " not found: " + targetIndex;
// unsafe; no bounds checking
dataIn.seek(graphLevelNodeOffsets.get(targetIndex + graphLevelNodeIndexOffsets[level]));
arcCount = dataIn.readVInt();
@@ -526,6 +527,11 @@ public final class Lucene99HnswVectorsReader extends KnnVectorsReader
return numLevels;
}
+ @Override
+ public int maxConn() {
+ return currentNeighborsBuffer.length >> 1;
+ }
+
@Override
public int entryNode() throws IOException {
return entryNode;
diff --git a/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsWriter.java b/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsWriter.java
index 0f4e8196d52..ce9ee1b79cc 100644
--- a/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsWriter.java
+++ b/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsWriter.java
@@ -93,7 +93,6 @@ public final class Lucene99HnswVectorsWriter extends KnnVectorsWriter {
this.numMergeWorkers = numMergeWorkers;
this.mergeExec = mergeExec;
segmentWriteState = state;
-
String metaFileName =
IndexFileNames.segmentFileName(
state.segmentInfo.name, state.segmentSuffix, Lucene99HnswVectorsFormat.META_EXTENSION);
@@ -293,6 +292,11 @@ public final class Lucene99HnswVectorsWriter extends KnnVectorsWriter {
return graph.numLevels();
}
+ @Override
+ public int maxConn() {
+ return graph.maxConn();
+ }
+
@Override
public int entryNode() {
throw new UnsupportedOperationException("Not supported on a mock graph");
diff --git a/lucene/core/src/java/org/apache/lucene/codecs/perfield/PerFieldKnnVectorsFormat.java b/lucene/core/src/java/org/apache/lucene/codecs/perfield/PerFieldKnnVectorsFormat.java
index bc18b231e74..ee9cb5cd5f5 100644
--- a/lucene/core/src/java/org/apache/lucene/codecs/perfield/PerFieldKnnVectorsFormat.java
+++ b/lucene/core/src/java/org/apache/lucene/codecs/perfield/PerFieldKnnVectorsFormat.java
@@ -28,6 +28,7 @@ import org.apache.lucene.codecs.KnnFieldVectorsWriter;
import org.apache.lucene.codecs.KnnVectorsFormat;
import org.apache.lucene.codecs.KnnVectorsReader;
import org.apache.lucene.codecs.KnnVectorsWriter;
+import org.apache.lucene.codecs.hnsw.HnswGraphProvider;
import org.apache.lucene.index.ByteVectorValues;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.FieldInfos;
@@ -41,6 +42,7 @@ import org.apache.lucene.internal.hppc.ObjectCursor;
import org.apache.lucene.search.KnnCollector;
import org.apache.lucene.util.Bits;
import org.apache.lucene.util.IOUtils;
+import org.apache.lucene.util.hnsw.HnswGraph;
/**
* Enables per field numeric vector support.
@@ -189,7 +191,7 @@ public abstract class PerFieldKnnVectorsFormat extends KnnVectorsFormat {
}
/** VectorReader that can wrap multiple delegate readers, selected by field. */
- public static class FieldsReader extends KnnVectorsReader {
+ public static class FieldsReader extends KnnVectorsReader implements HnswGraphProvider {
private final IntObjectHashMap<KnnVectorsReader> fields = new IntObjectHashMap<>();
private final FieldInfos fieldInfos;
@@ -322,6 +324,17 @@ public abstract class PerFieldKnnVectorsFormat extends KnnVectorsFormat {
reader.search(field, target, knnCollector, acceptDocs);
}
+ @Override
+ public HnswGraph getGraph(String field) throws IOException {
+ final FieldInfo info = fieldInfos.fieldInfo(field);
+ KnnVectorsReader knnVectorsReader = fields.get(info.number);
+ if (knnVectorsReader instanceof HnswGraphProvider) {
+ return ((HnswGraphProvider) knnVectorsReader).getGraph(field);
+ } else {
+ return null;
+ }
+ }
+
@Override
public void close() throws IOException {
List<KnnVectorsReader> readers = new ArrayList<>(fields.size());
diff --git a/lucene/core/src/java/org/apache/lucene/index/IndexSorter.java b/lucene/core/src/java/org/apache/lucene/index/IndexSorter.java
index 6db379b9b22..9fa2484af39 100644
--- a/lucene/core/src/java/org/apache/lucene/index/IndexSorter.java
+++ b/lucene/core/src/java/org/apache/lucene/index/IndexSorter.java
@@ -32,11 +32,16 @@ import org.apache.lucene.util.packed.PackedInts;
/**
* Handles how documents should be sorted in an index, both within a segment and between segments.
*
- * <p>Implementers must provide the following methods: {@link #getDocComparator(LeafReader,int)} -
- * an object that determines how documents within a segment are to be sorted {@link
- * #getComparableProviders(List)} - an array of objects that return a sortable long value per
- * document and segment {@link #getProviderName()} - the SPI-registered name of a {@link
- * SortFieldProvider} to serialize the sort
+ * <p>Implementers must provide the following methods:
+ *
+ * <ul>
+ * <li>{@link #getDocComparator(LeafReader,int)} - an object that determines how documents within
+ * a segment are to be sorted
+ * <li>{@link #getComparableProviders(List)} - an array of objects that return a sortable long
+ * value per document and segment
+ * <li>{@link #getProviderName()} - the SPI-registered name of a {@link SortFieldProvider} to
+ * serialize the sort
+ * </ul>
*
* <p>The companion {@link SortFieldProvider} should be registered with SPI via {@code
* META-INF/services}
diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.java
index b4688d09730..7f44bcf96aa 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
@@ -60,11 +60,10 @@ public class ConcurrentHnswMerger extends IncrementalHnswGraphMerger {
} else {
initializedNodes = new FixedBitSet(maxOrd);
int[] oldToNewOrdinalMap = getNewOrdMapping(mergedVectorValues, initializedNodes);
- graph =
- InitializedHnswGraphBuilder.initGraph(M, initializerGraph, oldToNewOrdinalMap, maxOrd);
+ graph = InitializedHnswGraphBuilder.initGraph(initializerGraph, oldToNewOrdinalMap, maxOrd);
}
}
return new HnswConcurrentMergeBuilder(
- taskExecutor, numWorker, scorerSupplier, M, beamWidth, graph, initializedNodes);
+ taskExecutor, numWorker, scorerSupplier, beamWidth, graph, initializedNodes);
}
}
diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswConcurrentMergeBuilder.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswConcurrentMergeBuilder.java
index c23f56bcdc6..d2e81addc5d 100644
--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswConcurrentMergeBuilder.java
+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswConcurrentMergeBuilder.java
@@ -49,7 +49,6 @@ public class HnswConcurrentMergeBuilder implements HnswBuilder {
TaskExecutor taskExecutor,
int numWorker,
RandomVectorScorerSupplier scorerSupplier,
- int M,
int beamWidth,
OnHeapHnswGraph hnsw,
BitSet initializedNodes)
@@ -62,7 +61,6 @@ public class HnswConcurrentMergeBuilder implements HnswBuilder {
workers[i] =
new ConcurrentMergeWorker(
scorerSupplier.copy(),
- M,
beamWidth,
HnswGraphBuilder.randSeed,
hnsw,
@@ -149,7 +147,6 @@ public class HnswConcurrentMergeBuilder implements HnswBuilder {
private ConcurrentMergeWorker(
RandomVectorScorerSupplier scorerSupplier,
- int M,
int beamWidth,
long seed,
OnHeapHnswGraph hnsw,
@@ -159,7 +156,6 @@ public class HnswConcurrentMergeBuilder implements HnswBuilder {
throws IOException {
super(
scorerSupplier,
- M,
beamWidth,
seed,
hnsw,
diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraph.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraph.java
index 0c38c4e2ff7..9326ace61f7 100644
--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraph.java
+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraph.java
@@ -84,6 +84,9 @@ public abstract class HnswGraph {
/** Returns the number of levels of the graph */
public abstract int numLevels() throws IOException;
+ /** returns M, the maximum number of connections for a node. */
+ public abstract int maxConn() throws IOException;
+
/** Returns graph's entry point on the top level * */
public abstract int entryNode() throws IOException;
@@ -118,6 +121,11 @@ public abstract class HnswGraph {
return 0;
}
+ @Override
+ public int maxConn() {
+ return 0;
+ }
+
@Override
public int entryNode() {
return 0;
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.java
index 57e7e43d3d7..d3cef0bc6d1 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
@@ -100,19 +100,14 @@ public class HnswGraphBuilder implements HnswBuilder {
protected HnswGraphBuilder(
RandomVectorScorerSupplier scorerSupplier, int M, int beamWidth, long seed, int graphSize)
throws IOException {
- this(scorerSupplier, M, beamWidth, seed, new OnHeapHnswGraph(M, graphSize));
+ this(scorerSupplier, beamWidth, seed, new OnHeapHnswGraph(M, graphSize));
}
protected HnswGraphBuilder(
- RandomVectorScorerSupplier scorerSupplier,
- int M,
- int beamWidth,
- long seed,
- OnHeapHnswGraph hnsw)
+ RandomVectorScorerSupplier scorerSupplier, int beamWidth, long seed, OnHeapHnswGraph hnsw)
throws IOException {
this(
scorerSupplier,
- M,
beamWidth,
seed,
hnsw,
@@ -125,8 +120,6 @@ public class HnswGraphBuilder implements HnswBuilder {
* ordinals, using the given hyperparameter settings, and returns the resulting graph.
*
* @param scorerSupplier a supplier to create vector scorer from ordinals.
- * @param M – graph fanout parameter used to calculate the maximum number of connections a node
- * can have – M on upper layers, and M * 2 on the lowest level.
* @param beamWidth the size of the beam search to use when finding nearest neighbors.
* @param seed the seed for a random number generator used during graph construction. Provide this
* to ensure repeatable construction.
@@ -134,20 +127,19 @@ public class HnswGraphBuilder implements HnswBuilder {
*/
protected HnswGraphBuilder(
RandomVectorScorerSupplier scorerSupplier,
- int M,
int beamWidth,
long seed,
OnHeapHnswGraph hnsw,
HnswLock hnswLock,
HnswGraphSearcher graphSearcher)
throws IOException {
- if (M <= 0) {
+ if (hnsw.maxConn() <= 0) {
throw new IllegalArgumentException("M (max connections) must be positive");
}
if (beamWidth <= 0) {
throw new IllegalArgumentException("beamWidth must be positive");
}
- this.M = M;
+ this.M = hnsw.maxConn();
this.scorerSupplier =
Objects.requireNonNull(scorerSupplier, "scorer supplier must not be null");
// normalization factor for level generation; currently not configurable
diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswUtil.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswUtil.java
index 7028a81808d..d0d398be2a7 100644
--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswUtil.java
+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswUtil.java
@@ -23,6 +23,7 @@ import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.List;
+import org.apache.lucene.codecs.KnnVectorsReader;
import org.apache.lucene.codecs.hnsw.HnswGraphProvider;
import org.apache.lucene.codecs.perfield.PerFieldKnnVectorsFormat;
import org.apache.lucene.index.CodecReader;
@@ -233,13 +234,16 @@ public class HnswUtil {
public static boolean graphIsRooted(IndexReader reader, String vectorField) throws IOException {
for (LeafReaderContext ctx : reader.leaves()) {
CodecReader codecReader = (CodecReader) FilterLeafReader.unwrap(ctx.reader());
- HnswGraph graph =
- ((HnswGraphProvider)
- ((PerFieldKnnVectorsFormat.FieldsReader) codecReader.getVectorReader())
- .getFieldReader(vectorField))
- .getGraph(vectorField);
- if (isRooted(graph) == false) {
- return false;
+ KnnVectorsReader vectorsReader =
+ ((PerFieldKnnVectorsFormat.FieldsReader) codecReader.getVectorReader())
+ .getFieldReader(vectorField);
+ if (vectorsReader instanceof HnswGraphProvider) {
+ HnswGraph graph = ((HnswGraphProvider) vectorsReader).getGraph(vectorField);
+ if (isRooted(graph) == false) {
+ return false;
+ }
+ } else {
+ throw new IllegalArgumentException("not a graph: " + vectorsReader);
}
}
return true;
diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.java
index c480d53360c..bcdb0cab04a 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
@@ -21,7 +21,6 @@ import static org.apache.lucene.search.DocIdSetIterator.NO_MORE_DOCS;
import java.io.IOException;
import org.apache.lucene.codecs.KnnVectorsReader;
import org.apache.lucene.codecs.hnsw.HnswGraphProvider;
-import org.apache.lucene.codecs.perfield.PerFieldKnnVectorsFormat;
import org.apache.lucene.index.ByteVectorValues;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.FloatVectorValues;
@@ -63,33 +62,30 @@ 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/PerFieldKnnVectorReader 3. Has the most docs of any
- * previous reader that met the above criteria
+ * deleted docs 2. Is a HnswGraphProvider 3. Has the most docs of any previous reader that met the
+ * above criteria
*/
@Override
public IncrementalHnswGraphMerger addReader(
KnnVectorsReader reader, MergeState.DocMap docMap, Bits liveDocs) throws IOException {
- KnnVectorsReader currKnnVectorsReader = reader;
- if (reader instanceof PerFieldKnnVectorsFormat.FieldsReader candidateReader) {
- currKnnVectorsReader = candidateReader.getFieldReader(fieldInfo.name);
+ if (hasDeletes(liveDocs) || !(reader instanceof HnswGraphProvider)) {
+ return this;
}
-
- if (!(currKnnVectorsReader instanceof HnswGraphProvider) || !noDeletes(liveDocs)) {
+ HnswGraph graph = ((HnswGraphProvider) reader).getGraph(fieldInfo.name);
+ if (graph == null || graph.size() == 0) {
return this;
}
-
int candidateVectorCount = 0;
switch (fieldInfo.getVectorEncoding()) {
case BYTE -> {
- ByteVectorValues byteVectorValues =
- currKnnVectorsReader.getByteVectorValues(fieldInfo.name);
+ ByteVectorValues byteVectorValues = reader.getByteVectorValues(fieldInfo.name);
if (byteVectorValues == null) {
return this;
}
candidateVectorCount = byteVectorValues.size();
}
case FLOAT32 -> {
- FloatVectorValues vectorValues = currKnnVectorsReader.getFloatVectorValues(fieldInfo.name);
+ FloatVectorValues vectorValues = reader.getFloatVectorValues(fieldInfo.name);
if (vectorValues == null) {
return this;
}
@@ -97,7 +93,7 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {
}
}
if (candidateVectorCount > initGraphSize) {
- initReader = currKnnVectorsReader;
+ initReader = reader;
initDocMap = docMap;
initGraphSize = candidateVectorCount;
}
@@ -130,7 +126,6 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {
int[] oldToNewOrdinalMap = getNewOrdMapping(mergedVectorValues, initializedNodes);
return InitializedHnswGraphBuilder.fromGraph(
scorerSupplier,
- M,
beamWidth,
HnswGraphBuilder.randSeed,
initializerGraph,
@@ -194,16 +189,16 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {
return oldToNewOrdinalMap;
}
- private static boolean noDeletes(Bits liveDocs) {
+ private static boolean hasDeletes(Bits liveDocs) {
if (liveDocs == null) {
- return true;
+ return false;
}
for (int i = 0; i < liveDocs.length(); i++) {
if (!liveDocs.get(i)) {
- return false;
+ return true;
}
}
- return true;
+ return false;
}
}
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.java
index 179d243233d..7dff036ddde 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
@@ -34,7 +34,6 @@ 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 M the number of connections to keep per node
* @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
@@ -47,7 +46,6 @@ public final class InitializedHnswGraphBuilder extends HnswGraphBuilder {
*/
public static InitializedHnswGraphBuilder fromGraph(
RandomVectorScorerSupplier scorerSupplier,
- int M,
int beamWidth,
long seed,
HnswGraph initializerGraph,
@@ -57,17 +55,15 @@ public final class InitializedHnswGraphBuilder extends HnswGraphBuilder {
throws IOException {
return new InitializedHnswGraphBuilder(
scorerSupplier,
- M,
beamWidth,
seed,
- initGraph(M, initializerGraph, newOrdMap, totalNumberOfVectors),
+ initGraph(initializerGraph, newOrdMap, totalNumberOfVectors),
initializedNodes);
}
public static OnHeapHnswGraph initGraph(
- int M, HnswGraph initializerGraph, int[] newOrdMap, int totalNumberOfVectors)
- throws IOException {
- OnHeapHnswGraph hnsw = new OnHeapHnswGraph(M, totalNumberOfVectors);
+ 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.NodesIterator it = initializerGraph.getNodesOnLevel(level);
while (it.hasNext()) {
@@ -93,13 +89,12 @@ public final class InitializedHnswGraphBuilder extends HnswGraphBuilder {
public InitializedHnswGraphBuilder(
RandomVectorScorerSupplier scorerSupplier,
- int M,
int beamWidth,
long seed,
OnHeapHnswGraph initializedGraph,
BitSet initializedNodes)
throws IOException {
- super(scorerSupplier, M, beamWidth, seed, initializedGraph);
+ super(scorerSupplier, beamWidth, seed, initializedGraph);
this.initializedNodes = 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.java
index a79bcd17d91..61f30152787 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
@@ -92,7 +92,14 @@ public final class OnHeapHnswGraph extends HnswGraph implements Accountable {
public NeighborArray getNeighbors(int level, int node) {
assert node < graph.length;
assert level < graph[node].length
- : "level=" + level + ", node has only " + graph[node].length + " levels";
+ : "level="
+ + level
+ + ", node "
+ + node
+ + " has only "
+ + graph[node].length
+ + " levels for graph "
+ + this;
assert graph[node][level] != null : "node=" + node + ", level=" + level;
return graph[node][level];
}
@@ -181,6 +188,11 @@ public final class OnHeapHnswGraph extends HnswGraph implements Accountable {
return entryNode.get().level + 1;
}
+ @Override
+ public int maxConn() {
+ return nsize - 1;
+ }
+
/**
* Returns the graph's current entry node on the top level shown as ordinals of the nodes on 0th
* level
diff --git a/lucene/core/src/test/org/apache/lucene/index/TestSortingCodecReader.java b/lucene/core/src/test/org/apache/lucene/index/TestSortingCodecReader.java
index 9663d676255..8039d8b8f6f 100644
--- a/lucene/core/src/test/org/apache/lucene/index/TestSortingCodecReader.java
+++ b/lucene/core/src/test/org/apache/lucene/index/TestSortingCodecReader.java
@@ -26,6 +26,7 @@ import java.util.Collections;
import java.util.List;
import java.util.Locale;
import org.apache.lucene.codecs.TermVectorsReader;
+import org.apache.lucene.codecs.hnsw.HnswGraphProvider;
import org.apache.lucene.document.BinaryDocValuesField;
import org.apache.lucene.document.Document;
import org.apache.lucene.document.Field;
@@ -53,6 +54,7 @@ import org.apache.lucene.tests.index.RandomIndexWriter;
import org.apache.lucene.tests.util.LuceneTestCase;
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.IOUtils;
+import org.apache.lucene.util.hnsw.HnswGraph;
public class TestSortingCodecReader extends LuceneTestCase {
@@ -151,6 +153,8 @@ public class TestSortingCodecReader extends LuceneTestCase {
docIds.add(i);
}
Collections.shuffle(docIds, random());
+ // If true, index a vector for every doc
+ boolean denseVectors = random().nextBoolean();
try (RandomIndexWriter iw = new RandomIndexWriter(random(), dir)) {
for (int i = 0; i < numDocs; i++) {
int docId = docIds.get(i);
@@ -168,7 +172,9 @@ public class TestSortingCodecReader extends LuceneTestCase {
doc.add(new BinaryDocValuesField("binary_dv", new BytesRef(Integer.toString(docId))));
doc.add(
new SortedSetDocValuesField("sorted_set_dv", new BytesRef(Integer.toString(docId))));
- doc.add(new KnnFloatVectorField("vector", new float[] {(float) docId}));
+ if (denseVectors || docId % 2 == 0) {
+ doc.add(new KnnFloatVectorField("vector", new float[] {(float) docId}));
+ }
doc.add(new NumericDocValuesField("foo", random().nextInt(20)));
FieldType ft = new FieldType(StringField.TYPE_NOT_STORED);
@@ -239,6 +245,8 @@ public class TestSortingCodecReader extends LuceneTestCase {
SortedSetDocValues sorted_set_dv = leaf.getSortedSetDocValues("sorted_set_dv");
SortedDocValues binary_sorted_dv = leaf.getSortedDocValues("binary_sorted_dv");
FloatVectorValues vectorValues = leaf.getFloatVectorValues("vector");
+ HnswGraph graph =
+ ((HnswGraphProvider) ((CodecReader) leaf).getVectorReader()).getGraph("vector");
NumericDocValues ids = leaf.getNumericDocValues("id");
long prevValue = -1;
boolean usingAltIds = false;
@@ -264,7 +272,12 @@ public class TestSortingCodecReader extends LuceneTestCase {
assertTrue(sorted_numeric_dv.advanceExact(idNext));
assertTrue(sorted_set_dv.advanceExact(idNext));
assertTrue(binary_sorted_dv.advanceExact(idNext));
- assertEquals(idNext, valuesIterator.advance(idNext));
+ if (denseVectors || prevValue % 2 == 0) {
+ assertEquals(idNext, valuesIterator.advance(idNext));
+ graph.seek(0, valuesIterator.index());
+ assertNotEquals(DocIdSetIterator.NO_MORE_DOCS, graph.nextNeighbor());
+ }
+
assertEquals(new BytesRef(ids.longValue() + ""), binary_dv.binaryValue());
assertEquals(
new BytesRef(ids.longValue() + ""),
@@ -276,9 +289,11 @@ public class TestSortingCodecReader extends LuceneTestCase {
assertEquals(1, sorted_numeric_dv.docValueCount());
assertEquals(ids.longValue(), sorted_numeric_dv.nextValue());
- float[] vectorValue = vectorValues.vectorValue(valuesIterator.index());
- assertEquals(1, vectorValue.length);
- assertEquals((float) ids.longValue(), vectorValue[0], 0.001f);
+ if (denseVectors || prevValue % 2 == 0) {
+ float[] vectorValue = vectorValues.vectorValue(valuesIterator.index());
+ assertEquals(1, vectorValue.length);
+ assertEquals((float) ids.longValue(), vectorValue[0], 0.001f);
+ }
Fields termVectors = leaf.termVectors().get(idNext);
assertTrue(
diff --git a/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java b/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java
index 1da8c8169a9..c6da6d30faf 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
@@ -550,12 +550,11 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {
// another graph to do the assertion
OnHeapHnswGraph graphAfterInit =
InitializedHnswGraphBuilder.initGraph(
- 10, initializerGraph, initializerOrdMap, initializerGraph.size());
+ initializerGraph, initializerOrdMap, initializerGraph.size());
HnswGraphBuilder finalBuilder =
InitializedHnswGraphBuilder.fromGraph(
finalscorerSupplier,
- 10,
30,
seed,
initializerGraph,
@@ -593,7 +592,6 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {
HnswGraphBuilder finalBuilder =
InitializedHnswGraphBuilder.fromGraph(
finalscorerSupplier,
- 10,
30,
seed,
initializerGraph,
@@ -987,7 +985,7 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {
HnswGraphBuilder.randSeed = random().nextLong();
HnswConcurrentMergeBuilder builder =
new HnswConcurrentMergeBuilder(
- taskExecutor, 4, scorerSupplier, 10, 30, new OnHeapHnswGraph(10, size), null);
+ taskExecutor, 4, scorerSupplier, 30, new OnHeapHnswGraph(10, size), null);
builder.setBatchSize(100);
builder.build(size);
exec.shutdownNow();
@@ -1337,6 +1335,11 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {
return delegate.entryNode();
}
+ @Override
+ public int maxConn() throws IOException {
+ return delegate.maxConn();
+ }
+
@Override
public NodesIterator getNodesOnLevel(int level) throws IOException {
return delegate.getNodesOnLevel(level);
diff --git a/lucene/core/src/test/org/apache/lucene/util/hnsw/TestHnswUtil.java b/lucene/core/src/test/org/apache/lucene/util/hnsw/TestHnswUtil.java
index 316afff5ee2..7ea05150e14 100644
--- a/lucene/core/src/test/org/apache/lucene/util/hnsw/TestHnswUtil.java
+++ b/lucene/core/src/test/org/apache/lucene/util/hnsw/TestHnswUtil.java
@@ -250,6 +250,11 @@ public class TestHnswUtil extends LuceneTestCase {
return 0;
}
+ @Override
+ public int maxConn() {
+ return 0;
+ }
+
@Override
public String toString() {
StringBuilder buf = new StringBuilder();
diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.java
new file mode 100644
index 00000000000..3f7442a2526
--- /dev/null
+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.java
@@ -0,0 +1,78 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+package org.apache.lucene.misc.index;
+
+/** Base class for docid-reorderers implemented using binary partitioning (BP). */
+public abstract class AbstractBPReorderer implements IndexReorderer {
+ /**
+ * Minimum size of partitions. The algorithm will stop recursing when reaching partitions below
+ * this number of documents: 32.
+ */
+ public static final int DEFAULT_MIN_PARTITION_SIZE = 32;
+
+ /**
+ * Default maximum number of iterations per recursion level: 20. Higher numbers of iterations
+ * typically don't help significantly.
+ */
+ public static final int DEFAULT_MAX_ITERS = 20;
+
+ protected int minPartitionSize = DEFAULT_MIN_PARTITION_SIZE;
+ protected int maxIters = DEFAULT_MAX_ITERS;
+ protected double ramBudgetMB;
+
+ public AbstractBPReorderer() {
+ // 10% of the available heap size by default
+ setRAMBudgetMB(Runtime.getRuntime().totalMemory() / 1024d / 1024d / 10d);
+ }
+
+ /** Set the minimum partition size, when the algorithm stops recursing, 32 by default. */
+ public void setMinPartitionSize(int minPartitionSize) {
+ if (minPartitionSize < 1) {
+ throw new IllegalArgumentException(
+ "minPartitionSize must be at least 1, got " + minPartitionSize);
+ }
+ this.minPartitionSize = minPartitionSize;
+ }
+
+ /**
+ * Set the maximum number of iterations on each recursion level, 20 by default. Experiments
+ * suggests that values above 20 do not help much. However, values below 20 can be used to trade
+ * effectiveness for faster reordering.
+ */
+ public void setMaxIters(int maxIters) {
+ if (maxIters < 1) {
+ throw new IllegalArgumentException("maxIters must be at least 1, got " + maxIters);
+ }
+ this.maxIters = maxIters;
+ }
+
+ /**
+ * Set the amount of RAM that graph partitioning is allowed to use. More RAM allows running
+ * faster. If not enough RAM is provided, a {@link NotEnoughRAMException} will be thrown. This is
+ * 10% of the total heap size by default.
+ */
+ public void setRAMBudgetMB(double ramBudgetMB) {
+ this.ramBudgetMB = ramBudgetMB;
+ }
+
+ /** Exception that is thrown when not enough RAM is available. */
+ public static class NotEnoughRAMException extends RuntimeException {
+ NotEnoughRAMException(String message) {
+ super(message);
+ }
+ }
+}
diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/BPIndexReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/BPIndexReorderer.java
index f51321fe842..6507ff02500 100644
--- a/lucene/misc/src/java/org/apache/lucene/misc/index/BPIndexReorderer.java
+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/BPIndexReorderer.java
@@ -90,14 +90,7 @@ import org.apache.lucene.util.packed.PackedInts;
*
* <p>Note: This is a slow operation that consumes O(maxDoc + numTerms * numThreads) memory.
*/
-public final class BPIndexReorderer {
-
- /** Exception that is thrown when not enough RAM is available. */
- public static class NotEnoughRAMException extends RuntimeException {
- private NotEnoughRAMException(String message) {
- super(message);
- }
- }
+public final class BPIndexReorderer extends AbstractBPReorderer {
/** Block size for terms in the forward index */
private static final int TERM_IDS_BLOCK_SIZE = 17;
@@ -108,33 +101,14 @@ public final class BPIndexReorderer {
/** Minimum required document frequency for terms to be considered: 4,096. */
public static final int DEFAULT_MIN_DOC_FREQ = 4096;
- /**
- * Minimum size of partitions. The algorithm will stop recursing when reaching partitions below
- * this number of documents: 32.
- */
- public static final int DEFAULT_MIN_PARTITION_SIZE = 32;
-
- /**
- * Default maximum number of iterations per recursion level: 20. Higher numbers of iterations
- * typically don't help significantly.
- */
- public static final int DEFAULT_MAX_ITERS = 20;
-
private int minDocFreq;
private float maxDocFreq;
- private int minPartitionSize;
- private int maxIters;
- private double ramBudgetMB;
private Set<String> fields;
/** Constructor. */
public BPIndexReorderer() {
setMinDocFreq(DEFAULT_MIN_DOC_FREQ);
setMaxDocFreq(1f);
- setMinPartitionSize(DEFAULT_MIN_PARTITION_SIZE);
- setMaxIters(DEFAULT_MAX_ITERS);
- // 10% of the available heap size by default
- setRAMBudgetMB(Runtime.getRuntime().totalMemory() / 1024d / 1024d / 10d);
setFields(null);
}
@@ -159,36 +133,6 @@ public final class BPIndexReorderer {
this.maxDocFreq = maxDocFreq;
}
- /** Set the minimum partition size, when the algorithm stops recursing, 32 by default. */
- public void setMinPartitionSize(int minPartitionSize) {
- if (minPartitionSize < 1) {
- throw new IllegalArgumentException(
- "minPartitionSize must be at least 1, got " + minPartitionSize);
- }
- this.minPartitionSize = minPartitionSize;
- }
-
- /**
- * Set the maximum number of iterations on each recursion level, 20 by default. Experiments
- * suggests that values above 20 do not help much. However, values below 20 can be used to trade
- * effectiveness for faster reordering.
- */
- public void setMaxIters(int maxIters) {
- if (maxIters < 1) {
- throw new IllegalArgumentException("maxIters must be at least 1, got " + maxIters);
- }
- this.maxIters = maxIters;
- }
-
- /**
- * Set the amount of RAM that graph partitioning is allowed to use. More RAM allows running
- * faster. If not enough RAM is provided, a {@link NotEnoughRAMException} will be thrown. This is
- * 10% of the total heap size by default.
- */
- public void setRAMBudgetMB(double ramBudgetMB) {
- this.ramBudgetMB = ramBudgetMB;
- }
-
/**
* Sets the fields to use to perform partitioning. A {@code null} value indicates that all indexed
* fields should be used.
@@ -830,6 +774,7 @@ public final class BPIndexReorderer {
* enable integration into {@link BPReorderingMergePolicy}, {@link #reorder(CodecReader,
* Directory, Executor)} should be preferred in general.
*/
+ @Override
public Sorter.DocMap computeDocMap(CodecReader reader, Directory tempDir, Executor executor)
throws IOException {
if (docRAMRequirements(reader.maxDoc()) >= ramBudgetMB * 1024 * 1024) {
diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/BPReorderingMergePolicy.java b/lucene/misc/src/java/org/apache/lucene/misc/index/BPReorderingMergePolicy.java
index 5cd363192fa..70fcea733eb 100644
--- a/lucene/misc/src/java/org/apache/lucene/misc/index/BPReorderingMergePolicy.java
+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/BPReorderingMergePolicy.java
@@ -27,7 +27,7 @@ import org.apache.lucene.index.MergeTrigger;
import org.apache.lucene.index.SegmentCommitInfo;
import org.apache.lucene.index.SegmentInfos;
import org.apache.lucene.index.Sorter;
-import org.apache.lucene.misc.index.BPIndexReorderer.NotEnoughRAMException;
+import org.apache.lucene.misc.index.AbstractBPReorderer.NotEnoughRAMException;
import org.apache.lucene.store.Directory;
import org.apache.lucene.util.SetOnce;
@@ -42,7 +42,7 @@ public final class BPReorderingMergePolicy extends FilterMergePolicy {
/** Whether a segment has been reordered. */
static final String REORDERED = "bp.reordered";
- private final BPIndexReorderer reorderer;
+ private final IndexReorderer reorderer;
private int minNaturalMergeNumDocs = 1;
private float minNaturalMergeRatioFromBiggestSegment = 0f;
@@ -59,7 +59,7 @@ public final class BPReorderingMergePolicy extends FilterMergePolicy {
* @param in the merge policy to use to compute merges
* @param reorderer the {@link BPIndexReorderer} to use to renumber doc IDs
*/
- public BPReorderingMergePolicy(MergePolicy in, BPIndexReorderer reorderer) {
+ public BPReorderingMergePolicy(MergePolicy in, IndexReorderer reorderer) {
super(in);
this.reorderer = reorderer;
}
diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/BpVectorReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/BpVectorReorderer.java
new file mode 100644
index 00000000000..7facf48580c
--- /dev/null
+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/BpVectorReorderer.java
@@ -0,0 +1,792 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+package org.apache.lucene.misc.index;
+
+import static org.apache.lucene.search.DocIdSetIterator.NO_MORE_DOCS;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.file.Path;
+import java.util.Arrays;
+import java.util.concurrent.Executor;
+import java.util.concurrent.ForkJoinPool;
+import java.util.concurrent.ForkJoinWorkerThread;
+import java.util.concurrent.RecursiveAction;
+import org.apache.lucene.index.CodecReader;
+import org.apache.lucene.index.DirectoryReader;
+import org.apache.lucene.index.FieldInfo;
+import org.apache.lucene.index.FloatVectorValues;
+import org.apache.lucene.index.IndexReader;
+import org.apache.lucene.index.IndexWriter;
+import org.apache.lucene.index.IndexWriterConfig;
+import org.apache.lucene.index.LeafReaderContext;
+import org.apache.lucene.index.Sorter;
+import org.apache.lucene.index.SortingCodecReader;
+import org.apache.lucene.index.VectorEncoding;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.search.DocIdSetIterator;
+import org.apache.lucene.search.TaskExecutor;
+import org.apache.lucene.store.Directory;
+import org.apache.lucene.store.FSDirectory;
+import org.apache.lucene.util.CloseableThreadLocal;
+import org.apache.lucene.util.IntroSelector;
+import org.apache.lucene.util.IntsRef;
+import org.apache.lucene.util.VectorUtil;
+
+/**
+ * Implementation of "recursive graph bisection", also called "bipartite graph partitioning" and
+ * often abbreviated BP, an approach to doc ID assignment that aims at reducing the sum of the log
+ * gap between consecutive neighbor node ids. See {@link BPIndexReorderer}.
+ */
+public class BpVectorReorderer extends AbstractBPReorderer {
+
+ /*
+ * Note on using centroids (mean of vectors in a partition) to maximize scores of pairs of vectors within each partition:
+ * The function used to compare the vectors must have higher values for vectors
+ * that are more similar to each other, and must preserve inequalities over sums of vectors.
+ *
+ * <p>This property enables us to use the centroid of a collection of vectors to represent the
+ * collection. For Euclidean and inner product score functions, the centroid is the point that
+ * minimizes the sum of distances from all the points (thus maximizing the score).
+ *
+ * <p>sum((c0 - v)^2) = n * c0^2 - 2 * c0 * sum(v) + sum(v^2) taking derivative w.r.t. c0 and
+ * setting to 0 we get sum(v) = n * c0; i.e. c0 (the centroid) is the place that minimizes the sum
+ * of (l2) distances from the vectors (thus maximizing the euclidean score function).
+ *
+ * <p>to maximize dot-product over unit vectors, note that: sum(dot(c0, v)) = dot(c0, sum(v))
+ * which is maximized, again, when c0 = sum(v) / n. For max inner product score, vectors may not
+ * be unit vectors. In this case there is no maximum, but since all colinear vectors of whatever
+ * scale will generate the same partition for these angular scores, we are free to choose any
+ * scale and ignore the normalization factor.
+ */
+
+ /** Minimum problem size that will result in tasks being split. */
+ private static final int FORK_THRESHOLD = 8192;
+
+ /**
+ * Limits how many incremental updates we do before initiating a full recalculation. Some wasted
+ * work is done when this is exceeded, but more is saved when it is not. Setting this to zero
+ * prevents any incremental updates from being done, instead the centroids are fully recalculated
+ * for each iteration. We're not able to make it very big since too much numerical error
+ * accumulates, which seems to be around 50, thus resulting in suboptimal reordering. It's not
+ * clear how helpful this is though; measurements vary, so it is currently disabled (= 0).
+ */
+ private static final int MAX_CENTROID_UPDATES = 0;
+
+ private final String partitionField;
+
+ /** Constructor. */
+ public BpVectorReorderer(String partitionField) {
+ setMinPartitionSize(DEFAULT_MIN_PARTITION_SIZE);
+ setMaxIters(DEFAULT_MAX_ITERS);
+ // 10% of the available heap size by default
+ setRAMBudgetMB(Runtime.getRuntime().totalMemory() / 1024d / 1024d / 10d);
+ this.partitionField = partitionField;
+ }
+
+ private static class PerThreadState {
+
+ final FloatVectorValues vectors;
+ final float[] leftCentroid;
+ final float[] rightCentroid;
+ final float[] scratch;
+
+ PerThreadState(FloatVectorValues vectors) {
+ try {
+ this.vectors = vectors.copy();
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ leftCentroid = new float[vectors.dimension()];
+ rightCentroid = new float[leftCentroid.length];
+ scratch = new float[leftCentroid.length];
+ }
+ }
+
+ private static class DocMap extends Sorter.DocMap {
+
+ private final int[] newToOld;
+ private final int[] oldToNew;
+
+ public DocMap(int[] newToOld) {
+ this.newToOld = newToOld;
+ oldToNew = new int[newToOld.length];
+ for (int i = 0; i < newToOld.length; ++i) {
+ oldToNew[newToOld[i]] = i;
+ }
+ }
+
+ @Override
+ public int size() {
+ return newToOld.length;
+ }
+
+ @Override
+ public int oldToNew(int docID) {
+ return oldToNew[docID];
+ }
+
+ @Override
+ public int newToOld(int docID) {
+ return newToOld[docID];
+ }
+ }
+
+ private abstract class BaseRecursiveAction extends RecursiveAction {
+
+ protected final TaskExecutor executor;
+ protected final int depth;
+
+ BaseRecursiveAction(TaskExecutor executor, int depth) {
+ this.executor = executor;
+ this.depth = depth;
+ }
+
+ protected final boolean shouldFork(int problemSize, int totalProblemSize) {
+ if (executor == null) {
+ return false;
+ }
+ if (getSurplusQueuedTaskCount() > 3) {
+ // Fork tasks if this worker doesn't have more queued work than other workers
+ // See javadocs of #getSurplusQueuedTaskCount for more details
+ return false;
+ }
+ if (problemSize == totalProblemSize) {
+ // Sometimes fork regardless of the problem size to make sure that unit tests also exercise
+ // forking
+ return true;
+ }
+ return problemSize > FORK_THRESHOLD;
+ }
+ }
+
+ private class ReorderTask extends BaseRecursiveAction {
+
+ private final VectorSimilarityFunction vectorScore;
+ // the ids assigned to this task, a sub-range of all the ids
+ private final IntsRef ids;
+ // the biases for the ids - a number < 0 when the doc goes left and > 0 for right
+ private final float[] biases;
+ private final CloseableThreadLocal<PerThreadState> threadLocal;
+
+ ReorderTask(
+ IntsRef ids,
+ float[] biases,
+ CloseableThreadLocal<PerThreadState> threadLocal,
+ TaskExecutor executor,
+ int depth,
+ VectorSimilarityFunction vectorScore) {
+ super(executor, depth);
+ this.ids = ids;
+ this.biases = biases;
+ this.threadLocal = threadLocal;
+ this.vectorScore = vectorScore;
+ }
+
+ @Override
+ protected void compute() {
+ if (depth > 0) {
+ Arrays.sort(ids.ints, ids.offset, ids.offset + ids.length);
+ } else {
+ assert sorted(ids);
+ }
+
+ int halfLength = ids.length >>> 1;
+ if (halfLength < minPartitionSize) {
+ return;
+ }
+
+ // split the ids in half
+ IntsRef left = new IntsRef(ids.ints, ids.offset, halfLength);
+ IntsRef right = new IntsRef(ids.ints, ids.offset + halfLength, ids.length - halfLength);
+
+ PerThreadState state = threadLocal.get();
+ FloatVectorValues vectors = state.vectors;
+ float[] leftCentroid = state.leftCentroid;
+ float[] rightCentroid = state.rightCentroid;
+ float[] scratch = state.scratch;
+
+ try {
+ computeCentroid(left, vectors, leftCentroid, vectorScore);
+ computeCentroid(right, vectors, rightCentroid, vectorScore);
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+
+ for (int iter = 0; iter < maxIters; ++iter) {
+ int moved;
+ try {
+ moved = shuffle(vectors, ids, right.offset, leftCentroid, rightCentroid, scratch, biases);
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ if (moved == 0) {
+ break;
+ }
+ if (moved > MAX_CENTROID_UPDATES) {
+ // if we swapped too many times we don't use the relative calculation because it
+ // introduces too much error
+ try {
+ computeCentroid(left, vectors, leftCentroid, vectorScore);
+ computeCentroid(right, vectors, rightCentroid, vectorScore);
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ }
+ }
+
+ // It is fine for all tasks to share the same docs / biases array since they all work on
+ // different slices of the array at a given point in time.
+ ReorderTask leftTask =
+ new ReorderTask(left, biases, threadLocal, executor, depth + 1, vectorScore);
+ ReorderTask rightTask =
+ new ReorderTask(right, biases, threadLocal, executor, depth + 1, vectorScore);
+
+ if (shouldFork(ids.length, ids.ints.length)) {
+ invokeAll(leftTask, rightTask);
+ } else {
+ leftTask.compute();
+ rightTask.compute();
+ }
+ }
+
+ static void computeCentroid(
+ IntsRef ids,
+ FloatVectorValues vectors,
+ float[] centroid,
+ VectorSimilarityFunction vectorSimilarity)
+ throws IOException {
+ Arrays.fill(centroid, 0);
+ for (int i = ids.offset; i < ids.offset + ids.length; i++) {
+ VectorUtil.add(centroid, vectors.vectorValue(ids.ints[i]));
+ }
+ switch (vectorSimilarity) {
+ case EUCLIDEAN, MAXIMUM_INNER_PRODUCT -> vectorScalarMul(1 / (float) ids.length, centroid);
+ case DOT_PRODUCT, COSINE ->
+ vectorScalarMul(
+ 1 / (float) Math.sqrt(VectorUtil.dotProduct(centroid, centroid)), centroid);
+ }
+ }
+
+ /** Shuffle IDs across both partitions so that each partition is closer to its centroid. */
+ private int shuffle(
+ FloatVectorValues vectors,
+ IntsRef ids,
+ int midPoint,
+ float[] leftCentroid,
+ float[] rightCentroid,
+ float[] scratch,
+ float[] biases)
+ throws IOException {
+
+ /* Computing biases requires a distance calculation for each vector (document) which can be
+ * costly, especially as the vector dimension increases, so we try to parallelize it. We also
+ * have the option of performing incremental updates based on the difference of the previous and
+ * the new centroid, which can be less costly, but introduces incremental numeric error, and
+ * needs tuning to be usable. It is disabled by default (see MAX_CENTROID_UPDATES).
+ */
+ new ComputeBiasTask(
+ ids.ints,
+ biases,
+ ids.offset,
+ ids.offset + ids.length,
+ leftCentroid,
+ rightCentroid,
+ threadLocal,
+ executor,
+ depth,
+ vectorScore)
+ .compute();
+
+ float scale =
+ VectorUtil.dotProduct(leftCentroid, leftCentroid)
+ + VectorUtil.dotProduct(rightCentroid, rightCentroid);
+ float maxLeftBias = Float.NEGATIVE_INFINITY;
+ for (int i = ids.offset; i < midPoint; ++i) {
+ maxLeftBias = Math.max(maxLeftBias, biases[i]);
+ }
+ float minRightBias = Float.POSITIVE_INFINITY;
+ for (int i = midPoint, end = ids.offset + ids.length; i < end; ++i) {
+ minRightBias = Math.min(minRightBias, biases[i]);
+ }
+ float gain = maxLeftBias - minRightBias;
+ /* This compares the gain of swapping the doc from the left side that is most attracted to the
+ * right and the doc from the right side that is most attracted to the left against the
+ * average vector length (/500) rather than zero. 500 is an arbitrary heuristic value
+ * determined empirically - basically we stop iterating once the centroids move less than
+ * 1/500 the sum of their lengths.
+ *
+ * TODO We could try incorporating simulated annealing by including the iteration number in the
+ * formula? eg { 1000 * gain <= scale * iter }.
+ */
+
+ // System.out.printf("at depth=%d, midPoint=%d, gain=%f\n", depth, midPoint, gain);
+ if (500 * gain <= scale) {
+ return 0;
+ }
+
+ class Selector extends IntroSelector {
+ int count = 0;
+ int pivotDoc;
+ float pivotBias;
+
+ @Override
+ public void setPivot(int i) {
+ pivotDoc = ids.ints[i];
+ pivotBias = biases[i];
+ }
+
+ @Override
+ public int comparePivot(int j) {
+ int cmp = Float.compare(pivotBias, biases[j]);
+ if (cmp == 0) {
+ // Tie break on the ID to preserve ID ordering as much as possible
+ cmp = pivotDoc - ids.ints[j];
+ }
+ return cmp;
+ }
+
+ @Override
+ public void swap(int i, int j) {
+ float tmpBias = biases[i];
+ biases[i] = biases[j];
+ biases[j] = tmpBias;
+
+ if (i < midPoint == j < midPoint) {
+ int tmpDoc = ids.ints[i];
+ ids.ints[i] = ids.ints[j];
+ ids.ints[j] = tmpDoc;
+ } else {
+ // If we're swapping across the left and right sides, we need to keep centroids
+ // up-to-date.
+ count++;
+ int from = Math.min(i, j);
+ int to = Math.max(i, j);
+ try {
+ swapIdsAndCentroids(
+ ids,
+ from,
+ to,
+ midPoint,
+ vectors,
+ leftCentroid,
+ rightCentroid,
+ scratch,
+ count,
+ vectorScore);
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ }
+ }
+ }
+
+ Selector selector = new Selector();
+ selector.select(ids.offset, ids.offset + ids.length, midPoint);
+ // System.out.printf("swapped %d / %d\n", selector.count, ids.length);
+ return selector.count;
+ }
+
+ private static boolean centroidValid(
+ float[] centroid, FloatVectorValues vectors, IntsRef ids, int count) throws IOException {
+ // recompute centroid to check the incremental calculation
+ float[] check = new float[centroid.length];
+ computeCentroid(ids, vectors, check, VectorSimilarityFunction.EUCLIDEAN);
+ for (int i = 0; i < check.length; ++i) {
+ float diff = Math.abs(check[i] - centroid[i]);
+ if (diff > 1e-4) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ private static void swapIdsAndCentroids(
+ IntsRef ids,
+ int from,
+ int to,
+ int midPoint,
+ FloatVectorValues vectors,
+ float[] leftCentroid,
+ float[] rightCentroid,
+ float[] scratch,
+ int count,
+ VectorSimilarityFunction vectorScore)
+ throws IOException {
+ assert from < to;
+
+ int[] idArr = ids.ints;
+ int fromId = idArr[from];
+ int toId = idArr[to];
+
+ // Now update the centroids, this makes things much faster than invalidating it and having to
+ // recompute on the next iteration. Should be faster than full recalculation if the number of
+ // swaps is reasonable.
+
+ // We want the net effect to be moving "from" left->right and "to" right->left
+
+ // (1) scratch = to - from
+ if (count <= MAX_CENTROID_UPDATES && vectorScore == VectorSimilarityFunction.EUCLIDEAN) {
+ int relativeMidpoint = midPoint - ids.offset;
+ vectorSubtract(vectors.vectorValue(toId), vectors.vectorValue(fromId), scratch);
+ // we must normalize to the proper scale by accounting for the number of points contributing
+ // to each centroid
+ // left += scratch / size(left)
+ vectorScalarMul(1 / (float) relativeMidpoint, scratch);
+ VectorUtil.add(leftCentroid, scratch);
+ // right -= scratch / size(right)
+ vectorScalarMul(-relativeMidpoint / (float) (ids.length - relativeMidpoint), scratch);
+ VectorUtil.add(rightCentroid, scratch);
+ }
+
+ idArr[from] = toId;
+ idArr[to] = fromId;
+
+ if (count <= MAX_CENTROID_UPDATES) {
+ assert centroidValid(
+ leftCentroid, vectors, new IntsRef(idArr, ids.offset, midPoint - ids.offset), count);
+ assert centroidValid(
+ rightCentroid,
+ vectors,
+ new IntsRef(ids.ints, midPoint, ids.length - midPoint + ids.offset),
+ count);
+ }
+ }
+ }
+
+ /**
+ * Adds the second argument to the first
+ *
+ * @param u the destination
+ * @param v the vector to add to the destination
+ */
+ static void vectorSubtract(float[] u, float[] v, float[] result) {
+ for (int i = 0; i < u.length; i++) {
+ result[i] = u[i] - v[i];
+ }
+ }
+
+ static void vectorScalarMul(float x, float[] v) {
+ for (int i = 0; i < v.length; i++) {
+ v[i] *= x;
+ }
+ }
+
+ private class ComputeBiasTask extends BaseRecursiveAction {
+
+ private final int[] ids;
+ private final float[] biases;
+ private final int start;
+ private final int end;
+ private final float[] leftCentroid;
+ private final float[] rightCentroid;
+ private final CloseableThreadLocal<PerThreadState> threadLocal;
+ private final VectorSimilarityFunction vectorScore;
+
+ ComputeBiasTask(
+ int[] ids,
+ float[] biases,
+ int start,
+ int end,
+ float[] leftCentroid,
+ float[] rightCentroid,
+ CloseableThreadLocal<PerThreadState> threadLocal,
+ TaskExecutor executor,
+ int depth,
+ VectorSimilarityFunction vectorScore) {
+ super(executor, depth);
+ this.ids = ids;
+ this.biases = biases;
+ this.start = start;
+ this.end = end;
+ this.leftCentroid = leftCentroid;
+ this.rightCentroid = rightCentroid;
+ this.threadLocal = threadLocal;
+ this.vectorScore = vectorScore;
+ }
+
+ @Override
+ protected void compute() {
+ final int problemSize = end - start;
+ if (problemSize > 1 && shouldFork(problemSize, ids.length)) {
+ final int mid = (start + end) >>> 1;
+ invokeAll(
+ new ComputeBiasTask(
+ ids,
+ biases,
+ start,
+ mid,
+ leftCentroid,
+ rightCentroid,
+ threadLocal,
+ executor,
+ depth,
+ vectorScore),
+ new ComputeBiasTask(
+ ids,
+ biases,
+ mid,
+ end,
+ leftCentroid,
+ rightCentroid,
+ threadLocal,
+ executor,
+ depth,
+ vectorScore));
+ } else {
+ FloatVectorValues vectors = threadLocal.get().vectors;
+ try {
+ for (int i = start; i < end; ++i) {
+ biases[i] = computeBias(vectors.vectorValue(ids[i]), leftCentroid, rightCentroid);
+ }
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ }
+ }
+
+ /**
+ * Compute a float that is negative when a vector is attracted to the left and positive
+ * otherwise.
+ */
+ private float computeBias(float[] vector, float[] leftCentroid, float[] rightCentroid) {
+ return switch (vectorScore) {
+ case EUCLIDEAN ->
+ VectorUtil.squareDistance(vector, leftCentroid)
+ - VectorUtil.squareDistance(vector, rightCentroid);
+ case MAXIMUM_INNER_PRODUCT, COSINE, DOT_PRODUCT ->
+ VectorUtil.dotProduct(vector, rightCentroid)
+ - VectorUtil.dotProduct(vector, leftCentroid);
+ default -> throw new IllegalStateException("unsupported vector score: " + vectorScore);
+ };
+ }
+ }
+
+ @Override
+ public Sorter.DocMap computeDocMap(CodecReader reader, Directory tempDir, Executor executor)
+ throws IOException {
+ TaskExecutor taskExecutor;
+ if (executor == null) {
+ taskExecutor = null;
+ } else {
+ taskExecutor = new TaskExecutor(executor);
+ }
+ VectorSimilarityFunction vectorScore = checkField(reader, partitionField);
+ if (vectorScore == null) {
+ return null;
+ }
+ FloatVectorValues floats = reader.getFloatVectorValues(partitionField);
+ Sorter.DocMap valueMap = computeValueMap(floats, vectorScore, taskExecutor);
+ return valueMapToDocMap(valueMap, floats, reader.maxDoc());
+ }
+
+ /** Expert: Compute the {@link DocMap} that holds the new vector ordinal numbering. */
+ Sorter.DocMap computeValueMap(
+ FloatVectorValues vectors, VectorSimilarityFunction vectorScore, TaskExecutor executor) {
+ if (docRAMRequirements(vectors.size()) >= ramBudgetMB * 1024 * 1024) {
+ throw new NotEnoughRAMException(
+ "At least "
+ + Math.ceil(docRAMRequirements(vectors.size()) / 1024. / 1024.)
+ + "MB of RAM are required to hold metadata about documents in RAM, but current RAM budget is "
+ + ramBudgetMB
+ + "MB");
+ }
+ return new DocMap(computePermutation(vectors, vectorScore, executor));
+ }
+
+ /**
+ * Compute a permutation of the ID space that maximizes vector score between consecutive postings.
+ */
+ private int[] computePermutation(
+ FloatVectorValues vectors, VectorSimilarityFunction vectorScore, TaskExecutor executor) {
+ final int size = vectors.size();
+ int[] sortedIds = new int[size];
+ for (int i = 0; i < size; ++i) {
+ sortedIds[i] = i;
+ }
+ try (CloseableThreadLocal<PerThreadState> threadLocal =
+ new CloseableThreadLocal<>() {
+ @Override
+ protected PerThreadState initialValue() {
+ return new PerThreadState(vectors);
+ }
+ }) {
+ IntsRef ids = new IntsRef(sortedIds, 0, sortedIds.length);
+ new ReorderTask(ids, new float[size], threadLocal, executor, 0, vectorScore).compute();
+ }
+ return sortedIds;
+ }
+
+ /** Returns true if, and only if, the given {@link IntsRef} is sorted. */
+ private static boolean sorted(IntsRef intsRef) {
+ for (int i = 1; i < intsRef.length; ++i) {
+ if (intsRef.ints[intsRef.offset + i - 1] > intsRef.ints[intsRef.offset + i]) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ private static long docRAMRequirements(int maxDoc) {
+ // We need one int per vector for the doc map, plus one float to store the bias associated with
+ // this vector.
+ return 2L * Integer.BYTES * maxDoc;
+ }
+
+ /**
+ * @param args two args: a path containing an index to reorder. the name of the field the contents
+ * of which to use for reordering
+ */
+ @SuppressWarnings("unused")
+ public static void main(String... args) throws IOException {
+ if (args.length < 2 || args.length > 8) {
+ usage();
+ }
+ String directory = args[0];
+ String field = args[1];
+ BpVectorReorderer reorderer = new BpVectorReorderer(field);
+ int threadCount = Runtime.getRuntime().availableProcessors();
+ try {
+ for (int i = 2; i < args.length; i++) {
+ switch (args[i]) {
+ case "--max-iters" -> reorderer.setMaxIters(Integer.parseInt(args[++i]));
+ case "--min-partition-size" -> reorderer.setMinPartitionSize(Integer.parseInt(args[++i]));
+ case "--thread-count" -> threadCount = Integer.parseInt(args[++i]);
+ default -> throw new IllegalArgumentException("unknown argument: " + args[i]);
+ }
+ }
+ } catch (NumberFormatException | ArrayIndexOutOfBoundsException e) {
+ usage();
+ }
+ Executor executor;
+ if (threadCount != 1) {
+ executor = new ForkJoinPool(threadCount, p -> new ForkJoinWorkerThread(p) {}, null, false);
+ } else {
+ executor = null;
+ }
+ try (Directory dir = FSDirectory.open(Path.of(directory))) {
+ reorderer.reorderIndexDirectory(dir, executor);
+ }
+ }
+
+ void reorderIndexDirectory(Directory directory, Executor executor) throws IOException {
+ try (IndexReader reader = DirectoryReader.open(directory)) {
+ IndexWriterConfig iwc = new IndexWriterConfig();
+ iwc.setOpenMode(IndexWriterConfig.OpenMode.CREATE);
+ try (IndexWriter writer = new IndexWriter(directory, iwc)) {
+ for (LeafReaderContext ctx : reader.leaves()) {
+ CodecReader codecReader = (CodecReader) ctx.reader();
+ writer.addIndexes(
+ SortingCodecReader.wrap(
+ codecReader, computeDocMap(codecReader, null, executor), null));
+ }
+ }
+ }
+ }
+
+ private static VectorSimilarityFunction checkField(CodecReader reader, String field)
+ throws IOException {
+ FieldInfo finfo = reader.getFieldInfos().fieldInfo(field);
+ if (finfo == null) {
+ return null;
+ /*
+ throw new IllegalStateException(
+ "field not found: " + field + " in leaf " + reader.getContext().ord);
+ */
+ }
+ if (finfo.hasVectorValues() == false) {
+ return null;
+ /*
+ throw new IllegalStateException(
+ "field not a vector field: " + field + " in leaf " + reader.getContext().ord);
+ */
+ }
+ if (finfo.getVectorEncoding() != VectorEncoding.FLOAT32) {
+ return null;
+ /*
+ throw new IllegalStateException(
+ "vector field not encoded as float32: " + field + " in leaf " + reader.getContext().ord);
+ */
+ }
+ return finfo.getVectorSimilarityFunction();
+ }
+
+ private static void usage() {
+ throw new IllegalArgumentException(
+ """
+ usage: reorder <directory> <field>
+ [--max-iters N]
+ [--min-partition-size P]
+ [--thread-count T]""");
+ }
+
+ private static Sorter.DocMap valueMapToDocMap(
+ Sorter.DocMap valueMap, FloatVectorValues values, int maxDoc) throws IOException {
+ if (maxDoc == values.size()) {
+ return valueMap;
+ }
+ // valueMap maps old/new ords
+ // values maps old docs/old ords
+ // we want old docs/new docs map
+ // sort docs with no value at the end
+ int[] newToOld = new int[maxDoc];
+ int[] oldToNew = new int[newToOld.length];
+ int docid = 0;
+ int ord = 0;
+ int nextNullDoc = values.size();
+ DocIdSetIterator it = values.iterator();
+ for (int nextDoc = it.nextDoc(); nextDoc != NO_MORE_DOCS; nextDoc = it.nextDoc()) {
+ while (docid < nextDoc) {
+ oldToNew[docid] = nextNullDoc;
+ newToOld[nextNullDoc] = docid;
+ ++docid;
+ ++nextNullDoc;
+ }
+ // check me
+ assert docid == nextDoc;
+ int newOrd = valueMap.oldToNew(ord);
+ oldToNew[docid] = newOrd;
+ newToOld[newOrd] = docid;
+ ++ord;
+ ++docid;
+ }
+ while (docid < maxDoc) {
+ oldToNew[docid] = nextNullDoc;
+ newToOld[nextNullDoc] = docid;
+ ++docid;
+ ++nextNullDoc;
+ }
+
+ return new Sorter.DocMap() {
+
+ @Override
+ public int size() {
+ return newToOld.length;
+ }
+
+ @Override
+ public int oldToNew(int docID) {
+ return oldToNew[docID];
+ }
+
+ @Override
+ public int newToOld(int docID) {
+ return newToOld[docID];
+ }
+ };
+ }
+}
diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.java
new file mode 100644
index 00000000000..1fdba7a4eb0
--- /dev/null
+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.java
@@ -0,0 +1,36 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+package org.apache.lucene.misc.index;
+
+import java.io.IOException;
+import java.util.concurrent.Executor;
+import org.apache.lucene.index.CodecReader;
+import org.apache.lucene.index.Sorter;
+import org.apache.lucene.store.Directory;
+
+/** Interface for docid-reordering expected by {@link BPReorderingMergePolicy}. */
+public interface IndexReorderer {
+ /**
+ * Returns a mapping from old to new docids.
+ *
+ * @param reader the reader whose docs are to be reordered
+ * @param tempDir temporary files may be stored here while reordering.
+ * @param executor may be used to parallelize reordering work.
+ */
+ Sorter.DocMap computeDocMap(CodecReader reader, Directory tempDir, Executor executor)
+ throws IOException;
+}
diff --git a/lucene/misc/src/test/org/apache/lucene/misc/index/TestBPReorderingMergePolicy.java b/lucene/misc/src/test/org/apache/lucene/misc/index/TestBPReorderingMergePolicy.java
index b4c68b30c85..9d5b193632d 100644
--- a/lucene/misc/src/test/org/apache/lucene/misc/index/TestBPReorderingMergePolicy.java
+++ b/lucene/misc/src/test/org/apache/lucene/misc/index/TestBPReorderingMergePolicy.java
@@ -20,6 +20,7 @@ import java.io.IOException;
import java.io.UncheckedIOException;
import org.apache.lucene.document.Document;
import org.apache.lucene.document.Field.Store;
+import org.apache.lucene.document.KnnFloatVectorField;
import org.apache.lucene.document.StringField;
import org.apache.lucene.index.CodecReader;
import org.apache.lucene.index.DirectoryReader;
@@ -35,17 +36,32 @@ import org.apache.lucene.search.DocIdSetIterator;
import org.apache.lucene.store.Directory;
import org.apache.lucene.tests.util.LuceneTestCase;
import org.apache.lucene.util.IOUtils;
+import org.junit.Before;
public class TestBPReorderingMergePolicy extends LuceneTestCase {
+ AbstractBPReorderer reorderer;
+
+ @Override
+ @Before
+ public void setUp() throws Exception {
+ super.setUp();
+ if (random().nextBoolean()) {
+ BPIndexReorderer bpIndexReorderer = new BPIndexReorderer();
+ bpIndexReorderer.setMinDocFreq(2);
+ reorderer = bpIndexReorderer;
+ } else {
+ BpVectorReorderer bpVectorReorderer = new BpVectorReorderer("vector");
+ reorderer = bpVectorReorderer;
+ }
+ reorderer.setMinPartitionSize(2);
+ }
+
public void testReorderOnMerge() throws IOException {
Directory dir1 = newDirectory();
Directory dir2 = newDirectory();
IndexWriter w1 =
new IndexWriter(dir1, newIndexWriterConfig().setMergePolicy(newLogMergePolicy()));
- BPIndexReorderer reorderer = new BPIndexReorderer();
- reorderer.setMinDocFreq(2);
- reorderer.setMinPartitionSize(2);
BPReorderingMergePolicy mp = new BPReorderingMergePolicy(newLogMergePolicy(), reorderer);
mp.setMinNaturalMergeNumDocs(2);
IndexWriter w2 = new IndexWriter(dir2, newIndexWriterConfig().setMergePolicy(mp));
@@ -54,10 +70,14 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {
doc.add(idField);
StringField bodyField = new StringField("body", "", Store.YES);
doc.add(bodyField);
+ KnnFloatVectorField vectorField = new KnnFloatVectorField("vector", new float[] {0});
+ doc.add(vectorField);
for (int i = 0; i < 10000; ++i) {
idField.setStringValue(Integer.toString(i));
- bodyField.setStringValue(Integer.toString(i % 2 == 0 ? 0 : i % 10));
+ int intValue = i % 2 == 0 ? 0 : i % 10;
+ bodyField.setStringValue(Integer.toString(intValue));
+ vectorField.setVectorValue(new float[] {intValue});
w1.addDocument(doc);
w2.addDocument(doc);
@@ -131,10 +151,15 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {
doc.add(idField);
StringField bodyField = new StringField("body", "", Store.YES);
doc.add(bodyField);
+ KnnFloatVectorField vectorField = new KnnFloatVectorField("vector", new float[] {0});
+ doc.add(vectorField);
for (int i = 0; i < 10000; ++i) {
idField.setStringValue(Integer.toString(i));
- bodyField.setStringValue(Integer.toString(i % 2 == 0 ? 0 : i % 10));
+ int intValue = i % 2 == 0 ? 0 : i % 10;
+ bodyField.setStringValue(Integer.toString(intValue));
+ vectorField.setVectorValue(new float[] {intValue});
+
w1.addDocument(doc);
if (i % 3 == 0) {
@@ -147,9 +172,6 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {
}
Directory dir2 = newDirectory();
- BPIndexReorderer reorderer = new BPIndexReorderer();
- reorderer.setMinDocFreq(2);
- reorderer.setMinPartitionSize(2);
BPReorderingMergePolicy mp = new BPReorderingMergePolicy(newLogMergePolicy(), reorderer);
mp.setMinNaturalMergeNumDocs(2);
IndexWriter w2 = new IndexWriter(dir2, newIndexWriterConfig().setMergePolicy(mp));
@@ -222,9 +244,6 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {
public void testReorderDoesntHaveEnoughRAM() throws IOException {
// This just makes sure that reordering the index on merge does not corrupt its content
Directory dir = newDirectory();
- BPIndexReorderer reorderer = new BPIndexReorderer();
- reorderer.setMinDocFreq(2);
- reorderer.setMinPartitionSize(2);
reorderer.setRAMBudgetMB(Double.MIN_VALUE);
BPReorderingMergePolicy mp = new BPReorderingMergePolicy(newLogMergePolicy(), reorderer);
mp.setMinNaturalMergeNumDocs(2);
@@ -234,10 +253,14 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {
doc.add(idField);
StringField bodyField = new StringField("body", "", Store.YES);
doc.add(bodyField);
+ KnnFloatVectorField vectorField = new KnnFloatVectorField("vector", new float[] {0});
+ doc.add(vectorField);
for (int i = 0; i < 10; ++i) {
idField.setStringValue(Integer.toString(i));
- bodyField.setStringValue(Integer.toString(i % 2 == 0 ? 0 : i % 10));
+ int intValue = i % 2 == 0 ? 0 : i % 10;
+ bodyField.setStringValue(Integer.toString(intValue));
+ vectorField.setVectorValue(new float[] {intValue});
w.addDocument(doc);
DirectoryReader.open(w).close();
}
diff --git a/lucene/misc/src/test/org/apache/lucene/misc/index/TestBpVectorReorderer.java b/lucene/misc/src/test/org/apache/lucene/misc/index/TestBpVectorReorderer.java
new file mode 100644
index 00000000000..7441e68f7d4
--- /dev/null
+++ b/lucene/misc/src/test/org/apache/lucene/misc/index/TestBpVectorReorderer.java
@@ -0,0 +1,434 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+
+package org.apache.lucene.misc.index;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.concurrent.Executor;
+import java.util.concurrent.ForkJoinPool;
+import java.util.concurrent.ForkJoinWorkerThread;
+import org.apache.lucene.codecs.KnnVectorsFormat;
+import org.apache.lucene.codecs.lucene101.Lucene101Codec;
+import org.apache.lucene.codecs.lucene99.Lucene99HnswScalarQuantizedVectorsFormat;
+import org.apache.lucene.document.Document;
+import org.apache.lucene.document.KnnFloatVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.DirectoryReader;
+import org.apache.lucene.index.FloatVectorValues;
+import org.apache.lucene.index.IndexReader;
+import org.apache.lucene.index.IndexWriter;
+import org.apache.lucene.index.IndexWriterConfig;
+import org.apache.lucene.index.KnnVectorValues;
+import org.apache.lucene.index.LeafReader;
+import org.apache.lucene.index.Sorter;
+import org.apache.lucene.index.StoredFields;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.search.DocIdSetIterator;
+import org.apache.lucene.search.TaskExecutor;
+import org.apache.lucene.store.Directory;
+import org.apache.lucene.tests.util.LuceneTestCase;
+import org.apache.lucene.util.VectorUtil;
+
+/** Tests reordering vector values using Binary Partitioning */
+public class TestBpVectorReorderer extends LuceneTestCase {
+
+ public static final String FIELD_NAME = "knn";
+ BpVectorReorderer reorderer;
+
+ @Override
+ public void setUp() throws Exception {
+ super.setUp();
+ reorderer = new BpVectorReorderer(FIELD_NAME);
+ reorderer.setMinPartitionSize(1);
+ reorderer.setMaxIters(10);
+ }
+
+ private void createQuantizedIndex(Directory dir, List<float[]> vectors) throws IOException {
+ IndexWriterConfig cfg = newIndexWriterConfig();
+ cfg.setCodec(
+ new Lucene101Codec() {
+ @Override
+ public KnnVectorsFormat getKnnVectorsFormatForField(String field) {
+ return new Lucene99HnswScalarQuantizedVectorsFormat(8, 32);
+ }
+ });
+ try (IndexWriter writer = new IndexWriter(dir, cfg)) {
+ int i = 0;
+ for (float[] vector : vectors) {
+ Document doc = new Document();
+ doc.add(new KnnFloatVectorField(FIELD_NAME, vector));
+ doc.add(new StoredField("id", i++));
+ writer.addDocument(doc);
+ }
+ }
+ }
+
+ public void testRandom() {
+ List<float[]> points = new ArrayList<>();
+ // This test may fail for small N; 100 seems big enough for the law of large numbers to make it
+ // work w/very high probability
+ for (int i = 0; i < 100; i++) {
+ points.add(new float[] {random().nextFloat(), random().nextFloat(), random().nextFloat()});
+ }
+ double closestDistanceSum = sumClosestDistances(points);
+ // run one iter so we can see what it did
+ reorderer.setMaxIters(1);
+ Sorter.DocMap map =
+ reorderer.computeValueMap(
+ FloatVectorValues.fromFloats(points, 3), VectorSimilarityFunction.EUCLIDEAN, null);
+ List<float[]> reordered = new ArrayList<>();
+ for (int i = 0; i < points.size(); i++) {
+ reordered.add(points.get(map.newToOld(i)));
+ }
+ double reorderedClosestDistanceSum = sumClosestDistances(reordered);
+ assertTrue(
+ reorderedClosestDistanceSum + ">" + closestDistanceSum,
+ reorderedClosestDistanceSum <= closestDistanceSum);
+ }
+
+ // Compute the sum of (for each point, the absolute difference between its ordinal and the ordinal
+ // of its closest neighbor in Euclidean space) as a measure of whether the reordering successfully
+ // brought vector-space neighbors closer together in ordinal space.
+ private static double sumClosestDistances(List<float[]> points) {
+ int sum = 0;
+ for (int i = 0; i < points.size(); i++) {
+ int closest = -1;
+ double closeness = Double.MAX_VALUE;
+ for (int j = 0; j < points.size(); j++) {
+ if (j == i) {
+ continue;
+ }
+ double distance = VectorUtil.squareDistance(points.get(i), points.get(j));
+ if (distance < closeness) {
+ closest = j;
+ closeness = distance;
+ }
+ }
+ sum += Math.abs(closest - i);
+ }
+ return sum;
+ }
+
+ public void testEuclideanLinear() {
+ doTestEuclideanLinear(null);
+ }
+
+ public void testQuantizedIndex() throws Exception {
+ doTestQuantizedIndex(null);
+ }
+
+ public void testEuclideanLinearConcurrent() {
+ int concurrency = random().nextInt(7) + 1;
+ // The default ForkJoinPool implementation uses a thread factory that removes all permissions on
+ // threads, so we need to create our own to avoid tests failing with FS-based directories.
+ ForkJoinPool pool =
+ new ForkJoinPool(
+ concurrency, p -> new ForkJoinWorkerThread(p) {}, null, random().nextBoolean());
+ try {
+ doTestEuclideanLinear(pool);
+ } finally {
+ pool.shutdown();
+ }
+ }
+
+ private void doTestEuclideanLinear(Executor executor) {
+ // a set of 2d points on a line
+ List<float[]> vectors = randomLinearVectors();
+ List<float[]> shuffled = shuffleVectors(vectors);
+ TaskExecutor taskExecutor = getTaskExecutor(executor);
+ Sorter.DocMap map =
+ reorderer.computeValueMap(
+ FloatVectorValues.fromFloats(shuffled, 2),
+ VectorSimilarityFunction.EUCLIDEAN,
+ taskExecutor);
+ verifyEuclideanLinear(map, vectors, shuffled);
+ }
+
+ private static TaskExecutor getTaskExecutor(Executor executor) {
+ TaskExecutor taskExecutor;
+ if (executor != null) {
+ taskExecutor = new TaskExecutor(executor);
+ } else {
+ taskExecutor = null;
+ }
+ return taskExecutor;
+ }
+
+ private void doTestQuantizedIndex(Executor executor) throws IOException {
+ // a set of 2d points on a line
+ List<float[]> vectors = randomLinearVectors();
+ List<float[]> shuffled = shuffleVectors(vectors);
+ try (Directory dir = newDirectory()) {
+ createQuantizedIndex(dir, shuffled);
+ reorderer.reorderIndexDirectory(dir, executor);
+ int[] newToOld = new int[vectors.size()];
+ int[] oldToNew = new int[vectors.size()];
+ try (IndexReader reader = DirectoryReader.open(dir)) {
+ LeafReader leafReader = getOnlyLeafReader(reader);
+ for (int docid = 0; docid < reader.maxDoc(); docid++) {
+ if (leafReader.getLiveDocs() == null || leafReader.getLiveDocs().get(docid)) {
+ int oldid = Integer.parseInt(leafReader.storedFields().document(docid).get("id"));
+ newToOld[docid] = oldid;
+ oldToNew[oldid] = docid;
+ } else {
+ newToOld[docid] = -1;
+ }
+ }
+ }
+ verifyEuclideanLinear(
+ new Sorter.DocMap() {
+ @Override
+ public int oldToNew(int docID) {
+ return oldToNew[docID];
+ }
+
+ @Override
+ public int newToOld(int docID) {
+ return newToOld[docID];
+ }
+
+ @Override
+ public int size() {
+ return newToOld.length;
+ }
+ },
+ vectors,
+ shuffled);
+ }
+ }
+
+ private static List<float[]> shuffleVectors(List<float[]> vectors) {
+ List<float[]> shuffled = new ArrayList<>(vectors);
+ Collections.shuffle(shuffled, random());
+ return shuffled;
+ }
+
+ private static List<float[]> randomLinearVectors() {
+ int n = random().nextInt(100) + 10;
+ List<float[]> vectors = new ArrayList<>();
+ float b = random().nextFloat();
+ float m = random().nextFloat();
+ float x = random().nextFloat();
+ for (int i = 0; i < n; i++) {
+ vectors.add(new float[] {x, m * x + b});
+ x += random().nextFloat();
+ }
+ return vectors;
+ }
+
+ private static void verifyEuclideanLinear(
+ Sorter.DocMap map, List<float[]> vectors, List<float[]> shuffled) {
+ int count = shuffled.size();
+ assertEquals(count, map.size());
+ float[] midPoint = vectors.get(count / 2);
+ float[] first = shuffled.get(map.newToOld(0));
+ boolean lowFirst = first[0] < midPoint[0];
+ for (int i = 0; i < count; i++) {
+ int oldIndex = map.newToOld(i);
+ assertEquals(i, map.oldToNew(oldIndex));
+ // check the "new" order
+ float[] v = shuffled.get(oldIndex);
+ // first the low vectors, then the high ones, or the other way. Within any given block the
+ // partitioning is kind of arbitrary -
+ // we don't get a global ordering
+ if (i < count / 2 == lowFirst) {
+ assertTrue("out of order at " + i, v[0] <= midPoint[0] && v[1] <= midPoint[1]);
+ } else {
+ assertTrue("out of order at " + i, v[0] >= midPoint[0] && v[1] >= midPoint[1]);
+ }
+ }
+ }
+
+ public void testDotProductCircular() {
+ doTestDotProductCircular(null);
+ }
+
+ public void testDotProductConcurrent() {
+ int concurrency = random().nextInt(7) + 1;
+ // The default ForkJoinPool implementation uses a thread factory that removes all permissions on
+ // threads, so we need to create our own to avoid tests failing with FS-based directories.
+ ForkJoinPool pool =
+ new ForkJoinPool(
+ concurrency, p -> new ForkJoinWorkerThread(p) {}, null, random().nextBoolean());
+ try {
+ doTestDotProductCircular(new TaskExecutor(pool));
+ } finally {
+ pool.shutdown();
+ }
+ }
+
+ public void doTestDotProductCircular(TaskExecutor executor) {
+ // a set of 2d points on a line
+ int n = random().nextInt(100) + 10;
+ List<float[]> vectors = new ArrayList<>();
+ double t = random().nextDouble();
+ for (int i = 0; i < n; i++) {
+ vectors.add(new float[] {(float) Math.cos(t), (float) Math.sin(t)});
+ t += random().nextDouble();
+ }
+ Sorter.DocMap map =
+ reorderer.computeValueMap(
+ FloatVectorValues.fromFloats(vectors, 2),
+ VectorSimilarityFunction.DOT_PRODUCT,
+ executor);
+ assertEquals(n, map.size());
+ double t0min = 2 * Math.PI, t0max = 0;
+ double t1min = 2 * Math.PI, t1max = 0;
+ // find the range of the lower half and the range of the upper half
+ // they should be non-overlapping
+ for (int i = 0; i < n; i++) {
+ int oldIndex = map.newToOld(i);
+ assertEquals(i, map.oldToNew(oldIndex));
+ // check the "new" order
+ float[] v = vectors.get(oldIndex);
+ t = angle2pi(Math.atan2(v[1], v[0]));
+ if (i < n / 2) {
+ t0min = Math.min(t0min, t);
+ t0max = Math.max(t0max, t);
+ } else {
+ t1min = Math.min(t1min, t);
+ t1max = Math.max(t1max, t);
+ }
+ }
+ assertTrue(
+ "ranges overlap",
+ (angularDifference(t0min, t0max) < angularDifference(t0min, t1min)
+ && angularDifference(t0min, t0max) < angularDifference(t0min, t1max))
+ || (angularDifference(t1min, t1max) < angularDifference(t1min, t0min)
+ && angularDifference(t1min, t1max) < angularDifference(t1min, t0max)));
+ }
+
+ public void testIndexReorderDense() throws Exception {
+ List<float[]> vectors = shuffleVectors(randomLinearVectors());
+ // compute the expected ordering
+ Sorter.DocMap expected =
+ reorderer.computeValueMap(
+ FloatVectorValues.fromFloats(vectors, 2), VectorSimilarityFunction.EUCLIDEAN, null);
+ Path tmpdir = createTempDir();
+ try (Directory dir = newFSDirectory(tmpdir)) {
+ // create an index with a single leaf
+ try (IndexWriter writer = new IndexWriter(dir, newIndexWriterConfig())) {
+ int id = 0;
+ for (float[] vector : vectors) {
+ Document doc = new Document();
+ doc.add(new KnnFloatVectorField("f", vector, VectorSimilarityFunction.EUCLIDEAN));
+ doc.add(new StoredField("id", id++));
+ writer.addDocument(doc);
+ }
+ writer.forceMerge(1);
+ }
+ int threadCount = random().nextInt(4) + 1;
+ threadCount = 1;
+ // reorder using the index reordering tool
+ BpVectorReorderer.main(
+ tmpdir.toString(),
+ "f",
+ "--min-partition-size",
+ "1",
+ "--max-iters",
+ "10",
+ "--thread-count",
+ Integer.toString(threadCount));
+ // verify the ordering is the same
+ try (IndexReader reader = DirectoryReader.open(dir)) {
+ LeafReader leafReader = getOnlyLeafReader(reader);
+ FloatVectorValues values = leafReader.getFloatVectorValues("f");
+ int newId = 0;
+ StoredFields storedFields = reader.storedFields();
+ KnnVectorValues.DocIndexIterator it = values.iterator();
+ while (it.nextDoc() != DocIdSetIterator.NO_MORE_DOCS) {
+ int storedId = Integer.parseInt(storedFields.document(it.docID()).get("id"));
+ assertEquals(expected.oldToNew(storedId), newId);
+ float[] expectedVector = vectors.get(expected.newToOld(it.docID()));
+ float[] actualVector = values.vectorValue(it.index());
+ assertArrayEquals(
+ "values differ at index " + storedId + "->" + newId + " docid=" + it.docID(),
+ expectedVector,
+ actualVector,
+ 0);
+ newId++;
+ }
+ }
+ }
+ }
+
+ public void testIndexReorderSparse() throws Exception {
+ List<float[]> vectors = shuffleVectors(randomLinearVectors());
+ // compute the expected ordering
+ Sorter.DocMap expected =
+ reorderer.computeValueMap(
+ FloatVectorValues.fromFloats(vectors, 2), VectorSimilarityFunction.EUCLIDEAN, null);
+ Path tmpdir = createTempDir();
+ int maxDoc = 0;
+ try (Directory dir = newFSDirectory(tmpdir)) {
+ // create an index with a single leaf
+ try (IndexWriter writer = new IndexWriter(dir, newIndexWriterConfig())) {
+ for (float[] vector : vectors) {
+ Document doc = new Document();
+ if (random().nextBoolean()) {
+ for (int i = 0; i < random().nextInt(3); i++) {
+ // insert some gaps -- docs with no vectors
+ writer.addDocument(doc);
+ maxDoc++;
+ }
+ }
+ doc.add(new KnnFloatVectorField("f", vector, VectorSimilarityFunction.EUCLIDEAN));
+ writer.addDocument(doc);
+ maxDoc++;
+ }
+ writer.forceMerge(1);
+ }
+ // reorder using the index reordering tool
+ BpVectorReorderer.main(
+ tmpdir.toString(), "f", "--min-partition-size", "1", "--max-iters", "10");
+ // verify the ordering is the same
+ try (IndexReader reader = DirectoryReader.open(dir)) {
+ LeafReader leafReader = getOnlyLeafReader(reader);
+ assertEquals(maxDoc, leafReader.maxDoc());
+ FloatVectorValues values = leafReader.getFloatVectorValues("f");
+ int lastDocID = 0;
+ KnnVectorValues.DocIndexIterator it = values.iterator();
+ while (it.nextDoc() != DocIdSetIterator.NO_MORE_DOCS) {
+ lastDocID = it.docID();
+ float[] expectedVector = vectors.get(expected.newToOld(lastDocID));
+ float[] actualVector = values.vectorValue(it.index());
+ assertArrayEquals(expectedVector, actualVector, 0);
+ }
+ // docs with no vectors sort at the end
+ assertEquals(vectors.size() - 1, lastDocID);
+ }
+ }
+ }
+
+ static double angularDifference(double a, double b) {
+ return angle2pi(b - a);
+ }
+
+ static double angle2pi(double a) {
+ while (a > 2 * Math.PI) {
+ a -= 2 * Math.PI;
+ }
+ while (a < 0) {
+ a += 2 * Math.PI;
+ }
+ return a;
+ }
+}
diff --git a/lucene/test-framework/src/java/org/apache/lucene/tests/codecs/asserting/AssertingKnnVectorsFormat.java b/lucene/test-framework/src/java/org/apache/lucene/tests/codecs/asserting/AssertingKnnVectorsFormat.java
index bd2911fc50a..22fa438b04b 100644
--- a/lucene/test-framework/src/java/org/apache/lucene/tests/codecs/asserting/AssertingKnnVectorsFormat.java
+++ b/lucene/test-framework/src/java/org/apache/lucene/tests/codecs/asserting/AssertingKnnVectorsFormat.java
@@ -223,7 +223,11 @@ public class AssertingKnnVectorsFormat extends KnnVectorsFormat {
@Override
public HnswGraph getGraph(String field) throws IOException {
- return ((HnswGraphProvider) delegate).getGraph(field);
+ if (delegate instanceof HnswGraphProvider) {
+ return ((HnswGraphProvider) delegate).getGraph(field);
+ } else {
+ return null;
+ }
}
}
}