Skip to content

Fix spatial.closest for polygons and measure distances in the layer's units - #498

Open
Andy2003 wants to merge 5 commits into
masterfrom
fix/closest-polygons-and-units
Open

Andy2003 wants to merge 5 commits into
masterfrom
fix/closest-polygons-and-units

Conversation

@Andy2003

@Andy2003 Andy2003 commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

spatial.closest dropped polygons, multipolygons and multilinestrings, and read distanceInKm as degrees on WGS84 layers.

Both spatial.closest and spatial.withinDistance now measure the distance in the layer's units:

Layer Distance
Geographic CRS (WGS84, also with a height axis), or no CRS kilometers, great-circle
Projected CRS, or native points with Cartesian CRS units, planar

Behaviour changes

  • spatial.closest: the distance is in km, not degrees. 1.0 used to mean about 111 km.
  • spatial.closest: returns only geometries within the distance, closest first. It used to return everything in a square around the point.
  • spatial.closest: 0 returns only geometries at the point. It used to search 1 % of the layer's extent.
  • spatial.closest and spatial.withinDistance on projected or Cartesian layers: the distance is in CRS units, not km.
  • The parameter distanceInKm is now distance. Calls are positional, so queries keep working.

Resolves #375

Out of scope

Pre-existing, fixed in separate PRs:

Pre-existing, not addressed here:

  • A coordinate map with x/y keys fails with a NullPointerException; use point({x, y}).
  • Native point layers store no layer CRS, so the procedure reads the CRS from the encoder.

findClosestEdges only snapped to points and line strings and dropped
polygons and multi-geometries. spatial.closest passed distanceInKm as raw
CRS units (degrees for WGS84) and returned everything in the square search
window; it now uses the same km search window as spatial.withinDistance,
keeps geometries within the orthodromic distance and orders them closest
first.
… units

Layers in a geographic CRS (and layers without a CRS) keep kilometers and
orthodromic distance; projected and Cartesian layers use planar distance
in CRS units. The parameter is renamed from distanceInKm to distance.
@Andy2003 Andy2003 self-assigned this Nov 18, 2026
@Andy2003 Andy2003 added the fix Bugfix label Nov 18, 2026
@Andy2003
Andy2003 requested a lite review from Copilot November 18, 2026 18:04

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Approval is blocked by an unresolved antimeridian candidate-window bug that can omit valid nearby geometries, along with inaccurate public API documentation for projected and Cartesian distance units.

2 open issues
What changed in this PR

This PR updates spatial proximity procedures to support all geometry types and interpret distances according to each layer's CRS: great-circle kilometers for geographic layers and planar CRS units for projected or Cartesian layers.

Changes:

  • Reworked spatial.closest to filter by distance and return results closest first.
  • Unified distance handling between spatial.closest and spatial.withinDistance.
  • Updated tests, documentation, examples, and compatibility fixtures for the revised distance semantics.
File Description
server-plugin/​src/​test/​java/​org/​neo4j/​gis/​spatial/​procedures/​SpatialProceduresTest.java Adds coverage for geometry types, CRS-specific distance units, ordering, and zero-distance behavior.
server-plugin/​src/​main/​java/​org/​neo4j/​gis/​spatial/​SpatialTopologyUtils.java Generalizes nearest-point calculations to arbitrary geometries using JTS distance operations.
server-plugin/​src/​main/​java/​org/​neo4j/​gis/​spatial/​procedures/​SpatialProcedures.java Selects geographic or planar distance processing and unifies closest and within-distance behavior.
server-plugin/​src/​main/​java/​org/​neo4j/​gis/​spatial/​pipes/​processing/​Distance.java Adds a shared property name for calculated distances.
server-plugin/​src/​main/​java/​org/​neo4j/​gis/​spatial/​pipes/​GeoPipeline.java Uses the shared distance property when filtering planar searches.
server-plugin/​src/​main/​java/​org/​neo4j/​gis/​spatial/​encoders/​neo4j/​Neo4jCRS.java Exposes geographic CRS classification.
server-plugin/​src/​main/​java/​org/​neo4j/​gis/​spatial/​encoders/​NativePointsEncoder.java Exposes geographic or Cartesian CRS classification for native point arrays.
server-plugin/​src/​main/​java/​org/​neo4j/​gis/​spatial/​encoders/​NativePointEncoder.java Exposes geographic or Cartesian CRS classification for native points.
server-plugin/​src/​main/​java/​org/​neo4j/​gis/​spatial/​Constants.java Adds shared documentation for distance parameter units.
docs/​docs/​modules/​ROOT/​partials/​generated/​api/​spatial/​spatial.withinDistance.adoc Documents the distance parameter and CRS-dependent units for spatial.withinDistance.
docs/​docs/​modules/​ROOT/​partials/​generated/​api/​spatial/​spatial.closest.adoc Documents closest-first ordering and CRS-dependent units for spatial.closest.
docs/​docs/​modules/​ROOT/​partials/​generated/​api/​spatial/​spatial.closest-examples.adoc Updates the closest-procedure example for the revised distance semantics.
docs/​docs/​modules/​ROOT/​partials/​generated/​api/​spatial/​spatial.addWKTs-examples.adoc Updates the generated WKT example distance.
docs/​docs/​modules/​ROOT/​partials/​generated/​api/​index.adoc Updates the generated procedure summary for the revised closest behavior.
doc-examples/​src/​main/​java/​org/​neo4j/​spatial/​doc/​examples/​ApiExampleGenerator.java Updates the source input used to generate API examples.
compat-tests/​src/​test/​resources/​compat/​5.26.0/​expected.txt Updates compatibility expectations for closest results.
compat-tests/​src/​test/​resources/​compat/​5.19.0/​expected.txt Updates compatibility expectations for closest results.
compat-tests/​src/​test/​resources/​compat/​2026.10.0/​expected.txt Updates compatibility expectations for closest results.
compat-tests/​src/​test/​resources/​compat/​2025.07/​expected.txt Updates compatibility expectations for closest results.
compat-tests/​src/​test/​java/​org/​neo4j/​spatial/​compat/​UpgradeCompatibilityTest.java Adjusts compatibility queries for the new distance semantics.

Review effort: Lite

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Test Results

443 tests  +8   421 ✅ +8   2m 58s ⏱️ -17s
 33 suites ±0    22 💤 ±0 
 33 files   ±0     0 ❌ ±0 

Results for commit 74ebc51. ± Comparison against base commit e390381.

♻️ This comment has been updated with latest results.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fix Bugfix

Projects

None yet

Development

Successfully merging this pull request may close these issues.

spatial.closest and spatial.withinDistance results not consistent?

2 participants