FunctionRangeQuery on a string field compares term ordinals as float, so above 2^24 distinct values in a segment it matches values just outside the range

FunctionRangeQuery over BytesRefFieldSource on a SORTED field, or over SortedSetFieldSource on a SORTED_SET field, does a string range through DocTermsIndexDocValues.getRangeScorer. That method looks the two string bounds up in the segment's sorted dictionary and gets exact int ordinals, then compares each document's ordinal with them as a float (float docVal = ordVal(doc); return docVal >= ll && docVal <= uu;). A float is exact for whole numbers only up to 2^24 = 16,777,216, so in a segment where the field has more than 2^24 distinct values, a value whose ordinal sits next to a bound rounds onto the bound's float and is matched. On a real single segment of 16,777,220 unique values, the range [016777217 TO 016777217] returns 2 hits, 016777216 and 016777217, with no error. Only extra hits occur, at most 2 per bound below 2^25 ordinals and up to 128 near 2^31; no in-range hit is lost. The compare was int up to 8.5.2; LUCENE-9258 changed it to float while adding multi-valued support, so every release from 8.6.0 to 10.6.0 and main are affected. Changing float back to int fixes it.

1. Entry points. BytesRefFieldSource ("for string based fields") returns a DocTermsIndexDocValues for any non-BINARY field (valuesource/BytesRefFieldSource.java:118-119). SortedSetFieldSource ("multi-valued string based fields") returns one over a SortedSetSelector view (valuesource/SortedSetFieldSource.java:59-61). FunctionRangeQuery's scorer is functionValues.getRangeScorer(...) (FunctionRangeQuery.java:172).
2. Exact bounds. DocTermsIndexDocValues.getRangeScorer converts each bound with termsIndex.lookupTerm(...). A lower bound missing from the dictionary becomes its insertion point, a missing upper bound the ordinal just below it, an exclusive bound moves by one, an absent bound is Integer.MIN_VALUE / Integer.MAX_VALUE; the results are final int ll, uu (docvalues/DocTermsIndexDocValues.java:129-150).
3. The narrowing. matches(int doc): if (!exists(doc)) return false; float docVal = ordVal(doc); return docVal >= ll && docVal <= uu; (:155-157). ordVal is the exact int ordinal (:79-81); assigning it to float rounds it to the nearest float (ties to even), and binary numeric promotion turns ll and uu into floats for the comparisons too.
4. The arithmetic. In the one-document repro the document has ordinal 16,777,216 and the lower bound 016777217, absent from the dictionary, has insertion point 16,777,217. Both become 16,777,216.0f, so docVal >= ll is true and the document matches although its value sorts before the bound.

• Int-to-float rounding is monotone, so an in-range ordinal is never rejected: only extra hits.
• No wrong match while every ordinal and bound is at most 2^24, so it needs more than 2^24 distinct values of the field in the segment.
• For a bound in [2^24, 2^25) at most 2 values outside it are admitted; the overall maximum is 128 values per bound, near 2^31. The model covers the lower bound; the upper bound is the mirror case, shown next.
• An upper bound admits extras too: on 16,777,224 hex ids, {1000000 TO 1000003] (3 values) returns 6 hits, 1000000 below the range and 1000004, 1000005 above it.

