ST_ClipByBox2D

What is ST_ClipByBox2D?

ST_ClipByBox2D returns the portion of a geometry that falls inside a 2D bounding box. It uses a lightweight clipping algorithm that is significantly faster than a general ST_Intersection against a rectangle, at the cost of producing geometries that may be non-simple or non-valid along the clip edges.

ST_ClipByBox2D(geometry geom, box2d box) → geometry

The box argument is a box2d literal or the result of ST_MakeEnvelope(...)::box2d. The output SRID matches the input geometry.

When would you use ST_ClipByBox2D?

Use ST_ClipByBox2D to restrict large geometries to a map tile, a viewport, or an analysis window — a common preprocessing step before rendering vector tiles, before an expensive operation, or when generating area extracts from a big dataset. It is the standard clipping primitive behind ST_AsMVTGeom and is much faster than ST_Intersection(geom, ST_MakeEnvelope(...)) on large polygons.

1-- Clip countries to a bounding box before tiling
2SELECT iso, ST_ClipByBox2D(geom, ST_MakeEnvelope(-10, 35, 40, 70, 4326)) AS geom
3FROM countries;

FAQs

How is it different from ST_Intersection?

ST_ClipByBox2D is faster but may return geometries that are non-simple at the clip boundary. ST_Intersection against the same box produces a strictly valid result but is slower. For rendering and tiling, ST_ClipByBox2D is almost always preferred.

Does it use a spatial index?

Not directly. It is a per-row clip. To accelerate a workload, filter candidate rows first with geom && box (the && index operator) so the GiST index eliminates non-overlapping rows before clipping.

What happens when the geometry is entirely outside the box?

The function returns an empty geometry of the appropriate type (e.g. empty POLYGON). Filter with NOT ST_IsEmpty(...) downstream if needed.

Can the output be invalid?

Yes, along the clip edges the result may not be OGC-valid. Pass through ST_MakeValid if downstream operations require strict validity, or use ST_Intersection to get a valid result directly.