PointVectorStrategy sorts a document without a point as if it were 180 units away in a non-geo context

PointVectorStrategy (spatial-extras, @lucene.experimental) stores a point as two numeric doc-values fields. Its makeDistanceValueSource returns vector/DistanceValueSource, which gives a document without a point the fixed value 180 * multiplier in every SpatialContext (DistanceValueSource.java:47) and wraps the distance in DoubleValues.withDefault, so the value always counts as present. In a geo context 180 degrees is the largest possible distance and the document sorts last. In a non-geo (Cartesian) context it is an ordinary distance: an ascending distance sort lists the point-less document before every real document more than 180 units away, and makeRecipDistanceValueSource scores it like a document 180 units away. In the repro (world -1000..1000, query point (0, 0)) the order is near=100, none=180, far=500 instead of near, far, none, and the recip scores are near 0.586, none 0.440, far 0.220. The other distance sources use ctx.isGeo() ? 180 * multiplier : Double.MAX_VALUE, the rule LUCENE-4208 set for all strategies in 2012, and so did this class until LUCENE-7737 ported it to DoubleValuesSource for 7.0.0; the same commit kept the rule in Solr's copy of the class. The missingValue of getSortField(reverse, missingValue) cannot override the value. The strategy's own queries never match a point-less document, but a predicate the caller builds on the distance source (in the run, FunctionMatchQuery with distance < 200) lets it through. Restoring the one line fixes it.

• PointVectorStrategy: a spatial-extras strategy that indexes one point per document as two DoublePoint fields with numeric doc values (x and y). Its class javadoc calls distance sort "the Strategy's best feature".
• SpatialContext: the spatial4j context that defines the world and the distance calculator. A geo context measures great-circle distances in degrees (at most 180); a non-geo (Cartesian) context, SpatialContextFactory.geo = false, measures straight-line distances in the world's own units, with no upper bound but the world size.
• Distance value source: SpatialStrategy.makeDistanceValueSource(point, multiplier) returns a DoubleValuesSource whose value per document is the distance from point times multiplier; it is used for sorting (getSortField) and for the recip score (makeRecipDistanceValueSource, c / (d + c)).
• Null value: the value the source reports for a document that has no indexed shape.

1. PointVectorStrategy.makeDistanceValueSource returns new DistanceValueSource(this, queryPoint, multiplier) (PointVectorStrategy.java:182-185).
2. The constructor sets this.nullValue = 180 * multiplier; whatever the context (DistanceValueSource.java:47).
3. getValues returns DoubleValues.withDefault(<distance * multiplier>, nullValue); the inner advanceExact is ptX.advanceExact(doc) && ptY.advanceExact(doc), false for a document without a point (DistanceValueSource.java:58-84).
4. DoubleValues.withDefault always returns true from advanceExact and then returns the default (DoubleValues.java:71-86), so the sort comparator never sees a missing value and the missingValue of getSortField(reverse, missingValue) is never used (DoubleValuesSource.java:667-716).
5. Geo: 180 times the multiplier is the largest possible distance (for a positive multiplier, as in the one-argument overload and every repro), so the document sorts last. Non-geo: spatial4j's default calculator is Cartesian unless the caller configures another, real distances can be any size, and 180 lands between them.
6. The recip score wraps the same source (SpatialStrategy.java:133-145, ReciprocalDoubleValuesSource.java:61-63), so the document scores c / (180 + c): 0.440 in the repro, against 0.220 for a real document 500 units away.
7. The sibling sources branch on the context: DistanceToShapeValueSource.java:52 (BBoxStrategy, SerializedDVStrategy) and ShapeFieldCacheDistanceValueSource.java:60 (prefix-tree strategies) use ctx.isGeo() ? 180 * multiplier : Double.MAX_VALUE.
8. The strategy's own queries are not affected: the circle query's approximation is the x/y range query (PointVectorStrategy.java:195-198, :209-222), which never matches a document without a point, so the distance check (:283) never sees one; the rectangle query is the same range query (:193-194).
9. A predicate the caller builds on the distance source is affected: FunctionMatchQuery (queries module) matches when advanceExact(doc) && filter.test(doubleValue()) (FunctionMatchQuery.java:98-99), and withDefault answers true with 180. FunctionMatchQuery(dist, d -> d < 200) on the three documents matches near and none on main (assertions on and off), near only with the fix.

