This topic describes the ST_Union function. This function constructs a geometry object that represents the union of multiple specified geometry objects.

Syntax

geometry  ST_Union(geometry set  g1Field);
geometry  ST_Union(geometry  g1 , geometry  g2);
geometry  ST_Union(geometry[]  g1Array);

Parameters

Parameter Description
g1field The fields of the geometry objects that you want to specify in the dataset.
g1 The first geometry object that you want to specify.
g2 The second geometry object that you want to specify.
g1Array An array that consists of the geometry objects you want to specify.

Description

  • The output type of this function is MULTI or GeometryCollection. The ST_Union function has two versions:
    • Version 1: The input of the ST_Union function is two geometry objects. The output can be a MULTI, NON-MULTI, or GeometryCollection object. If one of the two geometry objects is NULL, the ST_Union function returns NULL.
    • Version 2: The ST_Union function works as an aggregate function. The input is a collection of geometry objects. The output can be a MULTI or NON-MULTI object.
  • The ST_Collect function and the ST_Union function are interchangeable. The ST_Union function tries to dissolve the boundaries of the specified geometry objects to check whether the constructed MultiPolygon object has intersecting parts. Therefore, in most cases, the ST_Union runs at a lower speed than the ST_Collect function.

Examples

The following example shows the differences between the ST_Union function and the ST_Collect function:
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;
12