Box2D Functions

The 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 serialises 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

• Box2D values use closed-interval semantics: edge-touching boxes are considered intersecting and (per ST_BoxContains) contained.
• Absence is represented by SQL NULL rather 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 throw IllegalArgumentException on inverted input today.
• Unlike ST_Envelope, which returns the envelope as a Geometry (typically a polygon, but JTS may return a Point or LineString for degenerate inputs), ST_Box2D always returns a typed Box2D value. Prefer the typed form when downstream code only needs the four bounds, and prefer the geometry form when downstream code expects a Geometry.

Box2D 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

Box2D Accessors

Function	Return type	Description	Since
ST_XMin	Double	Return the minimum X coordinate of a Box2D.	v1.9.1
ST_YMin	Double	Return the minimum Y coordinate of a Box2D.	v1.9.1
ST_XMax	Double	Return the maximum X coordinate of a Box2D.	v1.9.1
ST_YMax	Double	Return the maximum Y coordinate of a Box2D.	v1.9.1

The same ST_XMin / ST_YMin / ST_XMax / ST_YMax functions also accept Geometry inputs — see Bounding Box Functions.

Box2D Predicates

Function	Return type	Description	Since
ST_BoxIntersects	Boolean	Closed-interval bbox intersection over two Box2D arguments. Matches PostGIS && on box2d.	v1.9.1
ST_BoxContains	Boolean	Closed-interval bbox containment over two Box2D arguments. Matches PostGIS ~ on box2d.	v1.9.1
ST_DWithin	Boolean	Closed-interval planar distance test between two Box2D rectangles.	v1.9.1

Box2D Functions

Function	Return type	Description	Since
ST_Expand	Box2D	Expand a Box2D by a per-axis or uniform delta.	v1.9.1
ST_AsText	String	Return the BOX(xmin ymin, xmax ymax) text representation of a Box2D.	v1.9.1

Box2D 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 recognises SQL CAST 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).

The cast forms require the Sedona SQL parser extension (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_BoxIntersects / ST_BoxContains predicates over a Box2D column and a literal Box2D push down to Parquet row-group statistics on the column's underlying xmin / ymin / xmax / ymax leaves. See Query optimization → Box2D filter pushdown.
• Spatial joins. ST_BoxIntersects and ST_BoxContains route through the same physical operators (RangeJoinExec, BroadcastIndexJoinExec) used for ST_Intersects / ST_Covers. See Query optimization → Range join and Broadcast index join.