• Who is hit. Applications that use PointVectorStrategy with a non-geo SpatialContext, have documents without a point, and sort or score by makeDistanceValueSource / makeRecipDistanceValueSource over a query that also matches those documents (a text query, MatchAllDocsQuery, a filter on other fields), or that filter on the distance source with a predicate of their own. An open upstream issue recommends this strategy "for general 2D" (LUCENE-9689, #10728).
• When it shows. Whenever such a result set also holds real documents more than 180 units from the query point: ordinary in a Cartesian world in metres or other fine units, and possible even in a non-geo world sized like the globe (a point at (170, 80) is 187.88 from the origin and sorts after the point-less document). Deterministic; no index-size threshold (three documents reproduce it); assertions on or off. The JUnit tests use LuceneTestCase's randomized directory, writer config, codec and searcher; the finder's cross-strategy probe, the version-portable probe and the diagram probe use a plain new IndexWriterConfig() (default codec) and new IndexSearcher(reader) and show the same 180 and the same wrong order.
• Opt-in on three counts: the spatial-extras module, the experimental strategy, and a non-geo context (spatial4j's SpatialContextFactory defaults to geo). Nothing else needs configuring.
• Silent. No exception and no log line: the nearest-first page simply has point-less documents ahead of real ones, and a distance boost ranks them like documents 180 units away.
• Not affected. Which documents the strategy's own rectangle and circle queries match; geo contexts; indexes where every document has a point; result sets in which every real document is within 180 units; circle-filtered queries (they exclude point-less documents).
• Caller-built distance filters. A predicate on the distance source, such as FunctionMatchQuery(dist, d -> d < 200), lets the point-less document through today (it sees 180); the fix changes that hit set (executed on main and with the fix).
• Why rare. All of the above must hold, and Solr, the main historical downstream of this strategy style, used its own copy of the class that kept the rule (at the introducing commit; Solr's later history was not traced). No report since 7.0.0 (2017) was found in the recorded 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.vector.TestPointVectorMissingDistanceNonGeo.testDocWithoutPointSortsLastInNonGeoContext(TestPointVectorMissingDistanceNonGeo.java:57)

• The rule was stated by the module's author. LUCENE-4208 (#5280; trunk commit 577e25c7ffc, 2012-09-15, and its 4.x-branch twin 11e5aca556b, the one in the 4.0.0 tag), patch comment: "Standardized behavior of makeDistanceValueSource across the 3 strategies, including null value behavior (it's '180' if geo, Double.MAX_VALUE otherwise)."
• Every other implementation still follows it: DistanceToShapeValueSource.java:52 (BBoxStrategy, SerializedDVStrategy) and ShapeFieldCacheDistanceValueSource.java:60 (prefix-tree strategies). On the same data only PointVectorStrategy in a non-geo context gives 180. (CompositeSpatialStrategy and NumberRangePrefixTreeStrategy do not implement distances; they throw UnsupportedOperationException.)
• This class had the rule from 2012 to 7.0. 4.0.0 to 4.4.0 have isGeo() ? 180 : Double.MAX_VALUE; LUCENE-5118 (trunk 47bf70812ba, 4.x 7677c9e98b7, in 4.5.0) added the multiplier and kept the rule; 6.5.1, 6.6.0 and 6.6.6 pass the repro scenario.
• The drop looks like a slip in a mechanical port (an inference: no commit message, comment or CHANGES line states the intent). LUCENE-7737 (2f2e00ffe23, "Remove spatial-extras dependency on queries module") moved nullValue into the constructor as 180 * multiplier. In the same commit Solr's copy of the class got (strategy.getSpatialContext().isGeo() ? 180 * multiplier : Double.MAX_VALUE). Its CHANGES entry (7.0.0, API Changes) announces the dependency change and the move from ValueSource to DoubleValuesSource extensions, but no behaviour change, and the 21-comment issue thread never mentions missing values.
• Cartesian contexts are documented: the spatial-extras overview lists, among the capabilities of Spatial4j, which the module uses heavily, "Both geospatial contexts and plain 2D Euclidean/Cartesian contexts are supported" (overview.html:40-45; a statement about Spatial4j, not about PointVectorStrategy in particular).
• The tests assume uniform behaviour. TestDistanceStrategy runs all six strategies, PointVectorStrategy included, through one test that adds a document without a shape ("test score for nothing") and expects 180 and a recip score of about 0 (TestDistanceStrategy.java:38-104). It only uses SpatialContext.GEO, which is why the change went unnoticed.
• Core states the same convention for Cartesian points: XYDocValuesField.newDistanceSort, "If a document is missing the field, then by default it is treated as having Double#POSITIVE_INFINITY distance (missing values sort last)" (XYDocValuesField.java:139-140).
• The sort field's missing value cannot opt out: DoubleValues.withDefault hides the missing value from getSortField(reverse, missingValue) (other workarounds exist; see the fix section).

Strongest case for "works as designed" (rated moderate by reviewers): no javadoc gives the missing-document value (SpatialStrategy.java:108-113 is silent); the API speaks of degrees (makeDistanceValueSource(Point) is "a multiplier of 1.0 (i.e. units of degrees)", :101-102); PointVectorStrategy is @lucene.experimental and DistanceValueSource @lucene.internal; the only upstream test of the value uses GEO and expects 180; and no complaint was found in nine years.

Why it fails: the value was a deliberate, stated rule shared by all strategies; the commit that changed it kept the rule in its own Solr copy and announced no behaviour change, so the change looks accidental; Cartesian contexts are documented; the "degrees" wording describes the default geo case; the experimental tags mark API instability rather than license a silent behaviour change; and the sort field's missing value cannot override the value. A maintainer could still prefer to document the current value instead (the documentation-only option). The contract is a design rule and sibling code, not javadoc.

Option A is the one validated; the javadoc sentence is optional and was validated together with it. Workarounds until a fix ships: if point-less documents need not be returned, add new FieldExistsQuery(strategy.getFieldName() + PointVectorStrategy.SUFFIX_X) as a FILTER clause (both public; getFieldNameX() is package-private), which returned near, far when run from a package outside Lucene; otherwise sort first on an application field that marks documents with a location, then by distance, or wrap the distance source in an application DoubleValuesSource that checks the x doc values itself (read, not run).

In the constructor (DistanceValueSource.java:47), use the same expression as DistanceToShapeValueSource and ShapeFieldCacheDistanceValueSource, and as this class before 7.0.

-    this.nullValue = 180 * multiplier;
+    this.nullValue = strategy.getSpatialContext().isGeo() ? 180 * multiplier : Double.MAX_VALUE;

Trade-offs

• Geo contexts keep 180 * multiplier, which TestDistanceStrategy asserts for all six strategies; for any multiplier it restores exactly the pre-7.0 expression.
• In a non-geo context a point-less document sorts last in ascending order and first in descending order, as with the other strategies; its recip score becomes about 0 (7.87E-307), the same as BBoxStrategy's.
• It also changes the hit set of predicates the caller builds on the distance source: FunctionMatchQuery(dist, d -> d < 200) stops matching the point-less document (executed). The strategy's own queries match the same documents as before.
• The same diff applies to the 10.5.2 file, which is byte-identical to main's.

What the checks validated

• Scratch worktree of main a9779ef3c193 with the fix, the javadoc sentence below and the new test, gradle: the new test passes 2 of 2; the whole :lucene:spatial-extras:test passes with assertions on (seed 777B0004) and off (seed 777B0005): 27 suites, 119 tests, 0 failures, 5 skipped by their own @Ignore/@Nightly annotations, including TestDistanceStrategy (12 tests) and TestPointVectorStrategy (4).
• :lucene:spatial-extras:check -x test passes (checkGoogleJavaFormat, ecjLintMain, ecjLintTest, forbiddenApisMain, forbiddenApisTest), after tidy rewrapped the new test's class javadoc; the tidied test passes 2 of 2 again.
• Standalone runner with the patched class shadowed: the new test (assertions on and off), the finder's test (2 of 2) and the independent reproducer's (5 of 5) pass.

Add to the javadoc of makeDistanceValueSource(Point, double) (SpatialStrategy.java:108-112): "A document without an indexed shape gets {@code 180 * multiplier} (the largest geo distance) if the context is geo, and {@link Double#MAX_VALUE} otherwise."

Trade-offs

Turns the issue-level rule into a documented contract that a test can pin. True of every implementation once the fix is in (Composite and NumberRangePrefixTree throw).

What the checks validated

Applied together with the fix in the runs above.

Matches core's XYDocValuesField.newDistanceSort convention; the recip score becomes exactly 0. Not run.

Trade-offs

Differs from the two sibling sources (Double.MAX_VALUE), so one consistent rule would mean changing all three; no benefit for sorting.

Not run; a coherent alternative contract (an explicit missingValue would then work), but not recommended here.

Trade-offs

The one-argument getSortField(reverse) uses a missingValue of 0 (DoubleValuesSource.java:111-112), so by default point-less documents would sort first; it also changes the geo value TestDistanceStrategy asserts and makes this strategy differ from the others again.

The direction LUCENE-5804 (#6866, open since 2014) proposed for all strategies. Not run.

Trade-offs

A larger refactor; not needed for this bug.

State the current value on SpatialStrategy.makeDistanceValueSource and PointVectorStrategy. Not run.

Trade-offs

Defensible if maintainers do not treat the LUCENE-4208 rule as a contract, but this strategy then keeps differing from the others in non-geo contexts, and the wrong order stays.

Method: semi-formal (the hunt's tier for tool-guided finds that are not a formal tool's own output): a hunt unit (reference semantics for the spatial-extras recip-distance and shape value sources), 2026-10-27, stock main jars.

• While writing the reference for the missing-document value of makeDistanceValueSource, the finder read the three distance sources and saw that vector/DistanceValueSource alone has no isGeo() branch.
• A bounded cross-strategy differential probe ran PointVectorStrategy, BBoxStrategy, SerializedDVStrategy and RecursivePrefixTreeStrategy, each in a geo and a Cartesian context, on the same two documents: seven of the eight combinations agree (180 in geo, Double.MAX_VALUE in Cartesian, far before none); only PointVectorStrategy in the Cartesian context gives 180.0 and sorts none first.
• It was then reduced to a public-API JUnit and checked by an independent reproducer, reviews by another model family, a devil's advocate, an adjudication, the version-history runs and an audit (see the checks).