Range filters whose fast-match query reads doc values keep serving cached results after an in-place doc-values update

LongRange#getQuery(Query fastMatchQuery, LongValuesSource) and its three siblings (the MultiLongValuesSource overload and the two DoubleRange ones) return a query that only checks the documents its fast-match query matches. Its Weight iterates the fast-match Weight's scorer, but its isCacheable asks only the value source (return valueSource.isCacheable(ctx);, LongRange.java:195-198 and :302-305, DoubleRange.java:208-211 and :315-318 on main a9779ef3c193). LRUQueryCache trusts Weight#isCacheable and keys entries on the segment's core cache key, which does not change on a doc-values update. So when the fast-match query reads a doc-values field that is updated in place (IndexWriter#updateNumericDocValue, updateBinaryDocValue or updateDocValues), the entry cached before the update keeps being served after the reopen: 5 hits instead of 4 in the repro, with and without assertions, on main and on every executed release from 7.2.0 to 10.5.2. The fast-match query on its own is correctly uncacheable on that segment. On 7.2.0-10.6.0 (10.6.0 by reading) the default IndexSearcher cache reproduces it with zero configuration; main has had no default cache since #14187 (unreleased), so there it needs an installed cache, for example the MIGRATE.md snippet. Introduced by LUCENE-8042 (276e317e9424), which replaced a never-cacheable "TODO delegate to LongValuesSource?" with the value-source check and left out the fast-match Weight built in the same method. The fix ANDs fastMatchWeight.isCacheable(ctx) into the four overrides.

• Fast-match query: the first argument of LongRange/DoubleRange#getQuery(Query fastMatchQuery, valueSource). "The query will check all documents that match the provided match query" and "@param fastMatchQuery a query to use as a filter" (LongRange.java:313-314, 319, 335; DoubleRange.java:326-327, 332, 348). The range check itself reads the value source. The query is the usual way to drill down on a range facet (DrillDownQuery#add, as TestRangeFacetCounts does).
• 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 friends change a doc-values 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). In every run the reopened segment kept its key (sameCore=true). 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 fast-match Weight once and iterates its scorer; the value source is only the second-phase check (LongRange.java:156-190).
2. isCacheable returns valueSource.isCacheable(ctx) and nothing else (LongRange.java:195-198; the same at :302-305, DoubleRange.java:208-211 and :315-318).
3. A doc-values fast match such as NumericDocValuesField.newSlowExactQuery("inStock", 1) reports DocValues.isCacheable(ctx, "inStock"), false once the field was updated in that segment (DocValues.java:340-346); a small BooleanQuery fast match like this two-clause one ANDs its clauses' answers (one with more clauses than BOOLEAN_REWRITE_TERM_COUNT_THRESHOLD is never cacheable; BooleanWeight.java:273-285). The range Weight never asks it.
4. After the update and reopen, the cache asks the range Weight, gets true, finds the old entry under the unchanged core key and returns it. The fast-match Weight is not consulted, because the outer entry is served before the range Weight's scorer is built.

20 documents, one segment, price 10 each; docs 0-9 shoes, docs 0-4 in stock. DrillDownQuery(MatchAllDocsQuery) plus add("price", LongRange[0, 100].getQuery(shoes AND inStock == 1, price)) counts 5. After updateNumericDocValue(id:0, inStock, 0) and openIfChanged: uncached 4, cached 5. The same for all four getQuery overloads used as plain filters. The range Weight's isCacheable is true on the updated segment while the fast-match Weight's is false. With an allow flag in the fast match, revoking doc 0 and granting doc 15 returns docs [0..9] where the uncached answer is [1..9, 15]: the wrong answer goes both ways for the changed documents.

