Range grouping can label a value with a range that leaves it out: DoubleRangeFactory(0, 0.1, 10).getRange(0.6) is DoubleRange(0.5, 0.6)

DoubleRangeFactory(min, width, max) turns a document's double value into the range that DoubleRangeGroupSelector groups it by, and that range comes back as the group's value. DoubleRange is documented as an inclusive minimum and an exclusive maximum, and the factory's ranges as "inclusive at the lower end, and exclusive at the upper end". getRange picks the bucket number with Math.floor((value - min) / width) and computes the bounds as min + bucket * width and then + width: three separately rounded results that can disagree near bucket boundaries, most visibly when width or min is not exactly representable in binary. With new DoubleRangeFactory(0, 0.1, 10), getRange(0.6) is DoubleRange(0.5, 0.6) and getRange(1.7) is DoubleRange(1.7000000000000002, 1.8000000000000003); 27 of the 100 values 0.0 to 9.9 lie outside their own range, and neighbouring ranges leave one-ulp gaps or overlap. Group membership, counts and order stay consistent; only the returned ranges are wrong, and anything built from them, such as a drill-down range query, which then misses or adds boundary documents. Present since the class was added in 8.6.0, in every release through 10.6.0 and on main; a small fix takes both bounds from one grid and moves the bucket by one when needed.

1. DoubleRangeFactory.getRange (DoubleRangeFactory.java:62-64):

   double bucket = Math.floor((value - min) / width);
   reuse.min = min + (bucket * width);
   reuse.max = reuse.min + width;

1. 0.6: the range ends too early. (0.6 - 0) / 0.1 = 5.999999999999999, so bucket 5, which is right for the binary values (the double 0.6 lies below 6 times the double 0.1). reuse.min = 0.5, and reuse.max = 0.5 + 0.1, which rounds to 0.6. The next bucket starts at 6 * 0.1 = 0.6000000000000001. So 0.6 lies in no range.
2. 1.7: the bucket is one too high. 1.7 / 0.1 rounds up to exactly 17.0, although the double 1.7 lies below 17 * 0.1 = 1.7000000000000002; the range starts above the value.
3. The ranges do not tile. reuse.max is the rounded reuse.min plus width, rounded again, while the next range starts at min + (bucket + 1) * width, rounded once.
4. Membership stays consistent. DoubleRangeGroupSelector calls getRange once per document on its own value (DoubleRangeGroupSelector.java:71) and keeps a document in the second pass if its range is one of the top groups (:75); DoubleRange.equals compares both bounds exactly (DoubleRange.java:44-50). Only the reported bounds are off.

• DoubleRangeFactory(0, 0.1, 10): getRange(0.6) = DoubleRange(0.5, 0.6), getRange(1.7) = DoubleRange(1.7000000000000002, 1.8000000000000003), getRange(4.1) = DoubleRange(4.0, 4.1).
• Of the 100 values 0.0, 0.1, ..., 9.9, 27 lie outside their own range (0.6, 1.7, 3.4, 3.9, 4.1, ...). Of the 99 pairs of neighbouring bucket ranges, 27 do not meet: 21 gaps and 6 overlaps such as [1.2000000000000002, 1.3000000000000003) and [1.3, 1.4000000000000001), each one ulp.
• End to end: documents with the values 0.55, 0.6 and 0.65 in a field price form the groups DoubleRange(0.5, 0.6) (0.55 and 0.6) and DoubleRange(0.6000000000000001, 0.7000000000000001) (0.65); DoublePoint.newRangeQuery("price", 0.5, Math.nextDown(0.6)) over the first label counts 1 document.
• A boundary effect: over six factories every gap or overlap is at most one ulp of the factory's largest bound, and no bucket midpoint is outside its range. Within 200 doubles of every boundary, a value outside its range is one double outside in five of the factories and up to 31 doubles outside in (-5, 0.7, 5) near -0.1, where doubles are denser.
• Which factories: an inexact min is enough. With widths 1, 10, 100, 0.5 and 0.25, no checked value (bucket boundaries and two-decimal values) is outside its range when min is an integer, but 8,519 of 499,985 are when min has two decimals, e.g. DoubleRangeFactory(248.8, 1.0, 928.8).getRange(520.8) = DoubleRange(519.8, 520.8). A negative min is enough too, even an integer one, because value - min then rounds: new DoubleRangeFactory(-10, 1, 10).getRange(0.9999999999999999, null) = DoubleRange(1.0, 2.0). With a non-negative integer min and an integer width, like Lucene's tests, 0 of 600,000 values next to a boundary were outside.

