Skip to content

[GH-3257] GeoPandas: Implement distributed hilbert_distance - #3258

Merged
jiayuasu merged 2 commits into
apache:masterfrom
jiayuasu:feature/geopandas-hilbert-distance
Aug 14, 2026
Merged

[GH-3257] GeoPandas: Implement distributed hilbert_distance#3258
jiayuasu merged 2 commits into
apache:masterfrom
jiayuasu:feature/geopandas-hilbert-distance

Conversation

@jiayuasu

Copy link
Copy Markdown
Member

Did you read the Contributor Guide?

Is this PR related to a ticket?

  • Yes, and the PR name follows the format [GH-XXX] my subject.

Closes #3257.
Part of #2230.

What changes were proposed in this PR?

  • Add a native ST_HilbertDistance(geometry, xmin, ymin, xmax, ymax, level) implementation that maps a geometry-envelope midpoint onto a Hilbert curve over a supplied extent.
  • Represent the unsigned 32-bit Hilbert address as a non-negative Long, including the level-16 maximum value 4294967295.
  • Clip midpoint coordinates outside the supplied extent, map zero-width axes to grid coordinate zero, propagate null SQL inputs, reject empty geometries, and preserve GeoPandas-compatible level behavior.
  • Register and expose ST_HilbertDistance through Spark SQL and DataFrame APIs, Flink SQL, Snowflake WKB and GeoJSON UDF paths, and the Python Spark SQL API.
  • Implement distributed GeoSeries.hilbert_distance and GeoDataFrame.hilbert_distance through the active geometry column.
  • Use one eager distributed aggregate to validate geometries and, when total_bounds is omitted, derive the extent of all envelope midpoints. Only the single aggregate row reaches the driver; geometry rows and returned keys remain distributed.
  • Preserve duplicate and MultiIndex indexes, the hilbert_distance result name, explicit-bound behavior, empty-series behavior, and GeoPandas parity without Python UDF execution.
  • Document the SQL function for Spark, Flink, and Snowflake and add the distributed method to the English and Chinese GeoPandas tutorials.

How was this patch tested?

  • Full common test suite: 1,292 tests passed.
  • Focused Spark ST_HilbertDistance suite: 4 tests passed.
  • Focused Flink function test: passed.
  • Snowflake native-function and DDL suites: 4 tests passed.
  • Focused Python GeoPandas, parity, and DataFrame API coverage: 15 tests passed.
  • Regression coverage includes Hilbert-address goldens at levels 2, 3, and 16; the unsigned level-16 maximum; envelope-midpoint bounds; zero-width axes; clipping; null and typed-empty geometries; empty sources; explicit and inferred bounds; level validation; named duplicate and MultiIndex indexes; active-geometry delegation; exactly one metadata action; and the absence of Python execution nodes.
  • The full documentation build, repository formatting checks, and git diff --check passed.
  • The commit passed the repository pre-commit suite.

Did this PR include necessary documentation updates?

  • Yes, I am adding a new API. I used the current SNAPSHOT version, v2.0.0.
  • Yes, I added Spark, Flink, and Snowflake SQL function documentation, release notes, and English and Chinese GeoPandas tutorial updates.

@jiayuasu
jiayuasu marked this pull request as ready for review August 14, 2026 06:16
@jiayuasu jiayuasu added this to the sedona-2.0.0 milestone Aug 14, 2026
@jiayuasu
jiayuasu merged commit 956d361 into apache:master Aug 14, 2026
45 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

GeoPandas: implement distributed hilbert_distance

1 participant