CompositeVerifyQuery reports itself cacheable without asking its index query, so a query cache keeps old matches after an in-place doc-values update

CompositeVerifyQuery(Query indexQuery, ShapeValuesPredicate predicate) (spatial-extras, public constructor, @lucene.experimental) finds candidates with its index query and verifies each one with the shape predicate. Its Weight iterates the index query's scorer as the approximation of every match, but its isCacheable asks only the predicate (return predicateValueSource.isCacheable(ctx);, CompositeVerifyQuery.java:113-116 on main a9779ef3c193). LRUQueryCache trusts Weight#isCacheable and keys entries on the segment's core cache key, which a doc-values update may leave unchanged (LeafReader allows it, and in the repro it stays the same). So when the index query reads a doc-values field that is updated in place (IndexWriter#updateNumericDocValue or updateBinaryDocValue), the entry cached before the update keeps being served after the reopen: [0, 1, 2] instead of [1, 2, 4] for an "in the area AND open" index query, [0, 1, 2] instead of [1, 2] for a bare newSlowExactQuery, 5025 instead of 5024 hits with the release-default cache settings. The index query on its own is correctly uncacheable on that segment. On 7.2.0-10.5.2 and 10.6.0 (released 2026-10-29) a plain IndexSearcher reproduces it with zero configuration; main has had no default cache since #14187 (unreleased), so there it needs an installed cache. CompositeSpatialStrategy's own queries (prefix-tree index queries) are not affected. Introduced by LUCENE-8042 (276e317e942), which replaced a never-cacheable "TODO delegate to PredicateValueSource?" with the predicate check and left out the index-query Weight built in the same method. The fix ANDs indexQueryWeight.isCacheable(ctx) in.

• CompositeVerifyQuery: "A Query that considers an 'indexQuery' to have approximate results, and a follow-on ShapeValuesSource is called to verify each hit" (CompositeVerifyQuery.java:33-35; the field comment at :41 says "approximation (matches more than needed)"). Public constructor (:44), @lucene.experimental (:37). CompositeSpatialStrategy builds it around a prefix-tree (RPT) query; applications can build it around any query.
• Query cache: LRUQueryCache stores the matching documents of a query per segment, keyed on the query and the segment's core cache key. It asks Weight#isCacheable(leaf) before it reads or writes an entry (LRUQueryCache.java:816-834 and :903-921).
• In-place doc-values update: IndexWriter#updateNumericDocValue and updateBinaryDocValue change a doc-values-only field without rewriting the segment. The reopened segment may keep its core key: "Two readers that have the same data but different sets of deleted documents or doc values updates may be considered equal" (LeafReader.java:66-70); the test asserts it does. That is why a query that reads an updated doc-values field must say it is not cacheable: "Updated doc values fields are not suitable for caching" (SegmentCacheable.java:30-32).

1. createWeight builds the index query's Weight once (CompositeVerifyQuery.java:95-97) and feeds its scorer's iterator to the predicate's two-phase iterator (:102-108): every match is an index-query match that the predicate confirmed.
2. isCacheable returns predicateValueSource.isCacheable(ctx) and nothing else (:113-116).
3. A doc-values index query such as NumericDocValuesField.newSlowExactQuery("open", 1) reports DocValues.isCacheable(ctx, "open") (SortedNumericDocValuesRangeQuery.java:119-121), false once the field was updated in that segment (DocValues.java:339-346); a small BooleanQuery ANDs its clauses' answers (BooleanWeight.java:272-285). The composite's Weight never asks it.
4. After the update and reopen, the cache asks the composite's Weight, gets true, finds the old entry under the unchanged core key and returns it. The index query's Weight is not consulted, because the outer entry is served before the composite's scorer is built.

Six shops at (i, i), one segment, indexed with a CompositeSpatialStrategy; shops 0-2 open. CompositeVerifyQuery(BooleanQuery(FILTER rpt Intersects area, FILTER open == 1), exact shape Intersects area) returns [0, 1, 2]. After updateNumericDocValue(id:0, open, 0), updateNumericDocValue(id:4, open, 1) and openIfChanged: uncached [1, 2, 4], cached [0, 1, 2]: a closed shop returned, an open one missing. The same flag as a sibling clause outside the composite is correct through the same cache. With the bare index query newSlowExactQuery("v", 1) and doc 0 changed from v=1 to v=2: cached [0, 1, 2] instead of [1, 2]. With the release-default cache settings (LRUQueryCache(1000, 32 MB), which is the releases' min(32 MB, heap/20) for heaps of 640 MB or more, and UsageTrackingQueryCachingPolicy; 10,050 documents, query counted 10 times): 5025 instead of 5024. The composite's isCacheable is true on the updated segment while the index query's is false.

• Needs: an index query that reads a doc-values field, an in-place update of that field, the composite cached on that segment before the update, and a cache that survives the reopen. The composite must run without scores, as a count, a filter clause or a no-score collector does: only then does IndexSearcher#createWeight wrap it in the cache (IndexSearcher.java:976-982).
• Affected index queries (model-based harness, 14 stale results): newSlowExactQuery, newSlowRangeQuery, a BooleanQuery with such a FILTER clause, FieldExistsQuery on a doc-values field, SerializedDVStrategy.makeQuery after a binary doc-values update.
• Not affected, by the code: CompositeSpatialStrategy.makeQuery (Intersects builds an IntersectsRPTVerifyQuery, CompositeSpatialStrategy.java:122-134; the other operations wrap an RPT query, :154-155, whose Weight is always cacheable, AbstractPrefixTreeQuery.java:107-108, or a TermQuery for a point shape on a points-only grid, also always cacheable, RecursivePrefixTreeStrategy.java:185-187, 216-229, TermQuery.java:192-194).
• No mismatch observed in the harness (its 9 index-query kinds x 9 index operations) for TermQuery, IntPoint range and kNN index queries, an update of the predicate's own shape field, deletes, new segments and updateDocument.
• The stale entry ends when the segment is merged into a new one, the entry is evicted, the application clears the cache (LRUQueryCache.java:458), or searches switch to another cache; LRUQueryCache#close keeps the entries and only stops an optional cleanup thread (:264-275). The duration in a running application was not measured.

• Intended public use. LUCENE-5579 (#6641), which added the class, "Pulled out the inner Query instances to live in the 'composite' package, so that they might be used by users who want to build with these constructs", after asking how users "can put other query/filters in-between RPT and the SerializedDVStrategy". An index query that ANDs the prefix-tree query with a doc-values flag fits that description.
• 7.2.0 to 10.5.2 and 10.6.0: the default configuration. IndexSearcher has a JVM-wide default LRUQueryCache(1000, min(32 MB, heap/20)) with UsageTrackingQueryCachingPolicy (10.5.2 IndexSearcher.java:83-99). It caches only segments of at least 10,000 documents that are large relative to the index (LRUQueryCache.java:251-253, 278-296), and a query only after repeated use. One 10,050-document segment and the query counted 10 times reproduce it with no cache code at all on 7.2.0, 8.11.4, 9.12.3, 10.5.2 and branch_10_6 (5025 instead of 5024); an independent program with 12,000 documents gives 6000 instead of 5999 on 10.5.2 and branch_10_6.
• main: opt-in. There is no default cache since #14187 (IndexSearcher.java:84, not yet released); MIGRATE.md:227-236 shows how to turn it back on.
• Effect. Silent wrong hit lists and counts for the documents whose field changed, in both directions; no exception. With the shared default cache, any searcher in the JVM that runs the same query without scores on the same segment core can get the stale entry.
• Scale. Ordinary: six documents with a cache that accepts every segment; one segment of about 10,000 documents with the default cache (LRUQueryCache.java:251-253).
• How likely: rare. The only in-tree producer, CompositeSpatialStrategy, passes prefix-tree queries, which cannot change in place; no Lucene query parser builds a CompositeVerifyQuery; no spatial-extras test touches caching; no outside report was found in the documented searches.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<0> but was:<1>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:647)
       org.junit.Assert.assertEquals(Assert.java:633)
       org.apache.lucene.spatial.composite.TestCompositeVerifyQueryCacheability.testCachedCountAfterDocValuesUpdate(TestCompositeVerifyQueryCacheability.java:67)

• Contract. SegmentCacheable.java:30-32: "Objects that depend on doc values should return DocValues#isCacheable(LeafReaderContext, String...), which will check to see if the doc values fields have been updated. Updated doc values fields are not suitable for caching." QueryCache.java:28-30: the caching wrapper "will only be equivalent if scores are not needed"; the repro collects and counts without scores.
• Upstream test. TestSegmentCacheables.java:84-92: "after field3 is updated, all composites referring to it should be uncacheable". TestLRUQueryCache.java:2222 (testDocValuesUpdatesDontBreakCache) tests the cache against doc-values updates with a test query whose Weight returns DocValues.isCacheable (DVCacheQuery, :2165, :2213): after the update that segment is no longer cached (:2271-2284).
• Precedent in core and queries. FilterWeight.java:47-50 (return in.isCacheable(ctx)), ConstantScoreQuery.java:192-195 (innerWeight.isCacheable(ctx)), BooleanWeight.java:272-285 and FunctionScoreQuery.java:279-282 (inner.isCacheable(ctx) && valueSource.isCacheable(ctx)). LUCENE-8042 gave FunctionScoreQuery a value-source-only answer too; LUCENE-7736 (#8787; 2a4dd499bbd on master and 03afeb7766a on the 7.x line, both committed 2017-11-15, in 7.2.0) ANDed its inner Weight in: a precedent for the fix.
• History. LUCENE-8017 (a886a001a4c) made this Weight never cacheable: return null; // TODO delegate to PredicateValueSource?. LUCENE-8042 (276e317e942, by romseygeek, +1 by rmuir, 107 files, 7.2.0) resolved the TODO by delegating to the predicate only; the indexQueryWeight was already in the same method. LUCENE-8017 had already made ConstantScoreQuery, FilterWeight and BooleanWeight delegate to their inner Weights' cache helpers, and LUCENE-8042 kept that delegation in isCacheable. No comment on #9065 or #9090 mentions CompositeVerifyQuery or its index query.
• Docs. No javadoc, package doc, CHANGES or MIGRATE entry says the index query must be segment-immutable. @lucene.experimental is about API stability, not correctness; the sibling IntersectsRPTVerifyQuery is @lucene.internal.

The intended-behaviour checker and a reviewer from another model family (OpenAI GPT-5.6) built the strongest case: (a) the composite package was built for RPT plus serialized shapes, and the only in-tree producer passes an RPT postings query, for which asking the predicate only is exactly right; (b) the sibling IntersectsRPTVerifyQuery uses the same predicate-only rule (IntersectsRPTVerifyQuery.java:157-158), and IndexOrDocValuesQuery#isCacheable also asks only one sub-query (IndexOrDocValuesQuery.java:211-214); (c) the class is @lucene.experimental; (d) a user can put the doc-values filter outside the composite as a sibling clause; (e) main has no default cache.

Why it fails: (a) convention is not a contract; the constructor is public, accepts any Query, and LUCENE-5579 contemplated users putting other filters between RPT and the serialized shapes. (b) IntersectsRPTVerifyQuery builds its approximation internally from prefix-tree terms, so predicate-only is correct there; IndexOrDocValuesQuery relies on its documented precondition "Both provided queries must match the same documents" (:61), and the "delegate to the indexQuery" remark on #9065 was about that query; here the two parts are different conditions. (c) Experimental allows API changes, not wrong results. (d) A workaround does not make the wrapping illegal, and nothing tells users to use it. (e) The cache is public, MIGRATE.md shows how to re-enable it, and it is the default in every release since 7.2.0 and on the 10.6 branch. Verdict: not intended: the independent reproducer rated the intended case weak, the second cross-model review moderate and rejected it, the devil's advocate "high that it is not intended".

One fix was built and validated; two alternatives were not built.

A one-line change in CompositeVerifyQuery.createWeight's anonymous Weight (1 file, +1/-1). It is what FunctionScoreQuery does for its inner query.

@Override
public boolean isCacheable(LeafReaderContext ctx) {
  return indexQueryWeight.isCacheable(ctx) && predicateValueSource.isCacheable(ctx);
}

Trade-offs

• On a segment where a field the index query reads was updated in place, the composite is no longer cached until that segment is merged away. The index query on its own is already treated that way, so no correct result is lost; caching is lost, though, whenever the index query is not cacheable, for any reason (below).
• The in-tree path is unchanged: prefix-tree query Weights are always cacheable (AbstractPrefixTreeQuery.java:107-108; so is the TermQuery built for a point on a points-only grid, TermQuery.java:192-194), and the control test shows CompositeSpatialStrategy's composite still served from the cache after an unrelated doc-values update.
• An index query that is not cacheable for another reason (for example a BooleanQuery with more than 16 clauses, BooleanWeight.java:274-280) now also keeps the composite out of the cache: correct, but a change in what gets cached.
• One extra isCacheable call, on the index query's Weight, per leaf cacheability check. A "Bug Fixes" CHANGES line would be usual; none is drafted.

What the checks validated

• Scratch worktree of a9779ef3c193, gradle: the new test fails 4 of 5 on the stock tree and passes 5 of 5 with the fix, with assertions on and off; the whole lucene/spatial-extras module (27 suites, among them TestCompositeStrategy, TestSerializedStrategy and TestQueryEqualsHashCode; 122 tests, 0 failures, 5 skipped, 4 of them nightly-only) passes with assertions on and off; :lucene:spatial-extras:check -x test (format, ecjLint, forbiddenApis) passes.
• Standalone runner with the fix shadowed in: the new test 5 of 5 (-ea, -da); the plain-defaults program on the 10.5.2 jars prints default searcher count=5024, uncached count=5024.
• Earlier, by the hunt: the finder's 3 tests 3 of 3, the independent reproducer's 3 of 3, the model-based harness 0 mismatches and 0 property violations, upstream TestCompositeStrategy and TestQueryEqualsHashCode (5 seeds, together with the visit fix of LFV-951), and the history probe on the introducing commit 6e4f9a62e7c.
• Not run: nightly tests, a benchmark.

A javadoc note on the class or its constructor.

Trade-offs

Leaves the trap for anyone who misses the note, and documents an exception to the SegmentCacheable contract instead of following it. Not built.

Return false, as LUCENE-8017 did.

Trade-offs

Correct, but it gives up caching on the in-tree prefix-tree path, where the current answer is right. Not built.

Method: semi-formal (the hunt's hunt unit for CompositeVerifyQuery's cache and visitor contracts, 2026-10-28, main a9779ef3c193).

• Lead. A planning probe from a cross-model ideas pack on committer contracts showed the wrapped query returning [0, 1, 2] where the uncached search returns [1, 2]; the finder re-read its outputs (a planning-stage reviewer had re-run it) and reduced it to a JUnit.
• Model-based harness. Reference semantics written from the class javadoc (live documents matched by the index query AND the predicate in the current state), compared with the cached search, the uncached search and the structural property "the composite is cacheable only if its index query is" on every leaf: 9 index-query kinds x 9 index operations x 2 search APIs = 162 scenarios, 324 hit-set checks, 99 property checks. Result on the stock jars (main with assertions on and off, 10.5.2): 14 stale cached results and 8 property violations, all for doc-values index queries after an in-place doc-values update; the model agreed with the uncached search in all 162 post-operation checks. With the fix: 0 and 0.
• JUnit. The scenario reduced to a public-API test: 3 of 3 fail with assertions on and off, 30 of 30 over 10 random seeds.