apache / apache/sedona

Geography bboxes: ST_Box2D over Geography with antimeridian-aware semantics

Open
#2,929 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.