This is an automated email from the ASF dual-hosted git repository. jiayu pushed a commit to branch fix/1137-h3-databricks-docs in repository https://gitbox.apache.org/repos/asf/sedona.git
commit a1992236de1782689877298c7a478753ac4fcb3b Author: Jia Yu <[email protected]> AuthorDate: Sun Feb 8 20:01:20 2026 -0800 [GH-1137] Document H3 version conflict workaround on Databricks Databricks Runtime bundles H3 v3.x which conflicts with Sedona's H3 v4.x API, causing NoSuchMethodError when using ST_H3CellIDs and other H3 functions. - Add rm -f /databricks/jars/*h3*.jar to the init script to remove the conflicting JAR before copying Sedona's JARs - Add a 'Known issues' section explaining the H3 conflict and the fix - Rename 'Known bugs' to 'Known issues' for consistency --- docs/setup/databricks.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/setup/databricks.md b/docs/setup/databricks.md index 22f61a71b6..6f70dd19eb 100644 --- a/docs/setup/databricks.md +++ b/docs/setup/databricks.md @@ -76,6 +76,11 @@ cat > /Workspace/Shared/sedona/sedona-init.sh <<'EOF' # # On cluster startup, this script will copy the Sedona jars to the cluster's default jar directory. +# Optional: Remove Databricks' bundled H3 JAR to avoid version conflicts with Sedona's H3 functions. +# Databricks bundles H3 v3.x which is incompatible with Sedona's H3 v4.x API. +# Uncomment the following line if you need to use Sedona's H3 functions (e.g., ST_H3CellIDs). +# rm -f /databricks/jars/*h3*.jar + cp /Workspace/Shared/sedona/{{ sedona.current_version }}/*.jar /databricks/jars EOF @@ -169,6 +174,21 @@ This is what the results look like in Databricks:  -## Known bugs +## Known issues To ensure stability, we recommend using a currently supported Long-Term Support (LTS) version, such as Databricks Runtime 16.4 LTS or 15.4 LTS. Some Databricks Runtimes, such as 16.2 (non-LTS), are not compatible with Apache Sedona, as this particular runtime introduced a change in the json4s dependency. + +### H3 function errors on Databricks + +Databricks Runtime bundles an older version of the H3 library (v3.x) which is incompatible with Sedona's H3 functions (which require H3 v4.x). If you see errors like: + +``` +java.lang.NoSuchMethodError: com.uber.h3core.H3Core.polygonToCells(...) +``` + +when calling `ST_H3CellIDs`, `ST_H3CellDistance`, `ST_H3KRing`, `ST_H3ToGeom`, or other Sedona H3 functions, it means Databricks' bundled H3 library is taking precedence over Sedona's. + +The init script provided above includes an optional fix: uncomment the line `rm -f /databricks/jars/*h3*.jar` to remove the Databricks-bundled H3 JAR before copying Sedona's JARs. This allows Sedona's H3 v4.x to be used instead. + +!!!note + Removing the Databricks-bundled H3 JAR will disable Databricks' built-in H3 SQL expressions (e.g., `h3_coverash3`, `h3_boundaryaswkt`). Sedona provides equivalent H3 functions that can be used as replacements.
