Monitor scores a DisjunctionMaxQuery as the sum of its matching disjuncts

The Monitor (lucene-monitor) matches documents against stored queries. To select candidate queries quickly, its default QueryDecomposer splits a registered DisjunctionMaxQuery into one query per disjunct and drops the tie-breaker. When several parts of one query match a document, ScoringMatch and ExplainingMatch merge them by adding their scores. A DisjunctionMaxQuery, however, scores the best disjunct plus tie-breaker times the others, "not the sum of the field scores (as BooleanQuery would give)". So for every registered DisjunctionMaxQuery with a tie-breaker below 1 and every document on which two or more distinct disjuncts of it score above 0, the Monitor reports the sum: (title:apple | body:apple) at tie 0 gets 0.3105659 instead of 0.1798013, the javadoc's albino-elephant ranking becomes a tie, and the tie-breaker has no effect. Which queries match is unchanged. It is in every release since the module was imported (LUCENE-8766, 8.2.0). Keeping a DisjunctionMaxQuery whose tie-breaker is not 1 whole in the decomposer (+5 lines, two decomposer tests updated) fixes it, and the whole monitor module passes with that change.

• Monitor (lucene-monitor, org.apache.lucene.monitor): stores queries and matches incoming documents against them. A matcher chosen per match call decides what is reported: SIMPLE_MATCHER (query ids), ScoringMatch (ids and scores), ExplainingMatch (ids and an Explanation), HighlightsMatch (matching terms).
• QueryDecomposer: splits a registered query into parts that are indexed and run separately, so the presearcher can select only the parts whose terms occur in the document. Each part keeps the registered query's id.
• DisjunctionMaxQuery (a | b)~tie: scores a document with its best disjunct plus tie times the other matching disjuncts (tie in [0, 1]).

1. QueryDecomposer.decompose replaces a DisjunctionMaxQuery by the decompositions of its disjuncts and never reads getTieBreakerMultiplier() (QueryDecomposer.java:46-52).
2. QueryCacheEntry.decompose stores each part under the parent's query id (QueryCacheEntry.java:51-60), and the Monitor runs every part the presearcher selects on its own (Monitor.java:294-299).
3. CandidateMatcher.addMatch merges two matches of one id with resolve() (CandidateMatcher.java:75-85). ScoringMatch.resolve returns match1.getScore() + match2.getScore() (ScoringMatch.java:42-44); ExplainingMatch.resolve builds a "sum of:" explanation (ExplainingMatch.java:44-53).
4. So the reported score is the sum of the matching disjuncts, max + others, instead of max + tie * others (DisjunctionMaxQuery.java:238-244). It is too high by (1 - tie) * others when the tie-breaker is below 1 and two or more distinct disjuncts score above 0; with two equal disjuncts at tie 0 it is doubled.

The sum is right for a BooleanQuery disjunction (it scores the sum of its matching SHOULD clauses), for tie 1, and when only one disjunct scores above 0. A BooleanQuery that the decomposer keeps whole (a MUST or FILTER clause next to other clauses, or minimumShouldMatch > 1) is scored right too. Matching is unchanged: a part is kept only with a score above 0, and the sum is above 0 exactly when some disjunct scores above 0, which is when the whole query does.

Document {title: "apple apple", body: "apple banana cherry date"}, BM25, IndexSearcher on a one-document index vs ScoringMatch.DEFAULT_MATCHER:

The javadoc's example, one batch of two documents, (title:albino | body:albino) (title:elephant | body:elephant) at tie 0: A {albino, albino} and B {albino, elephant}. IndexSearcher: A = 0.31506687, B = 0.3979403 (B ranks first). Monitor: A = 0.082873434 + 0.31506687 = 0.3979403 and B = 0.3979403, a tie.

• Who. lucene-monitor users with the default QueryDecomposer (MonitorConfiguration.java:38) who read scores through ScoringMatch (directly or through ParallelMatcher / PartitionMatcher, which report the same sums) or ExplainingMatch, and register a DisjunctionMaxQuery with tie < 1: on its own, in a BooleanQuery SHOULD clause (or as its only MUST clause), or under a BoostQuery.
• Default vs opt-in. The Monitor configuration and the decomposer are the defaults; lucene-monitor is an optional module, and the matcher is chosen per match call. DisjunctionMaxQuery is built in code or by the XML query parser; the classic, multi-field and standard parsers build BooleanQuery.
• Scale. None needed: one query and one document show it, deterministically, with assertions on and off.
• Effect. Too-high scores for multi-field matches, which can reorder or tie stored queries and documents (the javadoc's albino-elephant ranking is lost). Applications that rank or threshold on Monitor scores see it. The set of matching queries is right; nothing fails or is corrupted, and the values look plausible.
• How likely. Rare: it needs the scoring matchers together with DisjunctionMaxQuery; the one public Monitor integration found (an open Solr pull request) uses constant scores, and no public code combining the two was found. The lack of reports since 2019 is weak evidence, because the wrong values look reasonable.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<0.1798013> but was:<0.3105659>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:577)
       org.junit.Assert.assertEquals(Assert.java:701)
       org.apache.lucene.monitor.TestMonitorDisMaxScore.testDisMaxTieZero(TestMonitorDisMaxScore.java:50)