• Needs: a fast match that reads a doc-values field, an in-place update of that field, a range query cached on that segment before the update, and a cache that survives the reopen. The range query must run without scores, as a count, a filter or a drill-down dimension does: only then does IndexSearcher#createWeight wrap it in the cache (IndexSearcher.java:976-982).
• Not affected: a points or postings fast match (the distance demo's bounding box, the LongPoint/DoublePoint ranges in TestRangeFacetCounts), a null fast match, the same restriction in the base query or as its own clause, a range query first cached after the update. Deleted documents stay hidden.
• The stale entry survives later unrelated updates and reopens; it ends when the segment is merged into a new one, the entry is evicted, or the range's own value field is updated in place in that segment, or the application clears, closes or replaces the cache. The duration in a running application was not measured.

• 7.2.0 to 10.5.2: 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, and a query only after repeated use. One 12,000-document segment and the query run 6 times reproduce it with no cache code at all on 9.12.3 and 10.5.2 (5 instead of 4).
• 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; with exactly that snippet and otherwise default settings the bug is back on main (5 instead of 4).
• Effect. Silent wrong hit counts, hit lists and drill-downs for the documents whose flag changed; 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; nothing large is needed.
• How likely: rare. Every fast match that Lucene ships or tests is a points, postings or match-all query (TestRangeFacetCounts.java:1673-1676 passes MatchAllDocsQuery), none of which can be updated in place; no facet test updates doc values; code search found no Elasticsearch, OpenSearch or Solr code that runs these queries with a Lucene query cache. The realistic trigger is a selective fast match that ANDs a postings clause with a doc-values flag, the use the doc-values query javadoc implies (such queries are "slow if they are not ANDed with a selective query", NumericDocValuesField.java:134-135; its explicit advice is to wrap them in an IndexOrDocValuesQuery with a points query, :135-137, and a field updated in place is doc-values only, so it has no points).

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: cached count after the in-place inStock update 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.apache.lucene.facet.range.TestRangeFastMatchQueryCache.testCachedRangeQuerySeesFastMatchDocValuesUpdate(TestRangeFastMatchQueryCache.java:72)

• 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 counts without scores and gets 5 instead of 4.
• Upstream test. TestSegmentCacheables.java:43, 84: "after field3 is updated, all composites referring to it should be uncacheable".
• Precedent in core and queries. BooleanWeight.java:273-285, ConstantScoreQuery.java:193-195 and FunctionScoreQuery.java:280-282 (inner.isCacheable(ctx) && valueSource.isCacheable(ctx)) combine their sub-weights. LUCENE-8042 ANDed the sub-weights in the Weights that already combined them through getCacheHelper(context, weights) (BooleanWeight, DisjunctionMaxQuery, DrillSidewaysQuery and others). Where it replaced a return null; // TODO delegate to ... it asked the value source only: in these range Weights, in FunctionScoreQuery and in spatial-extras CompositeVerifyQuery. FunctionScoreQuery's inner Weight was ANDed in five days later by LUCENE-7736 (2a4dd499bbd on master, 03afeb7766a on branch_7x, committed 2017-11-15), before 7.2.0: a precedent for the fix.
• History. LUCENE-8017 (a886a001a4c) made these Weights never cacheable: return null; // TODO delegate to LongValuesSource?. LUCENE-8042 (276e317e9424, by romseygeek, +1 by rmuir, 7.2.0) resolved the TODO by delegating to the value source only; the fastMatchWeight was already in the same method. No comment on #9090, #9065 or #543 mentions the fast match; in #543 gsmiller wrote "I think we still need isCacheable though for the query implementations in LongRange and DoubleRange".
• Docs. No javadoc, CHANGES or MIGRATE entry says the fast match must be segment-immutable; getQuery calls it "a query to use as a filter" and LongRangeFacetCounts says "only documents passing the filter are checked" (LongRangeFacetCounts.java:77, 101).

The intended-behaviour checker and a reviewer from another model family (OpenAI GPT-5.6) built the strongest case: (a) every fast match Lucene ships or tests is a points, postings or match-all query, and doc-values queries are documented as slow; (b) IndexOrDocValuesQuery#isCacheable also asks only one sub-query (IndexOrDocValuesQuery.java:211-214), and spatial-extras CompositeVerifyQuery ignores its indexQuery the same way (:114-115); (c) the classes are @lucene.experimental; (d) main has no default cache; (e) in #543 romseygeek asked "possibly we don't need to worry about caching either given how these are used?".

Why it fails: (a) convention is not a contract; a selective postings-plus-doc-values fast match is the use the doc-values javadoc implies, and it triggers the bug. (b) IndexOrDocValuesQuery relies on its documented precondition "Both provided queries must match the same documents" (:61); the range query ANDs two different predicates on different fields. CompositeVerifyQuery got its value-source-only answer in the same LUCENE-8042 change: a second instance of the pattern, not a documented decision. (c) Experimental allows API changes, not wrong results. (d) The cache is public, MIGRATE.md shows how to re-enable it, and it is the default in every release since 7.2.0. (e) The remark asked whether the new facet values-source abstractions needed caching support at all (next to dropping needsScores() and rewrite()); gsmiller replied that isCacheable is still needed for the LongRange and DoubleRange queries, and it was kept. Verdict: not intended; no checker rated the intended case better than weak.

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

The same two-line change in LongRange.ValueSourceQuery, LongRange.MultiValueSourceQuery, DoubleRange.ValueSourceQuery and DoubleRange.MultiValueSourceQuery (2 files, 4 hunks, +8/-4; in LongRange.MultiValueSourceQuery the field is named valuesSource). It is what FunctionScoreQuery does for its inner query.

@Override
public boolean isCacheable(LeafReaderContext ctx) {
  return (fastMatchWeight == null || fastMatchWeight.isCacheable(ctx))
      && valueSource.isCacheable(ctx);
}

Trade-offs

• On a segment where a field the fast match reads was updated in place, the range query is no longer cached until that segment is merged away. The fast-match query on its own is already treated that way, so nothing new is lost.
• Without updates, a cacheable fast match changes nothing: the range query is still served from the cache (the brief's control test, one fast-match shape; on the introducing commit the fix keeps both cache entries).
• A fast match that is not cacheable for another reason ("global statistics or scores", SegmentCacheable.java:34-35) now also keeps the range query out of the cache, with or without updates: correct, but a change in what gets cached.
• At most one extra isCacheable call, on the fast-match Weight, per leaf cacheability check; none for a null fast match. A "Bug Fixes" CHANGES line would be usual; none is drafted.

What the checks validated

• Scratch worktree of a9779ef3c193, gradle: the new test fails 6 of 8 on the stock tree and passes 8 of 8 with the fix, with assertions on and off; the whole lucene/facet module (40 suites, 314 tests, among them TestRangeFacetCounts and TestDrillDownQuery) passes with assertions on and off; :lucene:facet:check -x test (format, ecjLint, forbiddenApis) passes.
• Standalone runner with the fix shadowed in: the original test 5 of 5, the independent test 7 of 7, the drill-down probe 3 of 3, the allow/deny-flag probe 3 of 3; the MIGRATE.md program prints default searcher 4, uncached 4.
• On the introducing commit 6e4f9a62e7cc the same change is correct and keeps both cache entries.
• Not run: nightly tests, a benchmark.

Return (or rewrite to) a BooleanQuery with the fast match and a range query without fast match as two FILTER clauses; BooleanWeight then combines cacheability.

Trade-offs

More invasive for the same result: it changes how iteration and costs are planned and how toString and equals look. Not built.

A javadoc note on the four getQuery methods.

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.

Method: semi-formal (the hunt's query-cache hunt, 2026-10-26, main ea57360912ed).

• Scan. A bytecode scan with the JDK class-file API over every module jar resolved the isCacheable body of 123 classes and classified them (constant, doc-values check, delegation). The four range Weights came out as "delegate: value source only"; reading the code showed that the fast-match Weight they iterate is not consulted.
• Sweep. A differential harness on the real jars ran 35 doc-values query cases (27 ok, 8 STALE): fill an always-cache LRUQueryCache, update a field in place, reopen with the same segment core, compare cached and uncached results. The four getQuery(fastMatch on a doc-values field, ...) cases were STALE (cached 5, uncached 4); every other STALE case belongs to two sibling bugs with separate fixes.
• Model. A TLA+ model of the cache path (isCacheable guard, core-keyed entries, NRT reopen, in-place update, merge, eviction), written afterwards, holds for correct cacheability shapes and violates its SearchCorrect invariant with a short counterexample for a query that checks a strict subset of the fields it reads.
• JUnit. The finder's public-API test failed 5 of 5 on the stock jars with assertions on and off, 100 of 100 over 20 iterations.