[GH-3020] Add ST_H3ToParent

[jjj-n]

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-3020] Add ST_H3ToParent.

Related to #3020.

This PR intentionally implements only ST_H3ToParent as the first incremental part of the H3 hierarchy functions requested in #3020. It does not close the parent issue.

What changes were proposed in this PR?

• Add a common Java implementation of ST_H3ToParent backed by H3's cellToParent.
• Register the function in the Spark SQL expression catalog.
• Add Scala and Python DataFrame API wrappers.
• Register the function as a Flink SQL scalar function.
• Add Common, Spark SQL, Scala DataFrame API, Python, and Flink tests.
• Document the new API for both Spark SQL and Flink.

The function accepts an H3 cell and a target parent resolution and returns the corresponding parent H3 cell. Null inputs are propagated by the SQL integrations.

How was this patch tested?

• mvn spotless:apply
• mvn -pl common -Dtest=FunctionsTest#h3ToParent test
• Spark Common production and test source compilation
• mvn -pl spark/common -DwildcardSuites=org.apache.sedona.sql.functions.STH3Functions org.scalatest:scalatest-maven-plugin:2.2.0:test
  • 6 tests passed, including the new parent-resolution, ancestor-relation, and null-propagation assertions
• mvn -pl flink -Dtest=FunctionTest#testH3ToParent test
  • 1 test passed
• python -m py_compile python/sedona/spark/sql/st_functions.py python/tests/sql/test_function.py python/tests/sql/test_dataframe_api.py
• git diff --check

The Python Spark integration tests were not run locally because PySpark is not installed in the local Python environment. The corresponding Python files passed bytecode compilation, and the underlying Spark SQL expression was covered by the JVM Spark test suite.

Did this PR include necessary documentation updates?

• Yes, I am adding a new API and using the current SNAPSHOT version number v2.0.0.
• Yes, I have added the Spark SQL and Flink function pages and updated both API catalogs.

[jiayuasu]

Thank you!