• Who. Range grouping through GroupingSearch(Supplier) (GroupingSearch.java:85) or the grouping collectors, with a decimal width (the natural choice for decimal data) or a decimal (or negative) min. A read-only code search on 2026-10-26 found no use of DoubleRangeFactory in Elasticsearch, OpenSearch or Solr (default branches). GroupingSearch and GroupDocs are marked @lucene.experimental (GroupingSearch.java:44, GroupDocs.java:33).
• What goes wrong. On every search, with assertions on or off: some values on a bucket boundary get a range that excludes them (27 of 100 for width 0.1), and neighbouring ranges leave one-ulp gaps or overlaps. A drill-down built from a group's range misses that group's boundary documents (a gap) or also matches the neighbour's (an overlap).
• What stays right. Which documents are in which group, the counts, the group sort and the documents within each group. Factories with a non-negative integer min and an integer width, the only ones in Lucene's tests, showed no value outside its range.
• How likely. Plausible within a rarely used API: decimal data puts many values exactly on boundaries (27 of the 100 one-decimal values for width 0.1), but it shows only once an application reads the bounds or filters by them, and nobody has reported it since 8.6.0 (2020).

Same package as Lucene's grouping tests (the file adds the Apache license header). The seed only picks the test framework's locale and settings, which the test does not use. The same test is the suggested regression test.

End to end through GroupingSearch (not part of the repro): documents 0.55, 0.6 and 0.65 give the group DoubleRange(0.5, 0.6) with 2 documents, whose range query DoublePoint.newRangeQuery("double", 0.5, Math.nextDown(0.6)) (the test's field is double) counts 1 (group DoubleRange(0.5, 0.6) expected:<2> but was:<1>, the hunt's test).

cp $REPRO/org/apache/lucene/search/grouping/TestDoubleRangeFactoryContainsValue.java \
   $LUCENE/lucene/grouping/src/test/org/apache/lucene/search/grouping/
cd $LUCENE && ./gradlew :lucene:grouping:test --tests org.apache.lucene.search.grouping.TestDoubleRangeFactoryContainsValue \
  -Ptests.seed=DEADBEEF -Ptests.asserts=true
# also with -Ptests.asserts=false (same failure); the test uses no randomness

# gradle, main 645d4fe14a20, -Ptests.seed=DEADBEEF, -Ptests.asserts=true (identical with =false)
TestDoubleRangeFactoryContainsValue > testRangeContainsValue FAILED
    java.lang.AssertionError: DoubleRange(0.5, 0.6) should contain 0.6
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:476F598A28E9D11B]:0)
        at org.apache.lucene.search.grouping.TestDoubleRangeFactoryContainsValue.testRangeContainsValue(TestDoubleRangeFactoryContainsValue.java:26)
1 test completed, 1 failed

# standalone runner: the same failure on main (-ea, -da), 10.6.0 (-ea, -da), 10.5.2 (-ea) and 9.12.3 (-ea)
# with the fix: 1 test, 0 failures (assertions on and off)

