DrillDownQuery.clone() shares each dimension's builder, so adding a value to one copy changes the other

DrillDownQuery keeps one BooleanQuery.Builder per facet dimension, and add() on a dimension that is already present ORs another value into that builder, as its javadoc documents. clone() hands the source's builders to the copy by reference (DrillDownQuery.java:68, this.dimQueries.addAll(dimQueries)), so add() on an existing dimension of either copy changes what the other copy matches: q restricts color = red, q.clone().add("color", "blue"), and q matches 2 documents instead of 1. Since 9.0 a copy that was already searched hides the leak until its own dimension changes (then 3 documents where 2 are right), and copies that match different documents compare equals() with the same hashCode(). Adding a new dimension to a copy is isolated, which is the only case upstream testClone covers. Lucene never calls clone() itself, so only applications that clone a DrillDownQuery and extend a dimension are hit, silently, on every release from 4.7.0 to 10.5.2 and main. Copying the builders in clone(), and comparing built dimension queries in equals(), fixes it; the whole lucene/facet test suite passes with that change.

• Drill-down: DrillDownQuery narrows a base query (or all documents) to facet values. Each dimension becomes one FILTER clause; the values of one dimension are OR'd: "if you pass the same dimension more than once it is OR'd with the previous constraints on that dimension, and all dimensions are AND'd against each other and the base query" (DrillDownQuery.java:111-115).
• Per-dimension builder: the query keeps one BooleanQuery.Builder per dimension (DrillDownQuery.java:56), adds each value to it as a SHOULD clause, and builds the dimension's query lazily, caching the result per copy until that dimension changes (:57-59, :204-211; the cache dates from 9.0).
• clone() (:139-142) has no javadoc. Object#clone says a copy "should be independent of this object", and upstream TestDrillDownQuery#testClone (:245-255) asserts that a change to the clone does not show up in the source.

1. clone() calls a package-private constructor that does this.dimQueries.addAll(dimQueries) (DrillDownQuery.java:68): a new list holding the same builder objects. The dimension map is copied (:69), and every dimension of the new copy is marked dirty (:71-74).
2. add(dim, ...) on a dimension the copy already has runs dimQueries.get(index).add(subQuery, Occur.SHOULD) (:135): the clause goes into the shared builder. Only the receiving copy is marked dirty (:136). A new dimension gets a new builder in that copy's own list (:128-133), so new dimensions stay isolated.
3. Any copy that builds a dirty dimension, including every fresh clone, reads the shared builder with the other copy's clause in it (:204-211). A copy that was already built keeps its cached query until its own dimension changes again, and then picks up everything in the builder.
4. equals() and hashCode() compare the builder list (:144-156); BooleanQuery.Builder does not override equals, so this is identity: a clone stays equal to its source while they match different documents.

Index: three documents, color = red, blue, green (SortedSetDocValuesFacetField).

The first five rows were run on main with assertions on and off and on 10.5.2 and 9.12.3; the last is an independent reproducer's control on main. On 8.11.2 and older there is no cache: the searched copy changes at once (2, then 3).

• Who is exposed. Applications that call DrillDownQuery#clone() and then add() on either copy for a dimension the source already constrains, while the other copy is still used: a base or template query cloned per request or per facet value, where another value is OR'd into an already selected dimension. Adding a new dimension to a clone is not affected.
• Default vs opt-in. Default codec, IndexWriterConfig and searcher; no index-size prerequisite (the runs used small indexes of 2 to 24 documents, and the shared state lives in the query objects). It needs an explicit clone() of an @lucene.experimental class. Lucene never calls clone() (none of the 11 main-source files that reference DrillDownQuery does), DrillSideways shares the builders internally but never adds to them, and a read-only code search found no DrillDownQuery use in Solr or Elasticsearch. No public report was found in the prior-report searches.
• Silent and one-sided. No exception or log line. The extra matches stay on the affected dimension: the base query, the other dimensions and a DrillSideways filter are never widened, and no document is lost (a randomized check over more than 1,000 searches in 4 runs: stock main with assertions on and off, 10.5.2, and main with the fix).
• Template pattern (executed on main and 10.5.2). A template restricting status = published, cloned per request: one request adds status = draft to its clone, and every later clone of the template returns the draft document too, also through DrillSideways.search, whether or not the template was searched first. Each such add() grows the template's builder by one clause, so with the default limit of 1,024 clauses the 1,024th request that adds a value and every later one fail with IndexSearcher.TooManyClauses, thrown by add(), until the template is rebuilt; a plain clone of the template still works.
• equals() side effect. An application-level result cache keyed on the DrillDownQuery could serve one copy's results for the other, since they compare equal. Lucene's own LRUQueryCache is not affected: it keys on the rewritten BooleanQuery (executed).
• Not assessed. Several threads cloning and adding to one shared template would also race on the builder's unsynchronized clause list (code reading only).

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: original (color=red) after adding color=blue to its clone expected:<1> but was:<2>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:647)
       org.apache.lucene.facet.TestDrillDownQueryCloneIsolation.testAddToCloneDoesNotChangeOriginal(TestDrillDownQueryCloneIsolation.java:48)

