PostGIS
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
A gridSize can be specified to work in fixed-precision space. The
inputs are snapped to a grid of the given size, and the result vertices
are computed on that same grid. (Requires GEOS-3.9.0 or higher)
|
Performed by the GEOS module.
ST_Union creates MultiLineString and does not sew LineStrings into a single LineString. Use ST_LineMerge to sew LineStrings.
| 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 to use the gridSize parameter
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.
[.inlinemediaobject]
This method implements the
OGC Simple Features
Implementation Specification for SQL 1.1.
s2.1.1.3
|
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))