• Monitor contract. package-info.java:40-45: ScoringMatch.matchWithSimilarity "returns the set of matching queries, with the score that each one records against a Document"; ExplainingMatch is "similar to ScoringMatch, but include the full Explanation". The natural reading is the query's own score; no aggregate of decomposed parts is mentioned.
• DisjunctionMaxQuery contract. DisjunctionMaxQuery.java:29-43: the maximum score "plus a tie breaking increment for any additional matching subqueries ... We want the primary score to be the one associated with the highest boost, not the sum of the field scores (as BooleanQuery would give)", followed by the albino-elephant example that the Monitor erases.
• No sum-of-parts semantic is documented. QueryDecomposer's javadoc says only "Split a disjunction query into its constituent parts, so that they can be indexed and run separately"; CandidateMatcher.resolve says "combine them". No CHANGES or MIGRATE entry discusses Monitor scores of decomposed queries.
• The only test that pins a score value. ConcurrentMatcherTestBase.testMatchesAreDisambiguated says each decomposed BooleanQuery "ends up with the sum of the scores for the 'test' and 'doc' parts" and asserts 1.4874471; the devil's-advocate probe showed that this is IndexSearcher's score for the whole BooleanQuery. The sum was meant to reproduce the query's own score. The only other score assertion, TestSimilarities.testNonStandardSimilarity, compares two similarities on a one-term query, which is not decomposed.
• The split tests. TestQueryDecomposer.testDisjunctionMaxDecomposition and testNestedDisjunctionMaxDecomposition assert that a tie-0.1 DisjunctionMaxQuery is split: its shape, which serves the presearcher. No test asserts its score.
• History. The predecessor library (Luwak) already split DisjunctionMaxQuery but kept the larger score in resolve; the 2019 import (LUCENE-8766) changed resolve to a sum, with no recorded discussion. Each rule is right for one query family and wrong for the other, because the split discards the tie-breaker.

The strongest works-as-designed case (the devil's advocate, the cross-model reviewer, and the finder's earlier reading-only cross-model review with the intended-behaviour lens, which ran no code and judged the bug real): both halves are deliberate and tested. TestQueryDecomposer asserts the split, the import deliberately changed max to sum, resolve's javadoc mentions "two branches of a disjunction", and the decomposer is a public customization point, so a maintainer may say Monitor scores are aggregates of the executed parts and that exact DisjunctionMaxQuery scores are available with a decomposer that keeps it whole. Monitor scores come from a tiny per-batch index anyway.

Why it fails: nothing documents a sum-of-parts semantic, the package javadoc most naturally reads as the query's own score, and the only upstream test that pins a score value pins the whole query's score. DisjunctionMaxQuery's javadoc rejects exactly this value. The split tests check matching shape, not scores, and a workaround is not a contract. Every repro's reference uses the same documents, so the gap is only how the parts are recombined. Verdict: not intended; a defect since the import. At worst upstream answers with a javadoc change.

Two fixes were built and run in a scratch worktree at a9779ef3c193. B changes only the DisjunctionMaxQuery branch of the decomposer and is recommended; A keeps the split for the presearcher and runs the registered query whole, which also fixes the two sibling decomposition bugs.

The finder's one-condition fix with a reworded comment, plus a test update: the two split tests in TestQueryDecomposer use tie 1.0 (where splitting is exact), and a new test asserts that a tie-0.1 DisjunctionMaxQuery stays whole, also inside a BooleanQuery next to a decomposed clause with an exclusion. +5 lines in QueryDecomposer.java, +20/-2 in the test.

if (q instanceof DisjunctionMaxQuery dmq) {
  // The scoring matchers add up the scores of a query's parts, but a DisjunctionMaxQuery
  // scores max + tieBreakerMultiplier * others, which is a sum only for a tie-breaker of 1
  if (dmq.getTieBreakerMultiplier() != 1f) {
    return Collections.singleton(q);
  }
  Set<Query> subqueries = new LinkedHashSet<>();
  for (Query subq : dmq.getDisjuncts()) {
    subqueries.addAll(decompose(subq));
  }
  return subqueries;
}

