Returns a geometry representing the union of the input geometries, dissolving shared boundaries and resolving overlaps.
Syntax
geometry ST_Union(geometry set g1Field);
geometry ST_Union(geometry g1, geometry g2);
geometry ST_Union(geometry[] g1Array);
geometry ST_Union(geometry set g1Field, float8 gridsize);
geometry ST_Union(geometry set g1Field, cstring options);
geometry ST_Union(geometry set g1Field, float8 gridsize, cstring options);
geometry ST_Union(geometry[] g1Array, float8 gridsize);
geometry ST_Union(geometry[] g1Array, cstring options);
geometry ST_Union(geometry[] g1Array, float8 gridsize, cstring options);Parameters
| Parameter | Description |
|---|---|
| g1Field | A geometry column from a dataset, used as the aggregate input. |
| g1 | The first geometry object. |
| g2 | The second geometry object. |
| g1Array | An array of geometry objects. |
| gridsize | The grid cell size used to snap vertices during the union. Vertices within the same cell are merged. Default: -1.0 (disabled). |
| options | A JSON string that controls parallel computing. Set to '{"parallel": N}' to enable parallel computing, where N is the degree of parallelism (1–64). Default: '{}' (sequential computing). |
Description
ST_Union has three variants.
Two-input variant — takes two geometry objects and returns their union as a MULTI, NON-MULTI, or GeometryCollection. If either input is NULL, the function returns NULL.
Array variant — takes an array of geometry objects and returns their union.
Aggregate variant — works like SUM() or AVG(): it operates on a set of rows, computing the union across all geometry values in the group. The output is a MULTI or NON-MULTI geometry.
All variants dissolve shared boundaries and check for overlapping parts in the resulting geometry. For large datasets where boundary dissolution is not required, use ST_Collect instead — it skips the dissolve step and runs faster.
Examples
Two-input variant
The following example shows that two distinct input geometries produce a MULTI result, while two identical geometries produce an atomic geometry after merging.
SELECT ST_Union(g1, g2), ST_Collect(g1, g2)
FROM (
SELECT 'POLYGON((0 0,1 0,1 2,0 2,0 0))'::geometry AS g1,
'POLYGON((1 0,3 0,3 1,1 1,1 0))'::geometry AS g2
) AS t;
The left result (ST_Union) dissolves the shared edge between the two polygons into a single merged polygon. The right result (ST_Collect) groups them without dissolving boundaries.
Aggregate variant with gridsize and options
All examples below use the aggregate variant. The gridsize parameter snaps nearby vertices before computing the union; the options parameter enables parallel computing.
-- Use gridsize to snap vertices within a 0.005-unit grid.
SELECT st_area(st_union(geom, 0.005)) FROM tableA;
-- Enable parallel computing with 4 workers.
SELECT st_area(st_union(geom, '{"parallel": 4}'::cstring)) FROM tableA;
-- Combine gridsize and parallel computing.
SELECT st_area(st_union(geom, 0.005, '{"parallel": 4}'::cstring)) FROM tableA;