Block grouping's TopGroups.maxScore changes with the index slicing: it can come from a group that is not returned

Since 10.5.0, GroupingSearch block grouping (new GroupingSearch(Query groupEndDocs)) runs through BlockGroupingCollectorManager, so on an IndexSearcher with an executor every slice collects its own top groupOffset + topNGroups groups and TopGroups.mergeBlockGroups merges them. Each slice reports a maxScore over the groups it kept, and for a field group sort the merge takes the maximum of those values before its k-way merge decides which groups are returned. A group that one slice kept but the merge drops can therefore set the top-level TopGroups.maxScore, and the value changes with how segments fall into slices.

In the minimal test the same query on the same six-segment index reports 1.0 sequentially and 2.0 with the default two slices, for the same single returned group (best score 1.0); the best hit overall scores 6.0. The executed releases before 10.5.0 (10.4.0 and 9.12.3) report one value with or without an executor, and two-pass grouping takes the maximum over the returned groups. Only this one field is wrong: the groups, their documents and order, each GroupDocs.maxScore and the hit counts are correct. Same root cause, secondary: with groupOffset > 0, block grouping now also counts the skipped groups, even without an executor. All of this is at withinGroupOffset 0; with withinGroupOffset > 0 the sibling bug LFV-230 can also lower a group's value.

// BlockGroupingCollectorManager.java:141-144: every slice keeps groupOffset + topNGroups groups
return new BlockGroupingCollector(groupSort, groupOffset + topNGroups, needsScores, lastDocPerGroup);

// BlockGroupingCollectorManager.java:148-159: each slice reports all its kept groups (offset 0), then the merge
collector.getTopGroups(withinGroupSort, 0, withinGroupOffset, maxDocsPerGroup);      // :151-152
return TopGroups.mergeBlockGroups(shardGroupsList, groupSort, groupOffset, topNGroups, withinGroupSort);

// TopGroups.java:404-437, mergeBlockGroups
for (...) {                                                       // :407-417, fill the queue
  if (!groupSortByRelevance) {
    totalMaxScore = nonNANmax(totalMaxScore, topGroups.maxScore); // :412-414, every slice's value
  } ...
}
while (!queue.isEmpty()) {                                        // :425-446, k-way merge
  ...
  if (count++ >= groupOffset) { groupDocsList.add(currentGroupDocs); ... }   // :431-437, the page
}

1. Per slice. Each slice's collector keeps its top groupOffset + topNGroups groups, and reduce asks for all of them (offset 0). The slice's TopGroups.maxScore is the maximum over those groups (BlockGroupingCollector.java:339-341), including groups that the merge later drops or skips.
2. Merge. For a field group sort, mergeBlockGroups takes the maximum of every slice's maxScore while it fills the queue, before the k-way merge picks the page.
3. Result. A group that some slice kept but the merge does not return can set the value. Which groups a slice keeps depends on which segments share a slice; the default slicing gives more than one slice once there are more than 5 segments (IndexSearcher.java:108, MAX_SEGMENTS_PER_SLICE = 5) or segments that pass the 250,000-documents-per-slice limit (:106, :361-363, :374-378; two segments of 250,001 documents give 1.0 vs 2.0 the same way). Several slices only enable the trigger: the value is wrong when some slice keeps a group that is not returned and scores higher than every returned group.
4. Contrast. The two-pass merge, TopGroups.merge, takes the maximum over the merged groups (TopGroups.java:290). Before 10.5.0, GroupingSearch ran one BlockGroupingCollector through IndexSearcher.search(Query, Collector), which visits segments in sequence even with an executor.

The merge formula would be exact if every slice reported a true "highest score across all hits" (TopGroups.java:59); its only non-test in-tree call path, BlockGroupingCollectorManager, feeds it BlockGroupingCollector results, which report the maximum over the groups each slice kept. The defect is that mismatch.

