SortedNumericSortField's javadoc on main suggests STRING_FIRST / STRING_LAST for missing values, but a numeric sort cannot use them

On main, the class javadoc of SortedNumericSortField says: "Like sorting by string, this also supports sorting missing values as first or last, via {@link SortField#STRING_FIRST} or {@link SortField#STRING_LAST}." Those two constants are markers for string sorts. A numeric SortedNumericSortField (INT, LONG, FLOAT or DOUBLE) accepts them without complaint, because its 5-argument constructor stores any Object as the missing value, and then the first search or index-sort setup casts the value to Integer, Long, Float or Double and throws ClassCastException.

The code is correct and intended: a numeric sort takes a number of its own type as the missing value (Long.MIN_VALUE / Long.MAX_VALUE to sort missing documents first / last), as the migration guide and the upstream tests show. The sentence came in with #15486, which removed setMissingValue and replaced the old pointer "via setMissingValue(Object)" with the two string markers in both SortedNumericSortField and SortedSetSortField; that is correct only for SortedSetSortField. Main only: no release has the sentence. The proposal is a javadoc fix, optionally with a constructor type check that fails fast.

1. The javadoc names the string markers. SortedNumericSortField.java:44-45: "Like sorting by string, this also supports sorting missing values as first or last, via {@link SortField#STRING_FIRST} or {@link SortField#STRING_LAST}." The constructor's @param missingValue says only "the sort value to use for documents with no value in the field" (:97).
2. No type check on the way in. The 5-argument constructor calls super(field, SortField.Type.CUSTOM, reverse, missingValue) and stores the object (:99-114). SortField.validateField checks the missing value only for Type.STRING (SortField.java:337-349, the check at :343-348).
3. The markers are plain objects. SortField.java:309-325: STRING_FIRST and STRING_LAST are anonymous Object instances (hence SortField$1 / SortField$2 in the message), documented as "Pass this as a missingValue constructor parameter to have missing string values sort first/last".
4. First use casts to the numeric type. getComparator passes (Integer) missingValue, (Float), (Long) or (Double) to the comparator (:272, :294, :316, :338); getIndexSorter does the same (:380, :383, :386, :389); IndexWriterConfig.setIndexSort calls getIndexSorter() on every sort field (IndexWriterConfig.java:505-510). So the index sort fails at configuration time, before any document is indexed.
5. What a numeric missing value means. The comparators substitute it for absent values and use 0 when it is null (comparators/LongComparator.java:37, likewise for Int, Float and Double), so Long.MIN_VALUE / Long.MAX_VALUE sort missing documents first / last and reverse flips that (upstream TestIndexSorting.testMissingMultiValuedLongFirst runs both directions).
6. Why the same sentence is right in SortedSetSortField. That class reads the missing value only as one of the two markers (SortedSetSortField.java:128-130, :176, :191).
7. Type-safe entry points exist. LongField.newSortField(field, reverse, selector, long missingValue) (document/LongField.java:186-189) and its Int, Float and Double counterparts take a primitive, so they cannot get the wrong type.

The late ClassCastException for a wrong-typed missing value is old and general: it was executed on 9.12.3 and 10.3.2 (through setMissingValue(STRING_LAST)) and on 10.4.0 and 10.5.2 (through the 5-argument constructor), and plain new SortField(f, SortField.Type.LONG, false, SortField.STRING_LAST) behaves the same on main and 10.5.2. On those releases the javadoc did not suggest the markers. Only the sentence is new.

• Who. Users of main who read this class javadoc to sort missing values first or last on a numeric SortedNumericSortField.
• Default vs opt-in. The input shape is opt-in (a string marker as the missing value of a numeric sort) and only this sentence suggests it; everything else is default: IndexWriterConfig, codec and IndexSearcher, assertions on or off. The cast fails before any doc values are read, so no codec or setting avoids it.
• What goes wrong. An immediate ClassCastException on each search with that sort, or from IndexWriterConfig.setIndexSort before an IndexWriter exists. Nothing hangs and nothing is written; the exception comes before any hit is collected, so no wrongly ordered result is returned.
• Scale. Any index size; one document is enough.
• Why fix it before 11.0. setMissingValue is gone on main, so a SortedNumericSortField gets its missing value only at construction: through this 5-argument constructor, whose class javadoc is where users look for how, or through typed helpers such as LongField.newSortField(field, reverse, selector, long missingValue), which cannot take a marker. 11.0.0 would be the first release with the sentence.

