Returns a geometry that is the union of two or more input geometries, dissolving shared boundaries where shapes overlap.
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 set of geometry objects from a dataset column, used with the aggregate variant. |
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 grid cell are merged. Default: -1.0 (disabled). |
options | Parallel computing configuration as a JSON string, such as '{"parallel": 4}'. The degree of parallelism ranges from 1 to 64. Default: '{}' (sequential). |
Description
ST_Union has three variants with different input types:
Two-input variant: Takes two geometry objects and returns their union as a MULTI, NON-MULTI, or GeometryCollection. Returns NULL if either input is NULL.
Array variant: Takes an array of geometry objects and returns their union.
Aggregate variant: Operates as an aggregate function over a rowset of geometry objects, similar to SUM() or AVG(). Returns a MULTI or NON-MULTI geometry.
ST_Collect may be used in place of ST_Union when overlapping results are acceptable. ST_Collect is typically faster because it skips boundary dissolution—ST_Union checks for and dissolves shared boundaries to produce a clean, non-overlapping result.
Examples
Compare ST_Union and ST_Collect
ST_Union dissolves the shared boundary between two adjacent polygons, producing a single merged shape. ST_Collect returns a collection without dissolving boundaries.
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;
Use the gridsize parameter
Specify a grid size to snap vertices during union. Vertices within 0.005 units of each other are merged, which reduces precision artifacts:
SELECT ST_Area(ST_Union(geom, 0.005)) FROM tableA;Enable parallel computing
Pass the options parameter as a JSON string to enable parallel computing. The following example runs the union with 4 parallel workers:
SELECT ST_Area(ST_Union(geom, '{"parallel": 4}'::cstring)) FROM tableA;Combine gridsize and parallel computing
Specify both parameters at the same time:
SELECT ST_Area(ST_Union(geom, 0.005, '{"parallel": 4}'::cstring)) FROM tableA;