The sequential search (one slice) reports 1.0; the best hit overall scores 6.0. Any split into two or more slices fails the same way, because the slice without v = 1 contributes its own top group's score, at least 2.0.

Because each slice reports with offset 0, the groups before the requested page count even with a single slice. Single-document groups P (sort rank 1, score 5), Q (rank 2, score 1) and R (rank 3, score 9), groupOffset = 1, top 1 returns Q: main and 10.5.2 report 5.0, from the skipped group P; 10.4.0 and 9.12.3 report 1.0. Taken alone this moves towards the javadoc's "across all hits", so it is a behaviour change rather than a second bug.

Not affected: a relevance group sort at groupOffset 0, where the slice holding the top group also holds the best hit (TopGroups.java:419-421).

• Who. Applications that index groups as document blocks and use block grouping, GroupingSearch(Query groupEndDocs) or BlockGroupingCollectorManager directly (both @lucene.experimental), with a field group sort, and read the top-level TopGroups.maxScore, for example to normalise scores or to apply a relative score cut-off.
  • With an executor: whenever the default slicing gives more than one slice (more than 5 segments, or segments that pass the 250,000-documents-per-slice limit; two segments of 250,001 documents are enough), and a slice keeps a higher-scoring group that is not on the page; there is no setting to change. A thread pool is not needed: a same-thread executor (Runnable::run) takes the same path.
  • Without an executor: only with groupOffset > 0 (the secondary symptom).
• Not affected. The groups, their documents and order, GroupDocs.maxScore, totalHitCount and totalGroupedHitCount; two-pass grouping (by field or function); a relevance group sort at groupOffset 0.
• Silent and unstable. The value is a real score of a matching document, no error is raised, and it can change whenever segments are flushed or merged, so the same query on the same documents can give different numbers over time.
• No scale needed. Six one-document segments show it.
• How likely: rare. A code search of the default branches of Solr, Elasticsearch and OpenSearch found no use of block grouping's collector, manager or merge; Lucene itself never reads the field to make a decision; it has shipped since 10.5.0 (June 2026), and no user report was found in the recorded searches.

Deterministic, single thread (Runnable::run is the executor: the defect is the per-slice merge, not concurrency), no random() in the test body; seeds DEADBEEF and 5EED1234 give the same values with assertions on and off. The scores come from FunctionScoreQuery over DoubleValuesSource.fromIntField("v"), so each document's score is its sort value and every number is exact.

It asserts only that the value does not depend on the slicing, so it is fix-neutral: it passes with fix A (both searchers 1.0) and with fix B (both 6.0), and is the regression test for either. It does not show the secondary groupOffset > 0 symptom: with v as both sort key and score, skipped groups always score lower.

cp $REPRO/TestBlockGroupingMaxScoreSlicing.java $LUCENE/lucene/grouping/src/test/org/apache/lucene/search/grouping/
cd $LUCENE && ./gradlew :lucene:grouping:test --tests TestBlockGroupingMaxScoreSlicing -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off fails the same way: -Ptests.asserts=false

TestBlockGroupingMaxScoreSlicing > testMaxScoreDoesNotDependOnSlicing FAILED
    java.lang.AssertionError: TopGroups.maxScore, 1 slice vs 2 slices expected:<1.0> but was:<2.0>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:E32C53693FF4A61F]:0)
        at junit@4.13.2/org.junit.Assert.fail(Assert.java:89)
        at junit@4.13.2/org.junit.Assert.failNotEquals(Assert.java:835)
        at junit@4.13.2/org.junit.Assert.assertEquals(Assert.java:577)
        at org.apache.lucene.search.grouping.TestBlockGroupingMaxScoreSlicing.testMaxScoreDoesNotDependOnSlicing(TestBlockGroupingMaxScoreSlicing.java:62)

1 test completed, 1 failed

