Repository navigation
Conversation
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.
There was a problem hiding this comment.
🟡 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.closestto filter by distance and return results closest first. - Unified distance handling between
spatial.closestandspatial.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
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


spatial.closestdropped polygons, multipolygons and multilinestrings, and readdistanceInKmas degrees on WGS84 layers.Both
spatial.closestandspatial.withinDistancenow measure the distance in the layer's units:CartesianBehaviour changes
spatial.closest: the distance is in km, not degrees.1.0used 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:0returns only geometries at the point. It used to search 1 % of the layer's extent.spatial.closestandspatial.withinDistanceon projected or Cartesian layers: the distance is in CRS units, not km.distanceInKmis nowdistance. Calls are positional, so queries keep working.Resolves #375
Out of scope
Pre-existing, fixed in separate PRs:
Pre-existing, not addressed here:
x/ykeys fails with a NullPointerException; usepoint({x, y}).