[GH-908] Add ST_GeoHashNeighbors and ST_GeoHashNeighbor functions #2628

jiayuasu · 2026-02-08T09:12:54Z

Did you read the Contributor Guide?

Yes, I have read the Contributor Rules and Contributor Development Guide

Is this PR related to a ticket?

Yes, and the PR name follows the format [GH-XXX] my subject. Closes Geohash neighbours geohashes util #908

What changes were proposed in this PR?

ST_GeoHashNeighbors(geohash): Returns an array of 8 neighboring geohash cells (N, NE, E, SE, S, SW, W, NW)
ST_GeoHashNeighbor(geohash, direction): Returns a single neighbor in the given direction (n, ne, e, se, s, sw, w, nw, case-insensitive)

Algorithm ported from geohash-java (Apache 2.0 license).

How was this patch tested?

9 common unit tests covering known values, all 8 neighbors, circular movement, case insensitivity, null/empty/invalid inputs
Spark SQL functional tests
Flink SQL functional tests
Snowflake tester tests (TestFunctions + TestFunctionsV2)

Did this PR include necessary documentation updates?

Yes, I am adding a new API. I am using the current SNAPSHOT version number in vX.Y.Z format.

Copilot

Pull request overview

Adds geohash-neighboring functionality across Sedona’s common library and exposes it through Spark, Flink, Snowflake, and Python APIs, with accompanying docs and tests.

Changes:

Introduces geohashNeighbors / geohashNeighbor in the common module and wires them into Spark/Flink/Snowflake/Python function catalogs.
Extends Spark’s inferred expression typing to support Array[String] round-tripping.
Adds unit/functional tests and API documentation for the two new functions.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
spark/common/src/test/scala/org/apache/sedona/sql/functionTestScala.scala	Adds Spark SQL tests for the new geohash neighbor functions (including null handling).
spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala	Exposes new functions in the Spark Scala API (`st_functions`).
spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/InferredExpression.scala	Adds inferred typing/serialization support for `Array[String]` results.
spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala	Adds Spark expression wrappers for the new functions.
spark/common/src/main/scala/org/apache/sedona/sql/UDF/Catalog.scala	Registers the new Spark SQL functions in the catalog.
snowflake/src/main/java/org/apache/sedona/snowflake/snowsql/UDFsV2.java	Adds Snowflake V2 UDF bindings for the new functions.
snowflake/src/main/java/org/apache/sedona/snowflake/snowsql/UDFs.java	Adds Snowflake UDF bindings for the new functions.
snowflake-tester/src/test/java/org/apache/sedona/snowflake/snowsql/TestFunctionsV2.java	Adds Snowflake V2 tests for the new functions.
snowflake-tester/src/test/java/org/apache/sedona/snowflake/snowsql/TestFunctions.java	Adds Snowflake tests for the new functions.
python/sedona/spark/sql/st_functions.py	Adds Python API wrappers + docstrings for the new functions.
flink/src/test/java/org/apache/sedona/flink/FunctionTest.java	Adds Flink SQL tests for neighbors + null handling.
flink/src/main/java/org/apache/sedona/flink/expressions/Functions.java	Adds Flink ScalarFunctions for the new geohash APIs.
flink/src/main/java/org/apache/sedona/flink/Catalog.java	Registers new functions in Flink’s catalog.
docs/api/sql/Function.md	Documents the new SQL functions (Spark).
docs/api/snowflake/vector-data/Function.md	Documents the new Snowflake functions.
docs/api/flink/Function.md	Documents the new Flink SQL functions.
common/src/test/java/org/apache/sedona/common/FunctionsTest.java	Adds common-module unit tests for neighbors and edge cases.
common/src/main/java/org/apache/sedona/common/utils/PointGeoHashEncoder.java	Refactors to reuse shared geohash constants.
common/src/main/java/org/apache/sedona/common/utils/GeoHashUtils.java	Introduces shared base32/bit constants + decode lookup table.
common/src/main/java/org/apache/sedona/common/utils/GeoHashNeighbor.java	Implements the neighbor computation algorithm.
common/src/main/java/org/apache/sedona/common/utils/GeoHashDecoder.java	Refactors to reuse shared geohash constants.
common/src/main/java/org/apache/sedona/common/Functions.java	Exposes the new neighbor functions from the common API.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

common/src/main/java/org/apache/sedona/common/utils/GeoHashNeighbor.java

...k/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/InferredExpression.scala

snowflake-tester/src/test/java/org/apache/sedona/snowflake/snowsql/TestFunctionsV2.java

snowflake-tester/src/test/java/org/apache/sedona/snowflake/snowsql/TestFunctions.java

spark/common/src/test/scala/org/apache/sedona/sql/functionTestScala.scala