• The contract. DoubleRange.java:23: "Represents a contiguous range of double values, with an inclusive minimum and exclusive maximum"; :27 and :30: "The inclusive minimum value of this range", "The exclusive maximum value of this range". DoubleRangeFactory.java:31-33: "Ranges are inclusive at the lower end, and exclusive at the upper end." :43: "Finds the DoubleRange that a value should be grouped into". Nothing documents a rounding tolerance or a restriction on width (javadoc, package-info.java, the 8.6.0 CHANGES entry).
• Lucene's tests read the range as a range. BaseGroupSelectorTestCase declares filterQuery(groupValue) (:50) and checks each group's documents against it (:71, :108, :160, :193, :215, :261), which TestDoubleRangeGroupSelector.java:57 builds as DoublePoint.newRangeQuery("double", groupValue.min, Math.nextDown(groupValue.max)). Its factory is (100, 100, 900) (:46), and TestDoubleRangeFactory uses (10, 10, 50) (:26): a positive integer min and width, where no wrong range was found.
• The binary reading fails too. Reading 0.1 as its exact binary value, the stock ranges still exclude their own values, leave gaps and overlap; taking both bounds from one grid removes all three.
• History. The formula, the javadoc and the selector test's label filter come from the introducing commit 7c350d22c707 (LUCENE-7889); the generic oracle in BaseGroupSelectorTestCase that runs the filter came a week earlier with LUCENE-9348 (0c58687a978e, 2020-05-04, #10388). The PR of 7c350d22c707 (apache/lucene-solr#1484) has no review comments, and issue #8940 discusses javadocs and tests, not rounding. No CHANGES, MIGRATE, test or comment endorses gaps.

The strongest case (the cross-model reviews and the intended-behaviour checker rated it moderate; the reproducer and the adjudication make the same case): the API works on binary doubles and 0.1 is not exact, so ranges can only approximate decimal boundaries; another engine's histogram uses the same floor((value - offset) / interval) formula, documents it and treats this symptom as normal; inside Lucene both grouping passes compute the same key, so membership is right, and no Lucene code outside its tests turns a label into a query; and no binary fix gives decimal buckets (with the fix, 1.7 moves to [1.6, 1.7000000000000002)).

Why it fails: Lucene, unlike that histogram, returns an explicit range object and documents what it contains; the stock ranges are not a consistent binary reading either; the introducing commit's own test uses the range as an exact half-open filter; and the trigger is a public constructor with an ordinary width. Verdict: a defect, minor.

