LongRange/DoubleRange#getQuery hides its fast-match query from QueryVisitor, so maxClauseCount never counts it

LongRange#getQuery(fastMatchQuery, valuesSource) and its DoubleRange and multi-valued twins return a query that only checks documents its fast-match query matches; the javadoc calls fastMatchQuery "a query to use as a filter". The query runs the fast-match query as its two-phase approximation, but its visit is just visitor.visitLeaf(this). IndexSearcher enforces maxClauseCount by walking the rewritten query with a QueryVisitor, so it counts the range query as one clause and never sees the fast-match query, not even on its own. With the default limit of 1024, a range query whose fast-match query holds 1,200 term clauses is searched without error, while the same clauses as a FILTER clause, searched alone or passed to IndexSearcher#rewrite, are rejected; range facet counting with the same fast-match query rejects it too. QueryVisitor.termCollector and RamUsageEstimator.sizeOf (an installed query cache's RAM estimate) also miss it. No wrong hits were seen: with the limit raised, the hits are those of the FILTER form. Every release since 9.0.0 is affected; the fix is to visit the fast-match query with a FILTER sub-visitor.

1. The leaf-only visit. ValueSourceQuery.visit and MultiValueSourceQuery.visit are visitor.visitLeaf(this); and nothing else (LongRange.java:137-140 and :236-239, DoubleRange.java:150-153 and :249-252). fastMatchQuery is read by equals, hashCode, rewrite and createWeight, but not by visit.
2. It stays in the rewritten tree. rewrite rewrites the fast-match query and, if it changed, returns a new range query that holds the rewritten one (LongRange.java:142-151, :241-250; DoubleRange.java:155-164, :254-263).
3. The check sees only what visit shows. IndexSearcher.rewrite(Query) rewrites to a fixpoint and calls query.visit(getNumClausesCheckVisitor()) (IndexSearcher.java:871-880); that visitor counts one clause per visitLeaf, consumeTerms or consumeTermsMatching call (:891-932; it tests before it increments, so 1,025 clauses pass, the known off-by-one #10339). The range query adds one visitLeaf.
4. It runs anyway. createWeight calls searcher.createWeight(fastMatchQuery, ScoreMode.COMPLETE_NO_SCORES, 1f) (LongRange.java:159, :258; DoubleRange.java:172, :271) and uses its iterator as the approximation. IndexSearcher.createWeight assumes a rewritten query and checks nothing (IndexSearcher.java:970-976); that part is normal.
5. Only per-builder caps remain. BooleanQuery.Builder.add refuses a 1025th clause in one BooleanQuery (BooleanQuery.java:74-86), but the total of a tree of such BooleanQueries is never counted on this path.
6. Facet counting differs. FacetCountsWithFilterQuery.createIterator runs searcher.rewrite(fastMatchQuery) first (FacetCountsWithFilterQuery.java:69-74), so range facet counts reject the fast-match query that the query path accepts.

Default IndexSearcher, maxClauseCount 1024, fast-match query = two MUST BooleanQueries of 600 SHOULD term clauses. Clauses a QueryVisitor counts: fast-match query alone 1,200, the range query 1, BooleanQuery(MUST range, FILTER fastMatch) 1,201. The FILTER form, the fast-match query alone and searcher.rewrite(fastMatch) throw; LongRange/DoubleRange#getQuery with single- and multi-valued sources run, also inside a DrillDownQuery and through DrillSideways. With the limit raised, hits are the same as for the FILTER form. RamUsageEstimator.sizeOf(rangeQuery, 32) is 32 bytes with a 1-term or the 1,200-leaf fast-match query; the fast-match query alone is 211,232 bytes.

• Who. Users of the four getQuery(fastMatchQuery, ...) overloads (opt-in, @lucene.experimental). The facet demo uses one to drill down on a distance range: DrillDownQuery.add("field", range.getQuery(boundingBox, vs)), searched through DrillSideways.
• When. A fast-match query is usually a small filter (the demo's is a bounding box), so the limit only matters for unusually large ones; the visitor effects matter when an application, a visitor-based highlighter (inferred from the code, not run) or an installed query cache (caching is off by default) inspects such a query.
• Effect. An application that relies on maxClauseCount to bound the queries it builds gets no limit on clauses inside a fast-match query; term collection under-reports, and so does an installed query cache's RAM estimate; the query and the facet counting path disagree on the same fast-match query.
• Not affected. No wrong hits were seen: with the limit raised, the hits are those of the FILTER form (scores were not compared). Each BooleanQuery inside the fast-match query is still capped when built, and the work stays proportional to the query the application built.
• Versions. Every release since 9.0.0 (multi-valued overloads since 9.1.0), 10.6.0, branch_11x and main.

The clause check runs in IndexSearcher.rewrite, before any field is read, and for this BooleanQuery/TermQuery shape the rewrite does not depend on the index, so the index content does not matter here. The test nests two BooleanQuery disjunctions because one BooleanQuery cannot be built with more than 1024 clauses and the check throws only past 1,025 counted clauses; 1,200 is well clear of both. The test uses the single-valued LongRange overload; DoubleRange and both multi-valued overloads have the same visit body and the same fix. Deterministic: 10 of 10 iterations of a second seed fail the same way.

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

# gradle, stock 645d4fe14a20, -Ptests.seed=DEADBEEF -Ptests.asserts=true (stack trimmed); -Ptests.asserts=false identical
> Task :lucene:facet:test FAILED

TestRangeQueryFastMatchClauseLimit > testFastMatchQueryCountsTowardsClauseLimit FAILED
    junit.framework.AssertionFailedError: Expected exception TooManyNestedClauses but no exception was thrown
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:9B02CD11DC2AA721]:0)
        at org.apache.lucene.tests.util.LuceneTestCaseParent.expectThrows(LuceneTestCaseParent.java:1432)
        at org.apache.lucene.facet.range.TestRangeQueryFastMatchClauseLimit.testFastMatchQueryCountsTowardsClauseLimit(TestRangeQueryFastMatchClauseLimit.java:55)