Implements #908: Adds two geohash neighbor functions across all platforms: - ST_GeoHashNeighbors(geohash): returns array of 8 neighboring geohash cells - ST_GeoHashNeighbor(geohash, direction): returns single neighbor in given direction (n, ne, e, se, s, sw, w, nw, case-insensitive) Algorithm ported from geohash-java (Apache 2.0 license). Platforms: Spark SQL, Flink SQL, Snowflake, Python. Added Array[String] support to InferredExpression. Tests: common unit tests, Spark SQL tests, Flink tests. Docs: Spark, Flink, Snowflake API documentation.

…eoHashNeighbor - Add ST_GeoHashNeighbors and ST_GeoHashNeighbor tests to dataFrameAPITestScala - Add Python SQL tests in test_function.py (neighbors array + neighbor direction) - Add Python DataFrame API tests in test_dataframe_api.py (test_configurations + wrong_type_configurations)

Recent Python/uv versions no longer bundle setuptools by default, causing 'ModuleNotFoundError: No module named pkg_resources' in CI.

- Pin uv version to 0.9.22 in python.yml, pyflink.yml, docs.yml, python-wheel.yml to avoid GitHub API lookup failures (ECONNREFUSED) - Add setuptools install after second uv sync in python.yml (the 'Run basic tests without rasterio' step)

setuptools (providing pkg_resources) is needed by keplergl and other dependencies at runtime. Adding it to [dependency-groups] dev ensures uv sync always includes it, eliminating the need for manual 'uv pip install setuptools' calls that could be undone by subsequent uv sync operations.

setuptools 82.0.0 removed pkg_resources entirely. keplergl still imports from pkg_resources at module level, causing ModuleNotFoundError during pytest collection. Pin setuptools>=69,<82 in dev deps and remove the now-unnecessary 'uv pip install setuptools' lines from CI workflows.

Copilot

Pull request overview

Copilot reviewed 30 out of 31 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

common/src/main/java/org/apache/sedona/common/utils/GeoHashUtils.java

...k/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/InferredExpression.scala

spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala

common/src/main/java/org/apache/sedona/common/Functions.java

…tests

github-actions bot added sedona-python docs sedona-flink sedona-common sedona-spark sedona-snowflake root labels Feb 8, 2026

jiayuasu marked this pull request as draft February 8, 2026 09:15

jiayuasu force-pushed the feature/908-geohash-neighbors branch from 38ad3fa to 1f78010 Compare February 8, 2026 10:17

jiayuasu requested a review from Copilot February 8, 2026 10:23

Copilot AI reviewed Feb 8, 2026

View reviewed changes

jiayuasu force-pushed the feature/908-geohash-neighbors branch from 1f78010 to a2179e5 Compare February 8, 2026 19:47

jiayuasu added 2 commits February 8, 2026 12:40

Fix CI: install setuptools to provide pkg_resources module

38d1b29

Recent Python/uv versions no longer bundle setuptools by default, causing 'ModuleNotFoundError: No module named pkg_resources' in CI.

github-actions bot added the github_actions Pull requests that update GitHub Actions code label Feb 8, 2026

jiayuasu added 5 commits February 8, 2026 12:51

Fix CI: install setuptools in pyflink and python-extension workflows

a1fdc83

Fix: add uv pip install setuptools right before pytest calls

97cb254

jiayuasu marked this pull request as ready for review February 9, 2026 05:32

Fix Spotless formatting in Snowflake test files

6ee8f56

jiayuasu requested a review from Copilot February 9, 2026 07:52

Copilot AI reviewed Feb 9, 2026

View reviewed changes

jiayuasu added 2 commits February 9, 2026 01:30

Address PR review comments: encapsulation, perf, overloads, JavaDoc, …

2617d34

…tests

Revert uv version pin

bc46f6a

jiayuasu force-pushed the feature/908-geohash-neighbors branch from af0f466 to bc46f6a Compare February 9, 2026 09:34

github-actions bot removed the github_actions Pull requests that update GitHub Actions code label Feb 9, 2026

jiayuasu merged commit 18f30ca into master Feb 9, 2026
48 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[GH-908] Add ST_GeoHashNeighbors and ST_GeoHashNeighbor functions #2628

[GH-908] Add ST_GeoHashNeighbors and ST_GeoHashNeighbor functions #2628

Uh oh!

jiayuasu commented Feb 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

[GH-908] Add ST_GeoHashNeighbors and ST_GeoHashNeighbor functions #2628

[GH-908] Add ST_GeoHashNeighbors and ST_GeoHashNeighbor functions #2628

Uh oh!

Conversation

jiayuasu commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Did you read the Contributor Guide?

Is this PR related to a ticket?

What changes were proposed in this PR?

How was this patch tested?

Did this PR include necessary documentation updates?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jiayuasu commented Feb 8, 2026 •

edited

Loading