Box2D type in Sedona represents a planar axis-aligned bounding box — a rectangle described by four Double values: xmin, ymin, xmax, ymax. It is a first-class SQL type backed by a Spark UDT and serializes to a struct of four non-nullable doubles, so columns of Box2D round-trip natively through Parquet and align with GeoParquet 1.1 bbox covering columns.
Box2D complements the Geometry and Geography types. Use it when you need a compact, comparable bounding rectangle — for example, as a covering column on a GeoParquet table that lets the reader prune row groups, or as the join key in a spatial join that only needs an envelope-level match.
Semantic notes
Box2Dvalues use closed-interval semantics: edge-touching boxes are considered intersecting and contained (viaST_Intersects/ST_ContainsoverBox2Dinputs).- Absence is represented by SQL
NULLrather than an in-band sentinel. - Bounds are required to be ordered (
xmin <= xmax,ymin <= ymax). Inverted-bound values are reserved for a future antimeridian-wraparound semantics on geography bboxes; predicates and join planning throwIllegalArgumentExceptionon inverted input today. - Unlike ST_Envelope, which returns the envelope as a
Geometry(typically a polygon, but JTS may return aPointorLineStringfor degenerate inputs), ST_Box2D always returns a typedBox2Dvalue. Prefer the typed form when downstream code only needs the four bounds, and prefer the geometry form when downstream code expects aGeometry.
Constructors
| Function | Return type | Description | Since |
|---|---|---|---|
| ST_Box2D | Box2D | Return the planar bounding box of a Geometry as a Box2D. | v1.9.1 |
| ST_MakeBox2D | Box2D | Build a Box2D from two corner POINT geometries. | v1.9.1 |
| ST_GeomFromBox2D | Geometry | Convert a Box2D to a closed rectangular polygon Geometry (degenerate boxes return a Point or LineString). | v1.9.1 |
Accessors
The same
ST_XMin / ST_YMin / ST_XMax / ST_YMax functions also accept Geometry inputs — see Bounding Box Functions.
Predicates
Box2D-on-Box2D overlap and containment are expressed through the standard ST_Intersects and ST_Contains predicates, which accept Box2D inputs directly with closed-interval semantics (ST_Intersects matches PostGIS && and ST_Contains matches PostGIS ~ on box2d).
| Function | Return type | Description | Since |
|---|---|---|---|
| ST_DWithin | Boolean | Closed-interval planar distance test between two Box2D rectangles. | v1.9.1 |
Utility functions
Aggregates
| Function | Return type | Description | Since |
|---|---|---|---|
| ST_Extent | Box2D | Return the planar bounding box of all geometries in a column as a Box2D. Empty and NULL inputs are skipped. Mirrors PostGIS ST_Extent. | v1.9.1 |
Type conversion
Catalyst recognizes SQLCAST between Box2D and Geometry:
| Cast | Equivalent function | Notes |
|---|---|---|
CAST(geom AS box2d) | ST_Box2D(geom) | Planar bounding box of the geometry. |
CAST(box AS geometry) | ST_GeomFromBox2D(box) | Closed rectangular polygon (Point/LineString for degenerate boxes). |
spark.sql.extensions=org.apache.sedona.sql.SedonaSqlExtensions); the function forms work in any Sedona-enabled session.
Query optimization
Box2D-typed columns are first-class participants in Sedona’s spatial optimizer:- Filter pushdown.
ST_Intersects/ST_Containspredicates over a Box2D column and a literal Box2D push down to Parquet row-group statistics on the column’s underlyingxmin/ymin/xmax/ymaxleaves. See Box2D filter pushdown. - Spatial joins.
ST_IntersectsandST_Containsover two Box2D columns route through the same physical operators (RangeJoinExec,BroadcastIndexJoinExec) used forGeometry. See Range join and Broadcast index join.