• One query, one index, one value. Every existing definition gives a single value: the javadoc's "Highest score across all hits, or Float.NaN if scores were not computed" (TopGroups.java:59; 6.0 in the repro), or the maximum over the returned groups, which two-pass TopGroups.merge computes (TopGroups.java:290) and block grouping reported in 10.4.0 and 9.12.3 (1.0). None allows a number that changes with the executor's slicing (2.0).
• #15936 was a parallelisation change. lucene/CHANGES.txt:1009, under 10.5.0: "GITHUB#15936: Introduce BlockGroupingCollectorManager to parallelize search when using BlockGroupingCollector." Nothing records a change to maxScore.
• Intent in the review. On #15936 javanna asked (2026-05-19) "is the maxScore only read once from the first group?", and gaobinlong replied (2026-05-25) "This is really a bug, we need to compute maxScore by iterating on all TopGroups, only for the case of sort by relevance, we can get the maxScore directly from the head of the queue after initialized." That fixed an earlier first-group-only value; nobody said that a slice's maxScore also covers groups the merge drops, or that the value may change with slicing.
• Grouping maxScore errors have been fixed as bugs before: LUCENE-8996 (#10039, distributed maxScore NaN) and #15872/#15873 (NaN maxScore). TestTopGroups.java:207-215 asserts the exact merged maxScore of merge().
• Why tests missed it. No grouping test asserts block grouping's TopGroups.maxScore; #15936's tests do not read it, and TestGrouping's per-group check is a commented-out // TODO // assertEquals(expectedGroup.maxScore, actualGroup.maxScore); (TestGrouping.java:1632-1633).

The strongest case for "intended" (the intended-behaviour check and the cross-model reviewer rated it moderate): the cross-slice maximum was chosen on purpose, and it matches the javadoc's "across all hits". If every slice reported a true all-hits maximum the merge would be exactly right, and the reviewer's direct-input test shows that stock mergeBlockGroups keeps such a value. The javadoc has never held literally for block or two-pass grouping, so maxScore is loosely defined; no test asserts it; the classes are @lucene.experimental; and the finder's first test overrode slices().

Why it fails: the premise is false for the merge's only non-test in-tree caller, BlockGroupingCollectorManager, whose slices report the maximum over an arbitrary, slicing-dependent set of kept groups; the result (2.0) is neither all hits (6.0) nor the page (1.0). "Loosely defined" still means one value per query and index. "Experimental" is about API stability; no javadoc promises that the value is the same for every slicing either, so the fair reading is a likely correctness defect whose intended meaning upstream must pick (the cross-model reviewer's point). The minimal test uses the default slicing, and its scores and sort values are distinct, so ties play no part. Verdict: not intended, a defect; which consistent meaning the fix restores is upstream's call.

Both options were applied to a scratch worktree of 645d4fe14a20 and run with gradle (OpenJDK 25.0.3, 2026-10-31). Which one is right is upstream's call: A restores what the executed releases before 10.5.0 (10.4.0, 9.12.3) and two-pass grouping report; B makes the javadoc's "highest score across all hits" literally true. No javadoc says which meaning grouped results should have, so the choice is open.

What each searcher reports on the minimal test's index (a printing probe on the same index and query, not a repro):

The best hit overall scores 6.0.