One fix was validated in a scratch worktree of 645d4fe14a20 with gradle; it is the hunt's fix, unchanged. A membership-preserving alternative (label each bucket with exactly the doubles it receives, found one double at a time) was tried and rejected: it hangs when a bucket boundary is at 0, e.g. new DoubleRangeFactory(-1000, 1, 1000).getRange(0.5, null) did not return within 30 s. Combined with LFV-407's clamp on the same line, the recommended fix becomes reuse.max = Math.min(min + ((bucket + 1) * width), max); (validated on both bugs' tests, assertions on). Fix A alone leaves LFV-407's problem (the last range is not cut at max) as it is.

After the floor, move the bucket down if the value is below min + bucket * width, or up if it is at or above min + (bucket + 1) * width, then use exactly those two grid points as the range. 1 file, +9/-1.

     double bucket = Math.floor((value - min) / width);
+    if (bucket > 0 && value < min + bucket * width) {
+      bucket--;
+    } else if (value >= min + (bucket + 1) * width) {
+      bucket++;
+    }
     reuse.min = min + (bucket * width);
-    reuse.max = reuse.min + width;
+    reuse.max = min + ((bucket + 1) * width);

Trade-offs

• Behaviour change. For (0, 0.1, 10), 27 of the 100 bucket ranges change their max by one ulp ((1.7000000000000002, 1.8000000000000003) becomes (1.7000000000000002, 1.8)), and group membership changes: 10 of the 100 values 0.0 to 9.9 move to a neighbouring bucket, each into the range [min + k * width, min + (k + 1) * width) that contains it. 6 move down (1.7, 3.4, 3.9, 6.8, 7.3, 7.8: the division rounded up to exactly k), and 4 move up (4.3, 8.1, 8.6, 9.1: k * 0.1 rounds down onto the value, so DoubleRange(4.2, 4.3) becomes [4.3, 4.4)). Over 889,912 boundary values the grouping partition differs from stock.
• Not decimal buckets. 0.6 gets [0.5, 0.6000000000000001) and 1.7 gets [1.6, 1.7000000000000002): correct ranges, but not what a decimal reading expects.
• Limits. "One step is enough" held in every check of factories whose width is well above the spacing of doubles near the values (all finite, with a positive width); that is a test result, not a proof. It fails when width is below the spacing of doubles near the values: for DoubleRangeFactory(1e6, 1e-12, 1e6 + 1) only about one grid range in 116 is non-empty, getRange(1000000.0000000001) computes bucket 116 while the grid range that contains the value is bucket 174, and stock and the fix both return the empty DoubleRange(1000000.0000000001, 1000000.0000000001).
• Cost. Up to four min + k * width evaluations per call (two distinct values, each computed twice) instead of one plus an addition, and two or three compares; no benchmark was run.

What the checks validated

• Stock + test: fails, assertions on and off (gradle).
• + fix: the test passes; the whole lucene/grouping module, 57 tests, 0 failures, assertions on and off; :lucene:grouping:check -x test (formatting, ecjLint, forbiddenApis) passes.
• + fix and LFV-407's clamp: this test, LFV-407's DoubleRangeFactory test, TestDoubleRangeFactory and TestDoubleRangeGroupSelector pass (10 tests, assertions on).
• Side probes (not tests to add): 0 of 100 grid values outside and 0 gaps or overlaps; 0 of 396,668 values outside in a random sweep of 20,000 factories (10,232 on stock); 0 of 499,985 with a two-decimal min (8,519 on stock).
• Earlier: the hunt's 2 tests and an independent verifier's 5 tests pass with it.

reuse.max = min + ((bucket + 1) * width) and keep the bucket as computed.

Trade-offs

The ranges tile, but 10 of the 100 grid values are still outside their range, because the bucket number still comes from the division alone: for 1.7, 3.4, 3.9, 6.8, 7.3 and 7.8 the division rounds up to exactly k; for 4.3, 8.1, 8.6 and 9.1 it rounds down and the shared upper bound (k + 1) * 0.1 rounds down onto the value.

What the checks validated

Side probe on main 645d4fe14a20 with the change shadowed: 10 of 100 outside, 0 gaps or overlaps.

Say in the javadoc that min and width should be exactly representable and min non-negative (for example integers), or that decimal data should be grouped with LongRangeGroupSelector over scaled values (e.g. cents).

Trade-offs

Keeps ranges that contradict DoubleRange's own [min, max) javadoc. Only a non-negative integer min with an integer width was measured clean, and no setting helps once width is below the spacing of doubles near the values. Within those limits it is also the workaround until a fix ships.

• Solver model. An SMT model of getRange in IEEE-754 double arithmetic (Z3; round-to-nearest subtraction, division, multiplication and addition, round-down floor) answered the query "min <= v < max, finite inputs, width > 0, yet the returned range does not contain v" with a satisfying input, DoubleRangeFactory(-31.051544275134813, 0.2985725411070654, 7.706943822235074E-301).getRange(-1.42110715556365E-14), which a replay on the real jar confirmed.
• Bounded-exhaustive check of the real factory over decimal grids: 1,594 containment failures among 1,029,006 checks, 0 with the fix.
• Grid scan of DoubleRangeFactory(0, 0.1, 10) over 0.0 to 9.9: 27 of 100 values outside their range, the first being 0.6.
• Then a public-API JUnit, independent verifiers, cross-model reviews (reading only) and an adjudication. Every query of the model was a targeted counterexample search, so the finding counts as semi-formal.