[GH-1327] Add Bing Tile functions

[jiayuasu]

Did you read the Contributor Guide?

• Yes, I have read the Contributor Rules and Contributor Developer Guide

Is this PR related to a ticket?

• Yes, and the PR name follows the format [GH-XXX] my subject. Closes Add Support for Bing Tile functions #1327

What changes were proposed in this PR?

Adds 9 Bing Tile functions for working with Bing Maps tile coordinates. The functions convert between geographic coordinates and Bing tile quad-keys, and support spatial queries over tile grids.

New Functions

Function	Description
ST_BingTile(tileX, tileY, zoomLevel)	Create a Bing tile quad-key from tile XY coordinates and zoom level
ST_BingTileAt(longitude, latitude, zoomLevel)	Return the quad-key of the tile covering a lon/lat point at a given zoom
ST_BingTilesAround(longitude, latitude, zoomLevel)	Return the 9 quad-keys surrounding (and including) a point
ST_BingTileZoomLevel(quadKey)	Extract the zoom level from a quad-key
ST_BingTileX(quadKey)	Extract the tile X coordinate from a quad-key
ST_BingTileY(quadKey)	Extract the tile Y coordinate from a quad-key
ST_BingTilePolygon(quadKey)	Return the bounding-box polygon of a tile as a Geometry
ST_BingTileCellIDs(geometry, zoomLevel)	Return all quad-keys whose tiles are covered by a geometry
ST_BingTileToGeom(quadKeys)	Return a GeometryCollection built from the polygons of a quad-key array

Design Decisions

• Quad-key string representation: Tiles are identified by quad-key strings (e.g., "123") rather than a custom BingTile type, for compatibility with all Sedona engines.
• Longitude-first parameter order: ST_BingTileAt and ST_BingTilesAround take (longitude, latitude, zoomLevel), consistent with Sedona's existing ST_Point(x, y) convention.
• Optimized covering algorithm: ST_BingTileCellIDs uses brute-force enumeration for zoom < 10 and recursive quadtree subdivision from zoom 10 for higher zoom levels, balancing simplicity and performance.

Modules Changed

• common: Core implementation in BingTile.java utility class; public API in Functions.java
• spark: Expression classes (Functions.scala), DataFrame API (st_functions.scala), UDF catalog (Catalog.scala)
• flink: Catalog and expression registration
• snowflake: UDFs.java (WKB binary I/O) and UDFsV2.java (GeoJSON String I/O)
• python: PySpark bindings in st_functions.py
• docs: API reference for Spark, Flink, and Snowflake

How was this patch tested?

Tests across all engines, using reference values from Trino's TestBingTileFunctions:

• common: 31 unit tests in FunctionsTest.java covering all functions, edge cases (antimeridian, poles, max zoom), and error cases
• spark SQL: 23 tests in STBingTileFunctions.scala
• spark DataFrame API: 16 tests in dataFrameAPITestScala.scala
• flink: 9 tests in FunctionTest.java
• snowflake: 9 tests each in TestFunctions.java (V1) and TestFunctionsV2.java (V2)

mvn test -pl common -Dtest="org.apache.sedona.common.FunctionsTest#testBingTile*" -DfailIfNoTests=false
mvn test -pl spark/common -Dsuites=org.apache.sedona.sql.functions.STBingTileFunctions -DfailIfNoTests=false

Did this PR include necessary documentation updates?

• Yes, API documentation has been added to Spark, Flink, and Snowflake Function.md pages.

[Copilot]

Pull request overview

This PR adds comprehensive Bing Tile functionality to Apache Sedona, addressing issue #1327. The implementation provides 9 functions for working with Bing Maps tile coordinates, enabling conversion between geographic coordinates and Bing tile quad-keys, as well as spatial queries over tile grids.

Changes:

• Adds core BingTile utility class with coordinate conversion, validation, and spatial query algorithms
• Implements 9 public API functions: ST_BingTile, ST_BingTileAt, ST_BingTilesAround, ST_BingTileZoomLevel, ST_BingTileX, ST_BingTileY, ST_BingTilePolygon, ST_BingTileCellIDs, and ST_BingTileToGeom
• Provides complete integration across Spark, Flink, Snowflake, and Python with comprehensive test coverage (31 common tests, 23 Spark SQL, 16 Spark DataFrame, 9 Flink, 18 Snowflake tests)

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
common/src/main/java/org/apache/sedona/common/utils/BingTile.java	Core implementation of Bing Tile system with coordinate conversions and spatial queries
common/src/main/java/org/apache/sedona/common/Functions.java	Public API functions for Bing Tile operations
common/src/test/java/org/apache/sedona/common/FunctionsTest.java	Comprehensive unit tests covering all functions and edge cases
spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala	Spark expression classes for Bing Tile functions
spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala	Spark DataFrame API bindings
spark/common/src/main/scala/org/apache/sedona/sql/UDF/Catalog.scala	Spark function catalog registration
spark/common/src/test/scala/org/apache/sedona/sql/functions/STBingTileFunctions.scala	Spark SQL tests
spark/common/src/test/scala/org/apache/sedona/sql/dataFrameAPITestScala.scala	Spark DataFrame API tests
flink/src/main/java/org/apache/sedona/flink/expressions/Functions.java	Flink function implementations
flink/src/main/java/org/apache/sedona/flink/Catalog.java	Flink function catalog registration
flink/src/test/java/org/apache/sedona/flink/FunctionTest.java	Flink tests
snowflake/src/main/java/org/apache/sedona/snowflake/snowsql/UDFs.java	Snowflake V1 UDF implementations (WKB binary I/O)
snowflake/src/main/java/org/apache/sedona/snowflake/snowsql/UDFsV2.java	Snowflake V2 UDF implementations (GeoJSON String I/O)
snowflake-tester/src/test/java/org/apache/sedona/snowflake/snowsql/TestFunctions.java	Snowflake V1 tests
snowflake-tester/src/test/java/org/apache/sedona/snowflake/snowsql/TestFunctionsV2.java	Snowflake V2 tests
python/sedona/spark/sql/st_functions.py	PySpark bindings with type hints and documentation
docs/api/sql/Function.md	Spark API documentation with examples
docs/api/flink/Function.md	Flink API documentation with examples
docs/api/snowflake/vector-data/Function.md	Snowflake API documentation with examples

---

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