Apache Lucene open-source search software
Disable skipper-based term competitive iterators if they are not effective (#15709)
Alan Woodward7501422c2e6b
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txtindex a610e0ff796..935ecd655e7 100644--- a/lucene/CHANGES.txt+++ b/lucene/CHANGES.txt@@ -363,7 +363,8 @@ Optimizations* GITHUB#15498: ExitableDirectoryReader keeps singleton SortedSetDocValues or SortedNumericDocValues as singletons. (Houston Putman)-* GITHUB#15511, GITHUB#15696: Dynamic pruning for SORTED(_SET) fields with doc values skipper (Pan Guixin, Alan Woodward)+* GITHUB#15511, GITHUB#15696, GITHUB#15709: Dynamic pruning for SORTED(_SET) fields with doc+ values skipper (Pan Guixin, Alan Woodward)* GITHUB#15560: Avoid unnecessary getGraph() call. (Shubham Chaudhary)diff --git a/lucene/core/src/java/org/apache/lucene/search/comparators/TermOrdValComparator.java b/lucene/core/src/java/org/apache/lucene/search/comparators/TermOrdValComparator.javaindex 7b6b45bfc49..6a9962fa356 100644--- a/lucene/core/src/java/org/apache/lucene/search/comparators/TermOrdValComparator.java+++ b/lucene/core/src/java/org/apache/lucene/search/comparators/TermOrdValComparator.java@@ -38,6 +38,7 @@ import org.apache.lucene.search.Scorable;import org.apache.lucene.search.SkipBlockRangeIterator;import org.apache.lucene.util.BytesRef;import org.apache.lucene.util.BytesRefBuilder;+import org.apache.lucene.util.FixedBitSet;import org.apache.lucene.util.PriorityQueue;/**@@ -196,7 +197,7 @@ public class TermOrdValComparator extends FieldComparator<BytesRef> {return val1.compareTo(val2);}- private class TermOrdValLeafComparator implements LeafFieldComparator {+ class TermOrdValLeafComparator implements LeafFieldComparator {/* Current reader's doc ord/values. */final SortedDocValues termsIndex;@@ -488,6 +489,13 @@ public class TermOrdValComparator extends FieldComparator<BytesRef> {public DocIdSetIterator competitiveIterator() {return competitiveState != null ? competitiveState.iterator : null;}++ // package-private for testing+ boolean isSkippingDisabled() {+ // index-based competitive iterators are never disabled+ return competitiveState instanceof SkipperBasedCompetitiveState skipperState+ && skipperState.state == SkipperBasedCompetitiveState.State.DISABLED;+ }}private record PostingsEnumAndOrd(PostingsEnum postings, int ord) {}@@ -625,17 +633,115 @@ public class TermOrdValComparator extends FieldComparator<BytesRef> {}private static class SkipperBasedCompetitiveState extends CompetitiveState {++ private static final int WARMUP_BOUNDARY_CROSSINGS = 16;++ private enum State {+ WARMING,+ ACTIVE,+ DISABLED+ }+private final DocValuesSkipper skipper;+ private final int maxDoc;+ private int prevMinOrd = Integer.MIN_VALUE;+ private int prevMaxOrd = Integer.MIN_VALUE;+ private State state = State.WARMING;SkipperBasedCompetitiveState(LeafReaderContext context, DocValuesSkipper skipper) {super(context);this.skipper = skipper;- this.iterator.update(DocIdSetIterator.all(context.reader().maxDoc()));+ this.maxDoc = context.reader().maxDoc();+ this.iterator.update(DocIdSetIterator.all(maxDoc));}@Overridepublic void update(int minOrd, int maxOrd) {- iterator.update(new SkipBlockRangeIterator(skipper, minOrd, maxOrd));+ if (state == State.DISABLED) {+ return;+ }+ if (minOrd == prevMinOrd && maxOrd == prevMaxOrd) {+ return;+ }+ prevMinOrd = minOrd;+ prevMaxOrd = maxOrd;+ iterator.update(+ new AdaptiveSkipIterator(new SkipBlockRangeIterator(skipper, minOrd, maxOrd)));+ }++ /**+ * Wraps a {@link SkipBlockRangeIterator} and monitors whether skipping is effective. Tracks+ * block boundary crossings using the skipper's level-0 block end so that within-block advances+ * (which always return target) do not dilute the signal. After {@link+ * #WARMUP_BOUNDARY_CROSSINGS} boundary crossings with no effective skip observed, the wrapper+ * disables itself and becomes a trivial pass-through iterator. If any boundary crossing+ * produces an effective skip, the wrapper stops monitoring and continues using the skip+ * iterator permanently.+ */+ private class AdaptiveSkipIterator extends AbstractDocIdSetIterator {+ private final SkipBlockRangeIterator in;+ private int blockEndDoc = -1;+ private int boundaryCrossings;++ AdaptiveSkipIterator(SkipBlockRangeIterator in) {+ this.in = in;+ }++ @Override+ public int nextDoc() throws IOException {+ return advance(doc + 1);+ }++ @Override+ public int advance(int target) throws IOException {+ return doc =+ switch (state) {+ case DISABLED -> target;+ case ACTIVE -> in.advance(target);+ case WARMING -> {+ int result = in.advance(target);+ if (target > blockEndDoc) {+ blockEndDoc = skipper.maxDocID(0);+ boundaryCrossings++;+ if (result > target) {+ // skipping has happened, so switch to permanently active skipping+ state = State.ACTIVE;+ } else if (boundaryCrossings >= WARMUP_BOUNDARY_CROSSINGS) {+ // we've crossed a number of block boundaries without any skipping+ // happening, so it's not helping. Switch to no skipping to avoid+ // overhead.+ state = State.DISABLED;+ iterator.update(DocIdSetIterator.all(maxDoc));+ }+ }+ yield result;+ }+ };+ }++ @Override+ public long cost() {+ return in.cost();+ }++ @Override+ public int docIDRunEnd() throws IOException {+ if (state == State.DISABLED) {+ return NO_MORE_DOCS;+ }+ return in.docIDRunEnd();+ }++ @Override+ public void intoBitSet(int upTo, FixedBitSet bitSet, int offset) throws IOException {+ if (state == State.DISABLED) {+ bitSet.set(doc - offset, upTo - offset);+ doc = upTo;+ return;+ }+ in.intoBitSet(upTo, bitSet, offset);+ doc = in.docID();+ }}}}diff --git a/lucene/core/src/test/org/apache/lucene/search/comparators/TestTermOrdValComparatorAdaptiveSkipping.java b/lucene/core/src/test/org/apache/lucene/search/comparators/TestTermOrdValComparatorAdaptiveSkipping.javanew file mode 100644index 00000000000..21641366736--- /dev/null+++ b/lucene/core/src/test/org/apache/lucene/search/comparators/TestTermOrdValComparatorAdaptiveSkipping.java@@ -0,0 +1,249 @@+/*+ * 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.search.comparators;++import java.io.IOException;+import java.util.function.IntFunction;+import org.apache.lucene.document.Document;+import org.apache.lucene.document.Field;+import org.apache.lucene.document.SortedDocValuesField;+import org.apache.lucene.document.StringField;+import org.apache.lucene.index.DirectoryReader;+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.Term;+import org.apache.lucene.search.DocIdSetIterator;+import org.apache.lucene.search.FieldDoc;+import org.apache.lucene.search.IndexSearcher;+import org.apache.lucene.search.LeafFieldComparator;+import org.apache.lucene.search.Pruning;+import org.apache.lucene.search.Query;+import org.apache.lucene.search.Sort;+import org.apache.lucene.search.SortField;+import org.apache.lucene.search.TermQuery;+import org.apache.lucene.search.TopFieldCollectorManager;+import org.apache.lucene.search.TopFieldDocs;+import org.apache.lucene.store.Directory;+import org.apache.lucene.tests.util.LuceneTestCase;+import org.apache.lucene.util.BytesRef;++/**+ * Tests that the adaptive skipping logic in TermOrdValComparator's SkipperBasedCompetitiveState+ * preserves correctness across data distributions, and that it disables skipping when the skip+ * index is ineffective.+ */+public class TestTermOrdValComparatorAdaptiveSkipping extends LuceneTestCase {++ private static final String SORT_FIELD_SKIP = "sort.skip";+ private static final String SORT_FIELD_NO_SKIP = "sort.noskip";+ private static final String QUERY_FIELD = "match";+ private static final String QUERY_VALUE = "yes";+ private static final int NUM_DOCS = 200_000;+ private static final int NUM_HITS = 10;+ private static final int TOTAL_HITS_THRESHOLD = 1;++ /**+ * For interleaved data (alternating values uncorrelated with doc order), the adaptive logic may+ * disable skipping. Verify that top-N results are identical to the non-skip baseline.+ */+ public void testResultsCorrectForInterleavedData() throws Exception {+ BytesRef a = new BytesRef("a");+ BytesRef z = new BytesRef("z");+ try (Directory dir = newDirectory()) {+ buildIndex(dir, i -> (i & 1) == 0 ? a : z);+ try (IndexReader reader = DirectoryReader.open(dir)) {+ assertTopNMatch(new IndexSearcher(reader));+ }+ }+ }++ /**+ * For clustered data (values sorted with doc order), skipping should remain active and prune+ * non-competitive blocks. Verify results are correct AND that totalHits is significantly lower+ * with skipping, showing that the adaptive logic did not incorrectly disable.+ */+ public void testSkippingEffectiveForClusteredData() throws Exception {+ BytesRef a = new BytesRef("a");+ BytesRef z = new BytesRef("z");+ try (Directory dir = newDirectory()) {+ buildIndex(dir, i -> i < NUM_DOCS / 2 ? a : z);+ try (IndexReader reader = DirectoryReader.open(dir)) {+ IndexSearcher searcher = new IndexSearcher(reader);++ assertTopNMatch(searcher);++ TopFieldDocs withSkip = searchSort(searcher, SORT_FIELD_SKIP);+ TopFieldDocs withoutSkip = searchSort(searcher, SORT_FIELD_NO_SKIP);++ assertTrue(+ "Expected skip-enabled totalHits ("+ + withSkip.totalHits.value()+ + ") to be significantly lower than non-skip ("+ + withoutSkip.totalHits.value()+ + "), proving skipping was not incorrectly disabled",+ withSkip.totalHits.value() < withoutSkip.totalHits.value() * 3 / 4);+ }+ }+ }++ /**+ * For random data, results must still be correct regardless of whether skipping is active or+ * adaptively disabled.+ */+ public void testResultsCorrectForRandomData() throws Exception {+ BytesRef[] values = new BytesRef[26];+ for (int i = 0; i < 26; i++) {+ values[i] = new BytesRef(Character.toString((char) ('a' + i)));+ }+ try (Directory dir = newDirectory()) {+ buildIndex(dir, _ -> values[random().nextInt(values.length)]);+ try (IndexReader reader = DirectoryReader.open(dir)) {+ assertTopNMatch(new IndexSearcher(reader));+ }+ }+ }++ /**+ * Directly exercises the comparator with interleaved data and verifies that adaptive disabling+ * fires via {@link TermOrdValComparator.TermOrdValLeafComparator#isSkippingDisabled()}.+ */+ public void testAdaptiveDisablingFiresForInterleavedData() throws Exception {+ BytesRef a = new BytesRef("a");+ BytesRef z = new BytesRef("z");+ try (Directory dir = newDirectory()) {+ buildIndex(dir, i -> (i & 1) == 0 ? a : z);+ try (IndexReader reader = DirectoryReader.open(dir)) {+ assertEquals(1, reader.leaves().size());+ LeafReaderContext leafContext = reader.leaves().get(0);+ int maxDoc = leafContext.reader().maxDoc();++ TermOrdValComparator comparator =+ new TermOrdValComparator(1, SORT_FIELD_SKIP, false, false, Pruning.GREATER_THAN);+ LeafFieldComparator leafComp = comparator.getLeafComparator(leafContext);+ assertTrue(leafComp instanceof TermOrdValComparator.TermOrdValLeafComparator);+ var typedLeafComp = (TermOrdValComparator.TermOrdValLeafComparator) leafComp;++ leafComp.copy(0, 0);+ leafComp.setBottom(0);+ leafComp.setHitsThresholdReached();++ DocIdSetIterator competitiveIter = leafComp.competitiveIterator();+ assumeTrue(+ "Competitive iterator not available (codec may not support skip index)",+ competitiveIter != null);++ assertFalse(+ "Skipping should not be disabled before iteration", typedLeafComp.isSkippingDisabled());++ // Advance through the entire segment+ int doc = 0;+ while (doc < maxDoc) {+ int next = competitiveIter.advance(doc);+ if (next == DocIdSetIterator.NO_MORE_DOCS) break;+ doc = next + 1;+ }++ assertTrue(+ "Skipping should be adaptively disabled after traversing interleaved data",+ typedLeafComp.isSkippingDisabled());+ }+ }+ }++ /**+ * Directly exercises the comparator with clustered data and verifies that adaptive disabling does+ * NOT fire, because the skip iterator successfully skips non-competitive blocks.+ */+ public void testAdaptiveDisablingDoesNotFireForClusteredData() throws Exception {+ BytesRef a = new BytesRef("a");+ BytesRef z = new BytesRef("z");+ try (Directory dir = newDirectory()) {+ buildIndex(dir, i -> i < NUM_DOCS / 2 ? a : z);+ try (IndexReader reader = DirectoryReader.open(dir)) {+ assertEquals(1, reader.leaves().size());+ LeafReaderContext leafContext = reader.leaves().get(0);+ int maxDoc = leafContext.reader().maxDoc();++ TermOrdValComparator comparator =+ new TermOrdValComparator(1, SORT_FIELD_SKIP, false, false, Pruning.GREATER_THAN);+ LeafFieldComparator leafComp = comparator.getLeafComparator(leafContext);+ assertTrue(leafComp instanceof TermOrdValComparator.TermOrdValLeafComparator);+ var typedLeafComp = (TermOrdValComparator.TermOrdValLeafComparator) leafComp;++ leafComp.copy(0, 0);+ leafComp.setBottom(0);+ leafComp.setHitsThresholdReached();++ DocIdSetIterator competitiveIter = leafComp.competitiveIterator();+ assumeTrue(+ "Competitive iterator not available (codec may not support skip index)",+ competitiveIter != null);++ // Advance through the entire segment+ int doc = 0;+ while (doc < maxDoc) {+ int next = competitiveIter.advance(doc);+ if (next == DocIdSetIterator.NO_MORE_DOCS) break;+ doc = next + 1;+ }++ assertFalse(+ "Skipping should remain active for clustered data", typedLeafComp.isSkippingDisabled());+ }+ }+ }++ private void buildIndex(Directory dir, IntFunction<BytesRef> valueSupplier) throws IOException {+ IndexWriterConfig config = newIndexWriterConfig();+ try (IndexWriter writer = new IndexWriter(dir, config)) {+ for (int i = 0; i < NUM_DOCS; i++) {+ Document doc = new Document();+ doc.add(new StringField(QUERY_FIELD, QUERY_VALUE, Field.Store.NO));+ BytesRef value = valueSupplier.apply(i);+ doc.add(new SortedDocValuesField(SORT_FIELD_NO_SKIP, value));+ doc.add(SortedDocValuesField.indexedField(SORT_FIELD_SKIP, value));+ writer.addDocument(doc);+ }+ writer.forceMerge(1);+ }+ }++ private void assertTopNMatch(IndexSearcher searcher) throws IOException {+ TopFieldDocs withSkip = searchSort(searcher, SORT_FIELD_SKIP);+ TopFieldDocs withoutSkip = searchSort(searcher, SORT_FIELD_NO_SKIP);++ assertEquals(+ "Top-N result count should match", withSkip.scoreDocs.length, withoutSkip.scoreDocs.length);+ for (int i = 0; i < withSkip.scoreDocs.length; i++) {+ FieldDoc skipDoc = (FieldDoc) withSkip.scoreDocs[i];+ FieldDoc noSkipDoc = (FieldDoc) withoutSkip.scoreDocs[i];+ assertEquals(+ "Sort value at position " + i + " should match", skipDoc.fields[0], noSkipDoc.fields[0]);+ }+ }++ private TopFieldDocs searchSort(IndexSearcher searcher, String field) throws IOException {+ Query query = new TermQuery(new Term(QUERY_FIELD, QUERY_VALUE));+ SortField sortField = new SortField(field, SortField.Type.STRING);+ Sort sort = new Sort(sortField, SortField.FIELD_SCORE);+ TopFieldCollectorManager manager =+ new TopFieldCollectorManager(sort, NUM_HITS, null, TOTAL_HITS_THRESHOLD);+ return searcher.search(query, manager);+ }+}