+2/-8 lines in TopGroups.mergeBlockGroups: drop the pre-merge aggregation (groupSortByRelevance, the nonNANmax over every slice's maxScore, the relevance branch) and take the maximum while the k-way merge fills the page.

while (!queue.isEmpty()) {
  ...
  if (count++ >= groupOffset) {
    groupDocsList.add(currentGroupDocs);
    // like merge(): the maximum over the groups that are returned
    totalMaxScore = nonNANmax(totalMaxScore, currentGroupDocs.maxScore());
    totalGroupedHitCount += (int) currentGroupDocs.totalHits().value();
    ...

Trade-offs

• Matches TopGroups.merge and the pre-10.5 value with and without an executor, and also undoes the groupOffset > 0 change (1.0 again in the P/Q/R case, as on 10.4.0). A relevance group sort at offset 0 keeps its value.
• Does not make the javadoc's "Highest score across all hits" true (no release did); upstream may want to reword it for grouped results (not drafted).
• mergeBlockGroups is public: a direct caller whose inputs already carry all-hits maxima would now get the page maximum (the cross-model reviewer's direct-input test: expected 25.0, got 1.0). No in-tree caller passes such inputs.
• It reads GroupDocs.maxScore, so with withinGroupOffset > 0 and relevance order it inherits the per-group value of the sibling bug LFV-230 until that is fixed (the stock code does too).

What the checks validated

• Stock 645d4fe14a20: the minimal test fails with assertions on and off.
• With A: ./gradlew :lucene:grouping:test (the whole module, the minimal test included) passes: 15 classes, 57 tests, 0 failures, seed DEADBEEF with assertions on and seed C0FFEE with assertions off; this includes TestBlockGrouping, TestGroupingSearch, TestGrouping and TestTopGroups. The probe gives 1.0 for both searchers.
• Earlier, on ea57360912ed: the finder's, the independent reproduction's, the intended-behaviour check's and the cross-model reviewer's own tests pass with A.

+4/-3 lines in BlockGroupingCollector: a field updated where each hit's score is recorded, and the per-slice maxScore set from it. The existing merge then takes the maximum of true all-hits maxima and is exact.

private float maxScoreAllHits = Float.NaN;   // new field
// collect(): where each hit's score is recorded
pendingSubScores[subDocUpto] = scorer.score();
maxScoreAllHits = TopGroups.nonNANmax(maxScoreAllHits, pendingSubScores[subDocUpto]);
// getTopGroups(): replaces "if (groupSortByRelevance) maxScore = groups[0].maxScore();"
maxScore = needsScores ? maxScoreAllHits : Float.NaN;

Trade-offs

• Makes TopGroups.maxScore literally "highest score across all hits" and leaves mergeBlockGroups unchanged for direct callers.
• Behaviour change for every block-grouping user, sequential ones included: the minimal test's value goes from 1.0 (every executed release, sequentially) to 6.0, a score from a group that is not on the page, and the P/Q/R groupOffset = 1 case to 9.0. Applications that normalise by maxScore see different numbers after upgrading.
• Independent of the per-group sibling bug. One extra max per collected hit when scores are needed; not benchmarked.

What the checks validated

• With B: the whole grouping module passes: 15 classes, 57 tests, 0 failures, seed DEADBEEF with assertions on and seed C0FFEE with assertions off. The probe gives 6.0 for both searchers. Upstream's suites had not been run with B before.

Method: semi-formal (bounded-exhaustive translation validation: the real jar is checked against exact semantics on every input up to a small scope; no model checker, SMT solver or proof is involved).

• A hunt unit (grouping) built tiny indexes with groups in {A, B, none} and values {0, 1, 2} used as score and sort key, tried every split into segments and 7 slicings, and every group sort x within-group sort x group page x document page. It compared each result with an exact reference written from the javadoc, with sequential search and with a distributed merge.
• The first signal, on the stock main jar: kind BSEQ_VS_CONC:TG_MAXSCORE_RET in scope block3 (same returned group, sequential maxScore 1.0, concurrent 2.0, distinct sort values, so not a tie effect). A focused probe then showed the concurrent value matches neither the returned groups nor all hits.
• Scope block5 (19,683 indexes, 13,988,052 checks, 29 s) reports that kind 155,919 times (raw counts are not split by root cause). With the unit's combined fix sketches shadowed, the sequential-vs-concurrent, reference and distributed maxScore kinds disappear in block5 and block6.
• The finder wrote a public-API JUnit (three one-document blocks in two segments, one slice per segment); the independent reproduction and the intended-behaviour check showed the default slicing suffices; it was then minimised by hand into the one-test repro above (2026-10-29).