• Reproducible. One document, no random input on the failing path. The test framework randomizes the codec, locale and time zone from the seed (the gradle run used Asserting(Lucene104)), but the cast fails in getComparator before any doc values are read, so the outcome does not depend on them. Run with seed DEADBEEF (and 5EED1234 standalone), assertions on and off: same failure.
• It transcribes the current javadoc. With option A (javadoc only) it keeps failing (executed) and becomes obsolete, because the documented contract changes. With option B it passes unchanged, so it is the regression test for B.
• Format. google-java-format (./gradlew tidy) wraps the constructor call over five lines (whitespace only).
• Index-sort path. new IndexWriterConfig().setIndexSort(new Sort(sortField)) throws the same exception from getIndexSorter (SortedNumericSortField.java:382) <- IndexWriterConfig.setIndexSort (IndexWriterConfig.java:507), before any document is indexed (executed on 645d4fe14a20 by the finder's two-method test, 2026-10-29); the minimal test keeps only the search path.

cp $REPRO/TestSortedNumericSortFieldStringLast.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/
cd $LUCENE
./gradlew :lucene:core:test --tests org.apache.lucene.search.TestSortedNumericSortFieldStringLast -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off: -Ptests.asserts=false (same failure)

# gradle, main 645d4fe14a20, seed DEADBEEF, -Ptests.asserts=true
TestSortedNumericSortFieldStringLast > testStringLastMissingValue FAILED
    java.lang.AssertionError: class javadoc: STRING_LAST sorts missing values last (or the constructor should reject it); actual: java.lang.ClassCastException: class org.apache.lucene.search.SortField$2 cannot be cast to class java.lang.Long (org.apache.lucene.search.SortField$2 is in unnamed module of loader 'app'; java.lang.Long is in module java.base of loader 'bootstrap')
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:F511CF93BA407CCF]:0)
        at org.apache.lucene.search.TestSortedNumericSortFieldStringLast.testStringLastMissingValue(TestSortedNumericSortFieldStringLast.java:44)
        Caused by:
        java.lang.ClassCastException: class org.apache.lucene.search.SortField$2 cannot be cast to class java.lang.Long (...)
            at org.apache.lucene.search.SortedNumericSortField.getComparator(SortedNumericSortField.java:315)
            at org.apache.lucene.search.FieldValueHitQueue.create(FieldValueHitQueue.java:146)
            at org.apache.lucene.search.TopFieldCollectorManager.newCollector(TopFieldCollectorManager.java:114)
            at org.apache.lucene.search.TopFieldCollectorManager.newCollector(TopFieldCollectorManager.java:29)
            at org.apache.lucene.search.IndexSearcher.search(IndexSearcher.java:752)
            at org.apache.lucene.search.IndexSearcher.searchAfter(IndexSearcher.java:735)
            at org.apache.lucene.search.IndexSearcher.search(IndexSearcher.java:678)
            at org.apache.lucene.search.TestSortedNumericSortFieldStringLast.testStringLastMissingValue(TestSortedNumericSortFieldStringLast.java:42)
1 test completed, 1 failed
# -Ptests.asserts=false: the same failure, same frames
# option A (javadoc only, reworded): checkGoogleJavaFormat and renderJavadoc pass; the test still fails (executed; comment-only change)
# option B (javadoc + constructor check): the test passes, assertions on and off; TestSortedNumericSortField 9/9, TestIndexSorting 62/62 (first run: 184 core + 42 queries tests)

