Skip to main content
The 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. Box3D anatomy: a cuboid spanning the (xmin, ymin, zmin) and (xmax, ymax, zmax) corners

​
Semantic notes

  • Box3D values use closed-interval semantics: edge-, face-, and corner-touching boxes are considered intersecting and contained.
  • Absence is represented by SQL NULL rather than an in-band sentinel.
  • Geometries without a Z dimension fold into zmin = zmax = 0, matching PostGIS. So ST_Box3D of a purely 2D geometry yields a box flush against the z = 0 plane.
  • 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 throw IllegalArgumentException on inverted input.

​
Constructors

​
Accessors

The same 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.

​
Utility functions

​
Aggregates

​
Type conversion

Catalyst recognizes the SQL CAST from Geometry to Box3D: The cast form requires the Sedona SQL parser extension (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_Intersects and ST_Contains between two Box3D columns, and ST_3DDWithin distance joins, route through the same physical operators (RangeJoinExec, BroadcastIndexJoinExec, DistanceJoinExec) used for the Geometry-typed forms. The planner projects each Box3D to 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 Box3D columns (it exists for Box2D).