• Contract. add(String, String...) (DrillDownQuery.java:111-115): "if you pass the same dimension more than once it is OR'd with the previous constraints on that dimension", on the copy you call it on. Object#clone: "By convention, the object returned by this method should be independent of this object ... this means copying any mutable objects that comprise the internal 'deep structure'". The builders are such internal state: add() creates them; the caller never supplies them. Query#equals (Query.java:99-101): "Typically a query will be equal to another only if ... its document-filtering properties are identical".
• Tests. TestDrillDownQuery#testClone (:245-255), added with clone() in LUCENE-4750 (4.2.0): q.add("a"), clone.add("b"), then assertFalse("query wasn't cloned: ...", ...). It adds a new dimension, the one isolated case, so it passes; it is the only upstream test that calls DrillDownQuery#clone.
• History. The author of LUCENE-4750 wrote: "Also implemented clone() (there's a test showing what would happen if we don't)". Until 4.6.1 adding the same dimension again threw or added a clause to that copy only, so the shallow copy was harmless. LUCENE-5339 (4.7.0) made it OR the value in place into the shared per-dimension query; nothing in that change discusses clone(). LUCENE-6570 (5.3.0) kept the sharing when it moved to builders; in its review @jpountz wrote, about queries in general, that clone() should eventually be documented to "return an independant instance. So there are two options: either deep cloning or shallow cloning and be immutable". DrillDownQuery is neither.
• Coherence. Since 9.0 (LUCENE-9956) whether a copy sees the other's value depends on whether it was searched first, and copies that match 1 and 2 documents are equals(). No design produces that on purpose.