• Who is hit. Callers of FunctionRangeQuery (the only caller of getRangeScorer in Lucene's main sources; a test also calls it directly) over BytesRefFieldSource on a SORTED field or SortedSetFieldSource on a SORTED_SET field (the only in-tree users of DocTermsIndexDocValues). A string source has no floatVal, so these queries are used where scores are not needed: a filter clause, ConstantScoreQuery, IndexSearcher.count.
• Default vs opt-in. Default codec and configuration; the API itself is opt-in (lucene/queries; FunctionRangeQuery is @lucene.experimental).
• Scale. Only segments in which the field has more than 2^24 distinct values. For SORTED that means more than 16.8 million documents in one segment; for SORTED_SET the distinct values can outnumber the documents. Such segments are legal: IndexWriter.MAX_DOCS is Integer.MAX_VALUE - 128, and SortedSetSelector rejects only fields with Integer.MAX_VALUE or more unique values.
• Size of the error. Only extra hits, only values next to a range edge: at most 2 per bound below 2^25 ordinals, up to 128 near 2^31. No in-range hit is lost.
• Silent. No exception and no assertion: the counts are wrong with assertions on and off.
• Likelihood: rare. It needs this experimental API on a string field and a very large segment, and it only moves the range edges; no public report of it was found, although it has shipped since 8.6.0 (2020).

The test is the hunt's minimal repro with one statement re-wrapped so that it passes :lucene:queries:check -x test (google-java-format); the code is otherwise identical. The wrapper keeps the dictionary consistent: lookupOrd(ord) is the 9-digit number ord, lookupTerm is the inherited binary search over it, and getValueCount() is 2^24 + 1. The query is counted, which needs no scores (a scored search over a string source throws UnsupportedOperationException from floatVal, as the documented float score implies; not part of this finding).

Executed: gradle on main e1faeba08bde with assertions on (seeds DEADBEEF, 5EED1108) and off (5EED1108): fails 1 of 1; with the fix it passes. The hunt's runs fail the same way (5 of 5 random seeds with assertions off).

About the stand-in dictionary: "Ordinals are dense" describes the numbering, which the wrapper keeps, and a wrapper-free program over a real single segment of 16,777,218 unique values (stock IndexWriter, forceMerge(1), about 24 s at a 2 GB heap) returns [0016777217 TO *] count 2 instead of 1 and [* TO 0016777216] count 16,777,218 instead of 16,777,217 on main and 10.6.0, and the right counts with the fix. That run is evidence, not part of the repro.

Use the same test as the regression test.

cp $REPRO/TestFunctionRangeQueryLargeOrdinals.java $LUCENE/lucene/queries/src/test/org/apache/lucene/queries/function/
cd $LUCENE && ./gradlew :lucene:queries:test --tests TestFunctionRangeQueryLargeOrdinals -Ptests.seed=5EED1108 -Ptests.asserts=true
# also with -Ptests.asserts=false; the result does not depend on the seed

TestFunctionRangeQueryLargeOrdinals > testOrdinalAbove2Pow24 FAILED
    java.lang.AssertionError: frange(f):[016777217 TO *] expected:<0> but was:<1>
        at __randomizedtesting.SeedInfo.seed([5EED1108:711E936FD763D735]:0)
        at junit@4.13.2/org.junit.Assert.fail(Assert.java:89)
        at junit@4.13.2/org.junit.Assert.failNotEquals(Assert.java:835)
        at junit@4.13.2/org.junit.Assert.assertEquals(Assert.java:647)
        at org.apache.lucene.queries.function.TestFunctionRangeQueryLargeOrdinals.testOrdinalAbove2Pow24(TestFunctionRangeQueryLargeOrdinals.java:111)
1 test completed, 1 failed

# with the fix (int docVal): :lucene:queries:test (SUCCESS): 1 test

• Contract. FunctionRangeQuery "matches docs in which the values in the value source match a configured range" (FunctionRangeQuery.java:32-33); FunctionValues.getRangeScorer "matches documents with values between the specified range" (FunctionValues.java:224-226), and the comment above it names the string case, "doing a binary search on the StringIndex" (:228-230). For a string source the range is lexicographic, and the override computes it exactly (DocTermsIndexDocValues.java:129-150). No javadoc, package doc, CHANGES or MIGRATE entry says string ranges are approximate.
• Sibling. IntDocValues.getRangeScorer compares in its native type: int val = intVal(doc); return val >= ll && val <= uu; (IntDocValues.java:113-114).
• Tests. No test exercises more than 2^24 ordinals or asserts float rounding; TestSortedSetFieldSource checks an "a".."z" range over two documents, and TestFunctionRangeQuery covers numeric sources only.
• History. Up to 8.5.2 the scorer compared int ordinals: int ord = values.ordValue(); return ord >= ll && ord <= uu; at the 7.0.0, 8.0.0 and 8.5.2 tags, and int ord = termsIndex.getOrd(doc); with the same return at 4.0.0, 5.0.0 and 6.0.0. LUCENE-9258 (b1ec1cd9e0c, 2020-03-11, #10298) replaced its private doc-values lookup with exists(doc) / ordVal(doc) so that it works on SortedSetSelector views, and wrote float docVal = ordVal(doc);, the shape of the float default scorer (float docVal = floatVal(doc);). The commit, its CHANGES entry and the #10298 discussion never mention float or precision.

The strongest "intended" case (built by the intended-behaviour verifier; a cross-model reviewer rated it moderate): function ranges are float-based by default (Float.parseFloat bounds), the score is documented as a float, DocTermsIndexDocValues is @lucene.internal and FunctionRangeQuery @lucene.experimental, ValueSource is named in the open deprecation proposal #16820, the scale is extreme, and the test's stand-in dictionary has more terms than documents although "Ordinals are dense".

Why it fails: this override exists to do a string range by ordinal and computes exact int bounds, and a string source has no float value at all ("Float scoring does not require float matching", the cross-model reviewer). The trigger goes through public, non-deprecated classes; "experimental" allows API changes, not wrong hits. A plain 16.8M-document single segment reproduces it in under a minute, silently. "Dense" describes the numbering, which the wrapper keeps, and the real-index runs need no wrapper. The deprecation proposal bears on priority, not validity. Verdict: not intended, a regression.

One fix was built and validated in a scratch worktree of e1faeba08bde; the alternatives are listed with their trade-offs.

One word in DocTermsIndexDocValues.getRangeScorer: the document's ordinal stays an int, so it is compared exactly with the exact int bounds ll and uu. LUCENE-9258's multi-valued support (exists / ordVal) stays as it is.

--- a/lucene/queries/src/java/org/apache/lucene/queries/function/docvalues/DocTermsIndexDocValues.java
+++ b/lucene/queries/src/java/org/apache/lucene/queries/function/docvalues/DocTermsIndexDocValues.java
@@ -153,7 +153,7 @@ public abstract class DocTermsIndexDocValues extends FunctionValues {
       @Override
       public boolean matches(int doc) throws IOException {
         if (!exists(doc)) return false;
-        float docVal = ordVal(doc);
+        int docVal = ordVal(doc);
         return docVal >= ll && docVal <= uu;
       }
     };

Trade-offs

None known. Results change only where they were wrong: values just outside a bound, in segments with more than 2^24 distinct values, stop matching. It also drops the int-to-float conversions per document.

What the checks validated

• Gradle, JDK 25, scratch worktree of e1faeba08bde (removed afterwards): the test fails on stock with assertions on (seeds DEADBEEF, 5EED1108) and off (5EED1108), and passes with the fix, assertions on and off.
• With the fix: the test plus TestFunctionRangeQuery, TestSortedSetFieldSource and TestDocValuesFieldSources, 12 tests, 0 failures; the whole :lucene:queries:test, 513 tests including the new one, 0 failures, 5 skipped; :lucene:queries:check -x test passes.
• The hunt: the repro passes with the fix shadowed; the wrapper-free 16,777,218-value index gives the right counts; a cross-model reviewer's real-index test and the existing function-query suites pass with it.

Both hold every int ordinal exactly, so they would also fix it.

Trade-offs

No advantage over int, and a wider type would suggest that one is needed. Not validated.

State that string function ranges are approximate above 2^24 distinct values.

Trade-offs

Not recommended: it would legitimise wrong hits that a one-word change removes, and it contradicts the exact bounds the method computes. Not validated.

Method: non-formal (code reading, then an executed differential probe; the Z3 floating-point model only bounded the window afterwards).

• Round 21 of the hunt built a ranked map of under-tested classes over core and 13 modules. The coverage-gap lens read DocTermsIndexDocValues.getRangeScorer with the property "a string range scorer must compare ordinals exactly" and saw the float compare. Its probe (2026-11-02) indexed 16,777,220 unique values into one segment and compared five ranges with a byte-comparison reference: 3 wrong on main, also on 10.6.0 and 8.6.0 (SORTED; SORTED_SET on main too); 8.5.2 clean.
• The coverage-critic lens found the same root independently (its probe: 16,777,224 documents, wrong also on 9.12.3). The two leads were then judged together as one finding.
• Its finder reduced it to a public-API JUnit, bounded the window with a Z3 floating-point / bit-vector model (10 obligations) and bisected it to LUCENE-9258. Independent verifiers, a cross-model reviewer (OpenAI GPT-5.6), an adjudication and an audit then re-ran it, and a last check reduced the test to one document.