• Contract. SortedNumericSortField.java:44-45 (quoted above). A user who follows it violates no precondition stated on the class.
• History. The sentence dates from LUCENE-5748 (2014) with "via {@link #setMissingValue(Object)}": 398af4596bd on trunk (first released in 6.0.0) and its branch_4x counterpart d1522d5fe78 (first released in 4.9.0). #15486 (f4f6d70c0c4, 2025-12-09) changed that one javadoc line and removed the setMissingValue override in this class; the constructor, getComparator, getIndexSorter and the serialization were not touched. The javadoc was not discussed in #15480, #15483, #15486 or #15720.
• Every other source says numeric. SortField.java:309, :318 (the markers are for "missing string values"); lucene/MIGRATE.md:258-278, which shows new SortedNumericSortField("price", SortField.Type.LONG, false, SortedNumericSelector.Type.MIN, 0L) (:273-274) and STRING_LAST only for SortedSetSortField (:276-277); TestSortedNumericSortField.testMissingFirst / testMissingLast with Integer.MIN_VALUE / Integer.MAX_VALUE (TestSortedNumericSortField.java:158, :194); no upstream test pairs the markers with SortedNumericSortField.
• A sibling class states the rule. ToParentBlockJoinSortField (join module): "For numeric types use the corresponding boxed type (e.g. {@link Integer} for Type.INT)" (ToParentBlockJoinSortField.java:139-142), and it validates that (:166-198, #15727).

The strongest case for "intended": numeric sorts take a number, the markers are documented for strings, a wrong-typed Object missing value has always failed late (executed on 9.12.3, 10.3.2, 10.4.0 and 10.5.2), and plain SortField behaves the same, so this is user error.

Why it fails: it defends the code, not the sentence. The javadoc of the very class being called tells users to pass the markers, so following the documentation produces the exception. That is why this is a javadoc defect, and why a constructor type check is an optional usability improvement, not a regression fix. (Such a check would be new here: this class's own setMissingValue override never validated the value.)

Three options. A and B were applied in a scratch worktree of main 645d4fe14a20 and run with gradle; C was not built. A's wording was revised after the fact checks (the first draft was too broad) and both were re-run with it. A is the proposal, because the code is intended and only the sentence is wrong; B is a compatible extra that turns the late ClassCastException into an early, clear error.

Replace the sentence (SortedNumericSortField.java:44-45) with the numeric rule, naming the four supported types. Optionally extend the constructor's @param missingValue (:97) the same way (not run).

- * <p>Like sorting by string, this also supports sorting missing values as first or last, via {@link
- * SortField#STRING_FIRST} or {@link SortField#STRING_LAST}.
+ * <p>Documents without a value sort as the {@code missingValue} passed to the constructor, or as 0
+ * when it is null. It must match {@code type}: an {@link Integer} for {@code Type.INT}, a {@link
+ * Long} for {@code Type.LONG}, a {@link Float} for {@code Type.FLOAT} or a {@link Double} for
+ * {@code Type.DOUBLE}. To sort them first or last, pass a value that sorts before or after every
+ * value in the field, for example {@link Long#MIN_VALUE} or {@link Long#MAX_VALUE} (the other way
+ * round when {@code reverse} is true). {@link SortField#STRING_FIRST} and {@link
+ * SortField#STRING_LAST} cannot be used here.

Trade-offs

• No behaviour change; it states what the code, the migration guide and the upstream tests already do, close to the wording ToParentBlockJoinSortField uses for its numeric missing values. It does not catch a wrong-typed value early: a marker still fails at first use, now against clear documentation.
• It names only the four types the class supports (any other type throws AssertionError in getComparator / getIndexSorter, :361-362, :396-397), and it does not call the markers "for string sorts only": BinarySortField takes them too (BinarySortField.java:31-40, :95-97), as does SortField with Type.STRING_VAL.
• A document whose value equals the chosen value sorts together with the missing documents (ties fall back to the next sort field, then the doc id). For FLOAT and DOUBLE the comparators use Float.compare / Double.compare, which order NaN after positive infinity, so POSITIVE_INFINITY does not sort missing documents after NaN values.

What the checks validated

• Gradle, fresh scratch worktree of 645d4fe14a20 (2026-11-01, after the fact checks): :lucene:core:applyGoogleJavaFormat produced the wrapping shown; checkGoogleJavaFormat and renderJavadoc pass; the rendered paragraph's links to Integer, Long, Float, Double, Long.MIN_VALUE, Long.MAX_VALUE, SortField.STRING_FIRST and SortField.STRING_LAST resolve.
• With the change applied, the minimal test still fails with the same ClassCastException (executed, seed DEADBEEF, assertions on), as expected for a comment-only change: it transcribes the old sentence and becomes obsolete; no test is needed for this change.
• The brief's first draft of this text ("must be of the boxed type that matches type", markers "for string sorts such as SortedSetSortField only") was too broad for the reasons above and is replaced.

In the 5-argument constructor, for the four numeric types, reject a non-null missing value whose class does not match the type, with IllegalArgumentException, as ToParentBlockJoinSortField does for its child missing value (#15727).

     if (type == null) {
       throw new NullPointerException();
     }
+    if (missingValue != null) {
+      Class<?> expected =
+          switch (type) {
+            case INT -> Integer.class;
+            case LONG -> Long.class;
+            case FLOAT -> Float.class;
+            case DOUBLE -> Double.class;
+            // $CASES-OMITTED$
+            default -> null;
+          };
+      if (expected != null && expected.isInstance(missingValue) == false) {
+        throw new IllegalArgumentException(
+            "Missing value for Type."
+                + type
+                + " must be a "
+                + expected.getName()
+                + ", got "
+                + missingValue);
+      }
+    }
     this.selector = selector;
     this.type = type;
   }

Trade-offs

• For INT, LONG, FLOAT and DOUBLE, moves the failure of a wrong-typed missing value from the first search or setIndexSort to construction, with a clear message. It checks only those four: for any other type the default branch yields null, no check runs, and the sort still fails at first use with the AssertionError of getComparator / getIndexSorter. A wrong-typed value always failed at first use already, so only a sort that is built but never used would newly fail; still worth a CHANGES entry.
• Every in-tree caller passes the matching type (LongField.newSortField and its siblings, the MultiValued*FieldSource classes, the tests), and the core and queries tests below pass.
• Plain new SortField(f, SortField.Type.LONG, false, SortField.STRING_LAST) has the same late failure and is not covered; a general check would belong in SortField.validateField (a wider change, not run).

What the checks validated

• Re-run with the reworded javadoc (the check code is unchanged) in the fresh scratch worktree (2026-11-01): checkGoogleJavaFormat, ecjLintMain (executed, not up to date) and renderJavadoc pass on :lucene:core; the minimal test passes with assertions on and off (the constructor rejects STRING_LAST); TestSortedNumericSortField (9) and TestIndexSorting (62) pass, assertions on.
• The brief's first run, with the first-draft javadoc and the same check code, seed DEADBEEF, assertions on: 9 core suites, 184 tests, 0 failures (TestSortedNumericSortField (9), TestIndexSorting (62), TestIndexSortSortedNumericDocValuesRangeQuery (29), TestDocValuesQueries (41), TestSortedNumericDocValuesUpdates (19), TestLucene99SegmentInfoFormat (17), TestSortingCodecReader (3), TestSegmentReordering (3) and the minimal test (1)), plus :lucene:queries TestValueSources (41) and TestDocValuesFieldSources (1).

Translate STRING_FIRST / STRING_LAST in the constructor into the type's extreme value, taking reverse into account, so that the current sentence becomes true.

Trade-offs

• A new feature rather than a fix: getMissingValue, equals, toString and serialization would see the translated number, floats and doubles need a choice (infinities), and real extreme values tie with missing documents.
• Overlaps the typed newSortField helpers on IntField / LongField / FloatField / DoubleField. Not built or run.

• Lead. The unit's list of contract lines for SortedNumericSortField named STRING_FIRST / STRING_LAST for missing values, taken from the class javadoc.
• Probe. A small program built the sort with STRING_LAST and ran a search and an index sort: both threw ClassCastException (SortField$2 cannot be cast to Long).
• JUnit. A public-API test failed 2 of 2 on main with assertions on and off, and the same way on 10.5.2 (behaviour only: there the javadoc points to setMissingValue).
• Verification. A cross-model review (OpenAI GPT-5.6), an independent reproducer, a cross-model adversary, an intended-behaviour devil's advocate and an adjudication followed; all classify it as a documentation defect.