ST_Union
Prev | 8.13. Overlay Functions | Next

## Name

ST_Union — Computes a geometry representing the point-set union of the input geometries.

## Synopsis

`geometry ST_Union(`geometry g1, geometry g2`)`;

`geometry ST_Union(`geometry g1, geometry g2, float8 gridSize`)`;

`geometry ST_Union(`geometry[] g1_array`)`;

`geometry ST_Union(`geometry set g1field`)`;

`geometry ST_Union(`geometry set g1field, float8 gridSize`)`;

## Description

Unions the input geometries, merging geometry to produce a result geometry with no overlaps. The output may be an atomic geometry, a MultiGeometry, or a Geometry Collection. Comes in several variants:

Two-input variant: returns a geometry that is the union of two input geometries. If either input is NULL, then NULL is returned.

Array variant: returns a geometry that is the union of an array of geometries.

Aggregate variant: returns a geometry that is the union of a rowset of geometries. The ST_Union() function is an "aggregate" function in the terminology of PostgreSQL. That means that it operates on rows of data, in the same way the SUM() and AVG() functions do and like most aggregates, it also ignores NULL geometries.

See ST_UnaryUnion for a non-aggregate, single-input variant.

The ST_Union array and set variants use the fast Cascaded Union algorithm described in http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html

If the optional `gridSize` parameter is given (GEOS-3.9.0 or higher required), all result vertices are guaranteed to fall on a grid of the specified size. For the operation to give predictable results all the input vertices must fall already on the specified grid, see ST_ReducePrecision.

ST_Collect may sometimes be used in place of ST_Union, if the result is not required to be non-overlapping. ST_Collect is usually faster than ST_Union because it performs no processing on the collected geometries.

Performed by the GEOS module.

ST_Union creates MultiLineString and does not sew LineStrings into a single LineString. Use ST_LineMerge to sew LineStrings.

NOTE: this function was formerly called GeomUnion(), which was renamed from "Union" because UNION is an SQL reserved word.

Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0

Changed: 3.0.0 does not depend on SFCGAL.

Availability: 1.4.0 - ST_Union was enhanced. ST_Union(geomarray) was introduced and also faster aggregate collection in PostgreSQL.

This method implements the OGC Simple Features Implementation Specification for SQL 1.1. s2.1.1.3

Aggregate version is not explicitly defined in OGC SPEC.

This method implements the SQL/MM specification. SQL-MM 3: 5.1.19 the z-index (elevation) when polygons are involved.

This function supports 3d and will not drop the z-index. However, the result is computed using XY only. The result Z values are copied, averaged or interpolated.

## Examples

Aggregate example

    SELECT id,
           ST_Union(geom) as singlegeom
    FROM sometable f
    GROUP BY id;

Non-Aggregate example

    select ST_AsText(ST_Union('POINT(1 2)' :: geometry, 'POINT(-2 3)' :: geometry))

    st_astext
    ----------
    MULTIPOINT(-2 3,1 2)

    select ST_AsText(ST_Union('POINT(1 2)' :: geometry, 'POINT(1 2)' :: geometry))

    st_astext
    ----------
    POINT(1 2)

3D example - sort of supports 3D (and with mixed dimensions!)

    select ST_AsEWKT(ST_Union(geom))
    from (
             select 'POLYGON((-7 4.2,-7.1 4.2,-7.1 4.3, -7 4.2))'::geometry geom
             union all
             select 'POINT(5 5 5)'::geometry geom
             union all
             select 'POINT(-2 3 1)'::geometry geom
             union all
             select 'LINESTRING(5 5 5, 10 10 10)'::geometry geom
         ) as foo;

    st_asewkt
    ---------
    GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7 4.2 5,-7.1 4.2 5,-7.1 4.3 5,-7 4.2 5)));

3d example not mixing dimensions

    select ST_AsEWKT(ST_Union(geom))
    from (
             select 'POLYGON((-7 4.2 2,-7.1 4.2 3,-7.1 4.3 2, -7 4.2 2))'::geometry geom
             union all
             select 'POINT(5 5 5)'::geometry geom
             union all
             select 'POINT(-2 3 1)'::geometry geom
             union all
             select 'LINESTRING(5 5 5, 10 10 10)'::geometry geom
         ) as foo;

    st_asewkt
    ---------
    GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7 4.2 2,-7.1 4.2 3,-7.1 4.3 2,-7 4.2 2)))

    --Examples using new Array construct
    SELECT ST_Union(ARRAY(SELECT geom FROM sometable));

    SELECT ST_AsText(ST_Union(ARRAY[ST_GeomFromText('LINESTRING(1 2, 3 4)'),
                ST_GeomFromText('LINESTRING(3 4, 4 5)')])) As wktunion;

    --wktunion---
    MULTILINESTRING((3 4,4 5),(1 2,3 4))

## See Also

ST_Collect, ST_UnaryUnion, ST_MemUnion, ST_Intersection, ST_Difference, ST_SymDifference, ST_ReducePrecision

Prev | Up | Next
ST_UnaryUnion | Home | ST_Buffer