# standalone runner: tests_run=1 failures=1 on the 645d4fe14a20 jars and the 10.6.0 release jars, -ea and -da

# QueryVisitor leaf counts (an independent reproducer's test): fast-match query 1200, range query 1,
# BooleanQuery(MUST range, FILTER fastMatch) 1201; sizeOf(range query, 32) = 32 bytes, fast-match query alone 211232

• Query.java:88-93: "Recurse through the query tree, visiting any child queries."
• IndexSearcher.java:1193-1199: TooManyNestedClauses is thrown "when a client attempts to execute a Query that has more than getMaxClauseCount() total clauses cumulatively in all of its children".
• MIGRATE.md (LUCENE-8811): "IndexSearcher now performs max clause count checks on all types of queries (including BooleanQueries)." CHANGES 9.0.0: the checks "are now implemented using a QueryVisitor and apply to all queries, rather than only booleans". In #9855, Adrien Grand liked that it "removes ways to by-pass the maximum clause count by splitting boolean queries into multiple sub boolean queries".
• getQuery javadoc: the query "will check all documents that match the provided match query"; fastMatchQuery is "a query to use as a filter". A TermQuery fast-match query cuts the hits from 20 to 1 in a verifier's probe.
• CHANGES 8.6.0, Bug Fixes: "LUCENE-8849: DocValuesRewriteMethod.visit wasn't visiting its embedded query"; its patch chose FILTER for the embedded query "as the rewritten query is really a filter" (Michele Palmia on #9892), as the fix here does, but it only calls visitor.getSubVisitor(BooleanClause.Occur.FILTER, query) and drops the result, so that query is still not visited on main (DocValuesRewriteMethod.java:73-77; the hunt's LFV-038, open PR #13140).
• In the QueryVisitor PR (LUCENE-3041), its author Alan Woodward said "all compound queries should pull a sub visitor and call visit on each of their sub queries with it. And visitLeaf is for queries that don't match on terms." In #14759 they called QueryVisitor "a query introspection API". Neither review that wrote these visit bodies (#581, #543) discusses their visit or the fast-match query (#543's only comments on these files are about keeping the single-valued getQuery overload).
• FacetCountsWithFilterQuery.java:74 rewrites, and so checks, the same fast-match query; no upstream test asserts that it is hidden, and TestRangeFacetCounts passes with the fix.

Strongest case for "intended" (built by a verifier): the fast-match query is an execution detail (LUCENE-6648 described getQuery as "a fast approximation and a slow confirmation"); other wrappers such as DrillSidewaysQuery, the block-join queries and CompositeVerifyQuery are opaque leaves too; Alan Woodward said in LUCENE-8811 that the visitor-based count "wouldn't be exact"; open PR #16175 calls IndexOrDocValuesQuery's doc-values variant "an implementation detail"; the classes are experimental.

Why it fails: IndexOrDocValuesQuery's two variants match the same documents, so visiting both double-counts; the fast-match query decides which documents can match, exactly like a FILTER clause, which is counted. LUCENE-8849 recorded this kind of gap as a bug, the API's author calls it an introspection API, and facet counting already checks the same query. The other opaque leaves are unreported, not endorsed: the verifier found no CHANGES, MIGRATE, javadoc or won't-fix text that accepts hiding an executed sub-query.

An independent fact check by another model family (OpenAI GPT-5.6) still rates the "intended" case moderate: the API is experimental, the application builds the filter, and the fix makes some accepted queries throw. It is a small, compatibility-sensitive report.

One option was built and validated; the others are listed with their trade-offs.

In ValueSourceQuery and MultiValueSourceQuery of LongRange.java and DoubleRange.java, visit keeps visitor.visitLeaf(this) and, when fastMatchQuery != null, calls fastMatchQuery.visit(visitor.getSubVisitor(BooleanClause.Occur.FILTER, this)) (+7 lines per file, one import). The count becomes 1,201, the same as BooleanQuery(MUST range, FILTER fastMatch); FILTER is the occur LUCENE-8849 chose; unlike that patch, this one passes the sub-visitor on.

@Override
public void visit(QueryVisitor visitor) {
  visitor.visitLeaf(this);
  if (fastMatchQuery != null) {
    fastMatchQuery.visit(visitor.getSubVisitor(BooleanClause.Occur.FILTER, this));
  }
}

Trade-offs

• Behaviour change. Range queries with a fast-match query over the limit start to throw TooManyNestedClauses; maintainers may want it on main only, with a CHANGES entry.
• Visitors see more. Term collectors (and, from the code, highlighters and the monitor module's query analysis) start to see the fast-match terms, and sizeOf includes the fast-match query, as they already do for a FILTER clause; a visitor that ignores filters can skip it through getSubVisitor(FILTER, ...).

What the checks validated

Applied to a scratch worktree of 645d4fe14a20 and run through gradle with OpenJDK 25.0.3, seed DEADBEEF (2026-10-31):

• stock: the minimal test fails with assertions on and off;
• with the fix: the minimal test passes with assertions on and off;
• TestRangeFacetCounts: 22 tests, 0 failures;
• the whole facet module: 40 classes (39 upstream and the repro), 307 tests, 0 failures, 7 skipped, including TestDrillDownQuery and TestDrillSideways;
• the demo's facet examples (9 classes, 19 tests, including TestDistanceFacetsExample and TestRangeFacetsExample): 0 failures;
• facet checkGoogleJavaFormat, ecjLintMain and forbiddenApisMain pass.

The hunt's version of the same change passed its own 4 tests, an independent reproducer's 8 tests and a verifier's 5 probes.

visitLeaf(this) only when there is no fast-match query; otherwise visit the fast-match query as a FILTER child.

Trade-offs

Counts 1,200 instead of 1,201 and hides the range query's own doc-values condition from visitors that look for leaves, so it is less faithful than the recommended option.

Call searcher.rewrite(fastMatchQuery) before searcher.createWeight(...), as facet counting does.

Trade-offs

Checks the fast-match query only on its own, not together with the rest of the query; leaves term collection, highlighting and sizeOf blind; re-runs a rewrite on an already rewritten query. Calling createWeight on a rewritten query is not itself defective.

State in the getQuery javadoc that the fast-match query is not counted.

Trade-offs

Contradicts the Query#visit and TooManyNestedClauses contracts the query inherits.

Method: semi-formal. The hunt unit looked for queries that execute an embedded query but hide it from QueryVisitor. Its harness ran the stock jars over 16 wrapper sites x primary leaves {1, 2, 4} x hidden leaves {1..10} x copies {1, 2, 3} = 1,440 checks at maxClauseCount 8, with assertions on and off, against a reference model that counts the clauses each query really executes.

• Each range site under-counted in 42 of its 90 checks, and in the single-wrapper phase it was never rejected (fast-match query up to 16 leaves, where the model rejects from 9).
• The BooleanQuery, ConstantScoreQuery and DisjunctionMaxQuery controls had 0 mismatches in 270, and the oracle flagged the known IndexOrDocValuesQuery over-count (52 cases), so it is not vacuous.
• A bytecode scan with the JDK ClassFile API listed ValueSourceQuery/MultiValueSourceQuery.fastMatchQuery as read by rewrite and createWeight but never by visit.
• The finding was reduced to a public-API JUnit, then checked by an independent reproducer, reviews by another model family (OpenAI GPT-5.6), a devil's-advocate verifier and an adjudication.