Box3D type in Sedona represents a planar axis-aligned 3D bounding box — a rectangular cuboid described by six Double values: xmin, ymin, zmin, xmax, ymax, zmax (PostGIS box3d storage order). It is a first-class SQL type backed by a Spark UDT and serializes to a struct of six non-nullable doubles, so columns of Box3D round-trip natively through Parquet. It is also available as a Flink type.
Box3D is the 3D counterpart to Box2D and complements the Geometry type. Use it when you need a compact, comparable bounding box that retains the Z extent — for example, as the join key in a spatial join that should match on all three axes.
Semantic notes
Box3Dvalues use closed-interval semantics: edge-, face-, and corner-touching boxes are considered intersecting and contained.- Absence is represented by SQL
NULLrather than an in-band sentinel. - Geometries without a Z dimension fold into
zmin = zmax = 0, matching PostGIS. SoST_Box3Dof a purely 2D geometry yields a box flush against thez = 0plane. - Bounds are required to be ordered (
xmin <= xmax,ymin <= ymax,zmin <= zmax) on all three axes. Unlike Box2D — where inverted X is reserved for a future antimeridian-wraparound semantics — Z has no wraparound convention, so all three axes are strictly ordered; predicates and join planning throwIllegalArgumentExceptionon inverted input.
Constructors
| Function | Return type | Description | Since |
|---|---|---|---|
| ST_Box3D | Box3D | Return the planar 3D bounding box of a Geometry as a Box3D (z = 0 for geometries without a Z dimension). | v1.9.1 |
| ST_3DMakeBox | Box3D | Build a Box3D from two corner POINT Z geometries. | v1.9.1 |
Accessors
| Function | Return type | Description | Since |
|---|---|---|---|
| ST_XMin | Double | Return the minimum X coordinate of a Box3D. | v1.9.1 |
| ST_YMin | Double | Return the minimum Y coordinate of a Box3D. | v1.9.1 |
| ST_ZMin | Double | Return the minimum Z coordinate of a Box3D. | v1.9.1 |
| ST_XMax | Double | Return the maximum X coordinate of a Box3D. | v1.9.1 |
| ST_YMax | Double | Return the maximum Y coordinate of a Box3D. | v1.9.1 |
| ST_ZMax | Double | Return the maximum Z coordinate of a Box3D. | v1.9.1 |
ST_XMin … ST_ZMax functions also accept Geometry inputs — see Bounding Box Functions.
Predicates
Box3D inputs are accepted by the existing ST_Intersects / ST_Contains predicates as type-dispatched overloads, and by the dedicated ST_3DDWithin distance predicate — there are no separate ST_3DBox* functions.
| Function | Return type | Description | Since |
|---|---|---|---|
| ST_Intersects | Boolean | Closed-interval bbox intersection on all three axes when both arguments are Box3D. Matches PostGIS &&& on box3d. | v1.9.1 |
| ST_Contains | Boolean | Closed-interval bbox containment on all three axes when both arguments are Box3D. | v1.9.1 |
| ST_3DDWithin | Boolean | 3D Euclidean distance-within test, over Geometry or Box3D inputs. Mirrors PostGIS ST_3DDWithin. | v1.9.1 |
Utility functions
| Function | Return type | Description | Since |
|---|---|---|---|
| ST_AsText | String | Return the BOX3D(xmin ymin zmin, xmax ymax zmax) text representation of a Box3D. | v1.9.1 |
Aggregates
| Function | Return type | Description | Since |
|---|---|---|---|
| ST_3DExtent | Box3D | Return the 3D bounding box of all geometries in a column as a Box3D. Empty and NULL inputs are skipped; geometries without Z fold to z = 0. Mirrors PostGIS ST_3DExtent. | v1.9.1 |
Type conversion
Catalyst recognizes the SQLCAST from Geometry to Box3D:
| Cast | Equivalent function | Notes |
|---|---|---|
CAST(geom AS box3d) | ST_Box3D(geom) | Planar 3D bounding box of the geometry (z = 0 when the geometry has no Z). |
spark.sql.extensions=org.apache.sedona.sql.SedonaSqlExtensions); the function form works in any Sedona-enabled session. The inverse cast (CAST(box3d AS geometry)) is not yet supported — there is no ST_GeomFromBox3D counterpart.
Query optimization
Box3D-typed columns participate in Sedona’s spatial join planner:
- Spatial joins.
ST_IntersectsandST_Containsbetween twoBox3Dcolumns, andST_3DDWithindistance joins, route through the same physical operators (RangeJoinExec,BroadcastIndexJoinExec,DistanceJoinExec) used for the Geometry-typed forms. The planner projects eachBox3Dto its XY footprint for the R-tree pass and re-checks the Z axis per candidate via the original predicate, so a Box3D join is correct on all three axes while still benefiting from the 2D index. See Range join and Broadcast index join. - Filter pushdown to Parquet row-group statistics is not yet implemented for
Box3Dcolumns (it exists for Box2D).