ST_Union
Prev | 12.12. Raster Processing: Map Algebra | Next

## Name

ST_Union — Returns the union of a set of raster tiles into a single raster composed of 1 or more bands.

## Synopsis

`raster ST_Union(`setof raster rast`)`;

`raster ST_Union(`setof raster rast, unionarg[] unionargset`)`;

`raster ST_Union(`setof raster rast, integer nband`)`;

`raster ST_Union(`setof raster rast, text uniontype`)`;

`raster ST_Union(`setof raster rast, integer nband, text uniontype`)`;

## Description

Returns the union of a set of raster tiles into a single raster composed of at least one band. The resulting raster's extent is the extent of the whole set. In the case of intersection, the resulting value is defined by `uniontype` which is one of the following: LAST (default), FIRST, MIN, MAX, COUNT, SUM, MEAN, RANGE.

In order for rasters to be unioned, they must all have the same alignment. Use ST_SameAlignment and ST_NotSameAlignmentReason for more details and help. One way to fix alignment issues is to use ST_Resample and use the same reference raster for alignment.

Availability: 2.0.0

Enhanced: 2.1.0 Improved Speed (fully C-Based).

Availability: 2.1.0 ST_Union(rast, unionarg) variant was introduced.

Enhanced: 2.1.0 ST_Union(rast) (variant 1) unions all bands of all input rasters. Prior versions of PostGIS assumed the first band.

Enhanced: 2.1.0 ST_Union(rast, uniontype) (variant 4) unions all bands of all input rasters.

## Examples: Reconstitute a single band chunked raster tile

    -- this creates a single band from first band of raster tiles
    -- that form the original file system tile
    SELECT filename, ST_Union(rast,1) As file_rast
    FROM sometable WHERE filename IN('dem01', 'dem02') GROUP BY filename;

## Examples: Return a multi-band raster that is the union of tiles intersecting geometry

    -- this creates a multi band raster collecting all the tiles that intersect a line
    -- Note: In 2.0, this would have just returned a single band raster
    -- , new union works on all bands by default
    -- this is equivalent to unionarg: ARRAY[ROW(1, 'LAST'), ROW(2, 'LAST'), ROW(3, 'LAST')]::unionarg[]
    SELECT ST_Union(rast)
    FROM aerials.boston
    WHERE ST_Intersects(rast,  ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) );

## Examples: Return a multi-band raster that is the union of tiles intersecting geometry

Here we use the longer syntax if we only wanted a subset of bands or we want to change order of bands

    -- this creates a multi band raster collecting all the tiles that intersect a line
    SELECT ST_Union(rast,ARRAY[ROW(2, 'LAST'), ROW(1, 'LAST'), ROW(3, 'LAST')]::unionarg[])
    FROM aerials.boston
    WHERE ST_Intersects(rast,  ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) );

## See Also

unionarg, ST_Envelope, ST_ConvexHull, ST_Clip, ST_Union

Prev | Up | Next
ST_Reclass | Home | ST_Distinct4ma