Trade-offs

• A DisjunctionMaxQuery with tie < 1 becomes one presearcher entry instead of one per disjunct and runs whole whenever it is selected. Matching is unchanged (the module's matching and presearcher tests pass); the cost was not benchmarked. The public entry counts change too: Monitor.getDisjunctCount() and the QueryCacheStats counts drop for such queries.
• Inside a BooleanQuery or under a BoostQuery it is still a part of its own, so the tested pure-SHOULD cases add up right (the nested and albino-elephant cases pass).
• It changes the decomposition that two upstream tests assert at tie 0.1; without the test update exactly those 2 of the module's tests fail.
• It fixes only this bug, not the two sibling decomposition bugs (a FILTER clause scored, repeated sub-queries collapsed).

What the checks validated

Gradle in a scratch worktree at a9779ef3c193, seed DEADBEEF: the whole :lucene:monitor:test with the 3 repro classes added, 35 classes, 201 tests, 0 failures, 1 skipped (a @Nightly test), with assertions on and off; all 11 repro tests that fail on stock pass. :lucene:monitor:check -x test with the fix and the primary test (google-java-format, ecj lint, forbidden APIs): BUILD SUCCESSFUL. The finder's condition alone, without the test update: 200 tests, exactly the 2 split tests fail.

Each QueryCacheEntry also keeps its parent MonitorQuery's query, and Monitor.StandardQueryCollector runs that whole query once per query id when the presearcher selects any of its parts. +17/-3 lines in QueryCacheEntry.java and Monitor.java; written as a sketch.

Trade-offs

• Also fixes the two sibling bugs: their repros fail 3 of 4 each on stock main and pass with this change.
• It changes every matcher, not only the scoring ones: the simple and highlighting matchers also run the whole query.
• getQueriesRun() still counts the selected parts (kept so the upstream count of 20 in ConcurrentMatcherTestBase holds), so it no longer equals the number of queries executed.
• A large disjunction runs whole when one of its parts is selected, every cache entry keeps a reference to its parent's whole query (memory), and each match run keeps a set of the ids already run. Not benchmarked; a design change for maintainers to weigh.

What the checks validated

Gradle with assertions on, the whole :lucene:monitor:test with the 3 repro classes and the 2 sibling repros: 37 classes, 208 tests, 0 failures, 1 skipped. Not run with assertions off or through check.

A note in the package javadoc and on ScoringMatch / ExplainingMatch.

Trade-offs

A legitimate maintainer choice, but the albino-elephant ranking stays broken and the tie-breaker keeps having no effect. Not run.

Combine matches with max + tie * others when they come from a DisjunctionMaxQuery.

Trade-offs

resolve sees only two matches, not which query they came from, so it cannot tell a BooleanQuery's parts from a DisjunctionMaxQuery's without new plumbing. Not run.

A QueryDecomposer subclass whose decompose returns a DisjunctionMaxQuery as a singleton, set with new MonitorConfiguration().setQueryDecomposer(...). No Lucene change.

Trade-offs

Gives IndexSearcher's exact score (the independent reproducer's control and the devil's-advocate probe); every application has to know about it.

Method: bounded-exhaustive translation validation against a reference semantics (the hunt's "semi-formal" tier).

• The hunt's planning probe for this area compared ScoringMatch with IndexSearcher on decomposed queries and gave the first signal; the hunt unit re-ran and reduced it.
• The finder's harness ran six matchers (simple, scoring, explaining, highlighting, parallel, partition) on the stock decomposer, and three of them on six decomposer variants, against IndexSearcher on a one-document index: every depth-1 query (420) on 55 documents, every depth-2 query (7,685) on 19 documents, and 3,000 random depth-3 queries on 34 documents; 6,506,760 checks with assertions on and the same with them off.
• Root attribution with public decomposer subclasses: the variant that keeps a DisjunctionMaxQuery whole when its tie-breaker is not 1 (fix B's rule) was the only single change that removed 272, 2,760 and 3,409 score-mismatch rows in the three tiers, for the scoring and the explaining matcher each; further rows were removed by it and by a sibling variant alike. Other variants explain the other families: the two sibling bugs (a FILTER clause, collapsed repeated parts) and a separately registered minimumShouldMatch bug.
• A Z3 model of the score algebra (19 obligations over the reals) confirmed that the split preserves the score under sum-resolve only for tie 1 or one matching disjunct, and that with tie < 1 and two matching disjuncts that both score above 0 it always differs.
• The finder then wrote the public-API JUnit test, and independent checkers reproduced it.