The strongest "intended" case: clone() has no javadoc; the class is @lucene.experimental; Java's List and Map clones are shallow, and in LUCENE-6369 ("Make queries more defensive and clone deeply", Won't Fix) a committer defended shallow query clones ("clone() did exactly what I wanted previously... a shallow clone. It's also more in line with Java cloning of things like List, Map"); DrillDownQuery is a known mutable query (#8134), so clone-then-mutate could be called a pattern to avoid.

Why it fails: a shallow List clone never lets clone.add(x) change the original, and here clone.add(dim, ...) does, because the shared objects are builders that add() created inside the query; LUCENE-6369 was about sub-queries the caller supplied. The author of clone() added it so that a copy is independent, with a test that says so. add() documents OR-ing into an existing dimension, not into other copies. @lucene.experimental is about API stability, not wrong results, and #8134 is about mutating a query after it was cached; it never mentions clones. Verdict: a defect (adjudication: confirmed, high; the independent reproduction and the intended-behaviour check real; the other-model-family intended-lens review rated the intended case moderate and rejected it). Low severity: the call pattern is rare.

Each copy then owns its builders, so add() reaches only the copy it is called on (new dimensions were already isolated), and equality compares the built dimension queries by content, per dimension position, as DrillSidewaysQuery does for its built drillDownQueries array (not full match-equivalence: the same dimensions added in a different order still compare unequal). The clone() half alone fixes every wrong match, including equal copies that match different documents, and is a credible minimal fix; the equals()/hashCode() half is a visible behaviour change (identical queries become equal) and can be proposed separately. Making DrillDownQuery immutable (#8134) would also remove the bug. Workaround until a fix ships: build a fresh DrillDownQuery per variant instead of clone() followed by add() on an existing dimension, and keep access restrictions in the base query or the DrillSideways filter.

clone() builds each dimension once and copies its clauses into a new BooleanQuery.Builder; hashCode() and equalsTo() compare baseQuery, drillDownDims and getDrillDownQueries() instead of the builder list. Two imports, and the stale constructor javadoc "Used by clone() and DrillSideways" (only clone() calls it) is corrected. +20/-4 in DrillDownQuery.java.

  public DrillDownQuery clone() {
    // add() on an existing dimension appends to that dimension's builder in place, so the copy
    // needs its own builders; sharing them would leak the new clause into the other copy.
    List<BooleanQuery.Builder> copies = new ArrayList<>(dimQueries.size());
    for (BooleanQuery.Builder dimQuery : dimQueries) {
      BooleanQuery.Builder copy = new BooleanQuery.Builder();
      for (BooleanClause clause : dimQuery.build()) {
        copy.add(clause);
      }
      copies.add(copy);
    }
    return new DrillDownQuery(config, baseQuery, copies, drillDownDims);
  }
  // equalsTo: Objects.equals(baseQuery, ...) && drillDownDims.equals(...)
  //   && Arrays.equals(getDrillDownQueries(), other.getDrillDownQueries()); hashCode alike

Trade-offs

• clone() costs O(total clauses) instead of O(dimensions).
• equals()/hashCode() now build dirty dimensions first through getDrillDownQueries(), which writes the query's own cache (builtDimQueries, dirtyDimQueryIndex): they are no longer read-only and race on that cache when run concurrently with add() or each other, as rewrite and toString already do (no thread-safety guarantee existed).
• Content equality is a behaviour change: a fresh clone equals its source, the two stop being equal once one changes, and two separately built identical queries become equal (they are unequal today; #11098 noted that in passing as a benign cache miss). Including drillDownDims keeps queries with different dimension names unequal. It is not full match-equivalence: the comparison is per dimension position, so the same dimensions added in a different order, or the same subqueries under different dimension names, compare unequal.
• hashCode() now also changes after add() on an existing dimension (today only a new dimension changes it), so a query used as a hash key and then extended is no longer found under that key.
• Also in the clone-only option: the copy replays each clause through BooleanQuery.Builder.add, which checks the current clause limit, so if the application lowered the limit below a dimension's clause count after building the query, clone() now throws TooManyClauses (the stock reference copy never does). Only clauses are copied, not minimumNumberShouldMatch, which DrillDownQuery never sets. (Code reading.)

What the checks validated

• Scratch worktree of a9779ef3c193, gradle, JDK 25: the new test fails 4 of 4 on stock (assertions on and off) and passes with the fix; with the fix the new test, an optional 2-test equality class (fails on stock), TestDrillDownQuery (13) and TestDrillSideways (14): 33 tests, 0 failures, assertions on and off; the whole :lucene:facet:test, 41 suites and 312 tests, 0 failures, assertions on (7 skipped) and off (8 skipped); :lucene:facet:check -x test (google-java-format, ecj lint, forbidden APIs) passes.
• Standalone runner with the fix shadowed: the new test (-ea, -da), the finder's test (2 of 2), the independent reproducer's test (7 of 7) and the security probe (7 of 7, including its template, DrillSideways and TooManyClauses cases) pass.

The same clone() and javadoc change, with equals()/hashCode() untouched (+13/-2).

Trade-offs

Fixes every wrong match, and copies that differ are no longer equal. Keeps identity equality: a fresh, unchanged clone is no longer equal to its source (it is today), and separately built identical queries stay unequal; only a cache keyed on the query notices. Identity equality on its own is defensible; equal copies that match different documents are not, and this option already removes those. It shares the clone-replay caveats of the first option.

What the checks validated

Gradle, assertions on: the new test, TestDrillDownQuery and TestDrillSideways, 31 tests, 0 failures; the new test passes through the standalone runner. The optional equality class fails with it, as expected.

Copy the builders in the 4-argument constructor (only clone() calls it), and optionally in the DrillSideways constructor (DrillDownQuery.java:78-91, addAll at :84).

Trade-offs

Same effect as the clone() change; the DrillSideways copy only hardens an internal query that is never mutated, at the cost of copying clauses on every DrillSideways.search(query, filter, ...). Not run.

An immutable query plus a separate builder, as #8134 asks for the remaining mutable queries.

Trade-offs

Removes this bug and the caching concern of #8134 together, but changes the API of an @lucene.experimental class; a larger discussion. Not run.

Instead of clone() followed by add() on an existing dimension, build each variant from its list of values (adding a new dimension to a clone is safe). Keep access restrictions in the base query or the DrillSideways filter.

Trade-offs

Application-side only; not a fix.

Method: code reading (the hunt's "non-formal" tier), a hunt unit (facets: taxonomy, SSDV and DrillSideways), 2026-10-26, stock main jars.

• The finder was modelling the drill-down semantics of DrillDownQuery and DrillSideways for a bounded-exhaustive harness and read both classes. It noticed that the constructor clone() uses copies the builder references while add() mutates an existing dimension's builder in place.
• It wrote a 2-test public-API JUnit test (TestDrillDownQueryCloneShares), which failed on main with assertions on and off and on releases back to 7.7.3. The harness itself did not find it.
• Then independent AI tools reproduced, reviewed and judged it (see the checks), and the history step found the introduction in 4.7.0.