Geography bboxes: ST_Box2D over Geography with antimeridian-aware semantics
- Dominant language
- Java
- Stars
- 2.4k
- Forks
- 784
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 58
Description
Follow-up to the Phase 1 Box2D epic (#2877).
## Scope
Bring bbox functionality to `Geography` columns. Sedona's `Geography` type (added in earlier work, e.g. GH-2830) currently has no bbox API; PostGIS doesn't expose one for `geography` either (it has an internal `gidx` but no user-facing type). Sedona has a chance to do better here.
## Design choice
The Phase 1 `Box2D` type was deliberately built to leave the door open for this. Three paths were laid out in #2877:
- **(a) Reuse `Box2D` with antimeridian-wraparound semantics on the longitude axis.** When the source is geography (or geometry in EPSG:4326), allow `xmin > xmax` to mean \"crosses 180°.\" Adopts `apache/sedona-db`'s `WraparoundInterval` model. Single type, accurate semantics.
- **(b) Separate `GeographyBox` type.** Mirrors the `Geometry`/`Geography` split. Doubles function surface, cleaner type semantics.
- **(c) Punt** — users cast `geography → geometry`, lose the spherical/wraparound semantics. PostGIS's de facto answer.
**Recommended path: (a)**. Phase 1 explicitly preserved `xmin > xmax` (rather than burning it on an in-band empty marker) so we could add wraparound semantics later without breaking the type contract.
## Implementation outline
### Type semantics
- A `Box2D` for geography input may have `xmin > xmax` on the X (longitude) axis only — interpreted as \"crosses the antimeridian.\"
- `ymin > ymax` remains an error / sentinel; latitude doesn't wrap.
- An accompanying boolean `crossesAntimeridian` may be added to the underlying struct, OR derived implicitly from `xmin > xmax`. Pick one and document.
### Functions
| Function | Signature |
|---|---|
| `ST_Box2D(geog)` | Geography → Box2D |
| `ST_Extent(geog)` | aggregate |
| `ST_BoxIntersects` etc. when applied to a Box2D from geography input | spherical-aware |
The accessor overloads (`ST_XMin/XMax/YMin/YMax`) are unchanged — they read raw stored values.
### sedona-db alignment
Coordinate with `apache/sedona-db` maintainers on the wraparound encoding. Their `WraparoundInterval` is the closest existing implementation; we should match the wire format and semantics so geography bboxes round-trip across engines.
## Out of scope
- True 3D geographic bboxes (would need spherical-cap math + Z handling).
- Polar caps as a special encoding. Could be a follow-up.
## Dependencies
- Phase 1 (#2877) — done.
- Geography type with `ST_Extent` / `ST_Box2D` plumbing in InferredExpression — small extension to cover Geography input alongside Geometry.
Contributor guide
Research direction
Start with the Phase 1 Box2D work in #2877 and the Geography plumbing in InferredExpression, then compare apache/sedona-db's WraparoundInterval encoding. Resolve the representation choice and coordinate wire-format compatibility; done means Geography supports ST_Box2D and ST_Extent with antimeridian-aware semantics while preserving accessor behavior and the stated out-of-scope limits.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, sql
- Domain
- database
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100