ST_Collect
Prev | 8.3. Geometry Constructors | Next

## Name

ST_Collect — Creates a GeometryCollection or Multi* geometry from a set of geometries.

## Synopsis

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

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

`geometry ST_Collect(`geometry set g1field`)`;

## Description

Collects geometries into a geometry collection. The result is either a Multi* or a GeometryCollection, depending on whether the input geometries have the same or different types (homogeneous or heterogeneous). The input geometries are left unchanged within the collection.

Variant 1: accepts two input geometries

Variant 2: accepts an array of geometries

Variant 3: aggregate function accepting a rowset of geometries.

If any of the input geometries are collections (Multi* or GeometryCollection) ST_Collect returns a GeometryCollection (since that is the only type which can contain nested collections). To prevent this, use ST_Dump in a subquery to expand the input collections to their atomic elements (see example below).

ST_Collect and ST_Union appear similar, but in fact operate quite differently. ST_Collect aggregates geometries into a collection without changing them in any way. ST_Union geometrically merges geometries where they overlap, and splits linestrings at intersections. It may return single geometries when it dissolves boundaries.

Availability: 1.4.0 - ST_Collect(geomarray) was introduced. ST_Collect was enhanced to handle more geometries faster.

This function supports 3d and will not drop the z-index.

This method supports Circular Strings and Curves

## Examples - Two-input variant

Collect 2D points.

    SELECT ST_AsText( ST_Collect( ST_GeomFromText('POINT(1 2)'),
    	ST_GeomFromText('POINT(-2 3)') ));

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

Collect 3D points.

    SELECT ST_AsEWKT( ST_Collect( ST_GeomFromEWKT('POINT(1 2 3)'),
    		ST_GeomFromEWKT('POINT(1 2 4)') ) );

    		st_asewkt
    -------------------------
     MULTIPOINT(1 2 3,1 2 4)

Collect curves.

    SELECT ST_AsText( ST_Collect( 'CIRCULARSTRING(220268 150415,220227 150505,220227 150406)',
    		'CIRCULARSTRING(220227 150406,2220227 150407,220227 150406)'));

    		st_astext
    ------------------------------------------------------------------------------------
    MULTICURVE(CIRCULARSTRING(220268 150415,220227 150505,220227 150406),
     CIRCULARSTRING(220227 150406,2220227 150407,220227 150406))

## Examples - Array variant

Using an array constructor for a subquery.

    SELECT ST_Collect( ARRAY( SELECT geom FROM sometable ) );

Using an array constructor for values.

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

    --wkt collect --
    MULTILINESTRING((1 2,3 4),(3 4,4 5))

## Examples - Aggregate variant

Creating multiple collections by grouping geometries in a table.

    SELECT stusps, ST_Collect(f.geom) as geom
    	 FROM (SELECT stusps, (ST_Dump(geom)).geom As geom
    				FROM
    				somestatetable ) As f
    	GROUP BY stusps

## See Also

ST_Dump, ST_Union

Prev | Up | Next
UpdateGeometrySRID | Home | ST_LineFromMultiPoint