ST_Contains¶

Introduction: Return true if A fully contains B. Polymorphic over input type:

(Geometry, Geometry) — topological containment via JTS.
(Geography, Geography) — topological containment via S2.
(Box2D, Box2D) — closed-interval bbox containment on both axes. Matches PostGIS ~ on box2d. Throws IllegalArgumentException on inverted bounds (xmin > xmax or ymin > ymax).
(Box3D, Box3D) — closed-interval bbox containment on all three axes. Equal boxes contain each other. Throws on inverted bounds on any axis.

ST_Contains returning true ST_Contains returning false

Format:

ST_Contains(A: Geometry, B: Geometry)
ST_Contains(A: Geography, B: Geography)
ST_Contains(A: Box2D, B: Box2D) (Since v1.9.1)
ST_Contains(A: Box3D, B: Box3D) (Since v1.9.1)

Return type: Boolean

Since: v1.0.0

SQL Example

SELECT ST_Contains(ST_GeomFromWKT('POLYGON((175 150,20 40,50 60,125 100,175 150))'), ST_GeomFromWKT('POINT(174 149)'))

Output:

false

Box2D example:

SELECT ST_Contains(
    ST_MakeBox2D(ST_Point(0.0, 0.0), ST_Point(10.0, 10.0)),
    ST_MakeBox2D(ST_Point(2.0, 2.0), ST_Point(5.0, 5.0)))

Output:

true

For Box3D inputs containment must hold on all three axes — a box contained within another's XY footprint but extending past it in Z is not contained:

Box3D ST_Contains returning true: B lies fully inside A Box3D ST_Contains returning false: B is inside in XY but extends past A in Z

Box2D optimization¶

ST_Contains(box_col, lit_box) over a Box2D column and a literal Box2D (and the reversed form) is recognised by Sedona's spatial optimizer:

Filter pushdown. When the column is a Box2D stored in GeoParquet, the predicate translates to Parquet row-group inequalities on the xmin / ymin / xmax / ymax leaves. See Box2D filter pushdown.
Spatial join. ST_Contains(a, b) between two Box2D columns is planned as a range or broadcast-index join with SpatialPredicate.COVERS semantics (closed-interval containment — JTS contains, strict-interior, would reject edge-sharing pairs). See Box2D spatial join.