This topic describes the ST_Collect function. This function returns a geometry object that represents the collection of input geometry objects.
Syntax
geometry ST_Collect(geometry set g1Field);
geometry ST_Collect(geometry g1 , geometry g2);
geometry ST_Collect(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 consisting of the geometry objects you want to specify. |
Description
- This function returns a MULTI or GeometryCollection object. The ST_Collect function has two versions:
- Version 1: The input of the ST_Collect function is two geometry objects. In this case, this function returns a MULTI or GeometryCollection object.
- Version 2: The ST_Collect function works as an aggregate function. The input of the ST_Collect function is a collection of geometry objects. This function returns the geometry object that is returned by the ST_Geometry function.
- The ST_Collect function supports CircularString objects and Curve objects. This function may not return a MultiCurve object or MULTI object as you expect.
- The ST_Collect function and the ST_Union function are interchangeable. The ST_Collect function returns a MULTI or GeometryCollection object. The ST_Union function may return a geometry object because this function dissolves the boundaries of the input geometry object. The ST_Union function also splits a LineString object at the intersection of nodes while the ST_Collect function just returns a MultiLineString object.
- In most cases, the ST_Collect function runs faster than the ST_Union function because the ST_Union function dissolves the boundaries of the specified geometry objects or checks whether the constructed MultiPolygon object has intersecting parts. The ST_Collect function collects geometry objects into a MULTI object or collects MULTI objects into a GeometryCollection object.
- You can use the ST_Dump function to convert MULTI objects into geometry objects, and then specify the geometry objects to the ST_Collect function. This prevents the ST_Collect function from returning a GeomotryCollection object for MULTI objects.
Examples
- Execute the following statement to return a MULTI object:
SELECT ST_AsText(ST_Collect('POINT(0 0)'::geometry, 'POINT(0 1)'::geometry)); st_astext --------------------- MULTIPOINT(0 0,0 1) (1 row) - Execute the following statement to return a GeometryCollection object:
SELECT ST_AsText(ST_Collect('POINT(0 0)'::geometry, 'LINESTRING(0 2,0 3)'::geometry)); st_astext ---------------------------------------------------- GEOMETRYCOLLECTION(POINT(0 0),LINESTRING(0 2,0 3)) (1 row) - Execute the following statement to aggregate the input dataset:
select ST_AsText(ST_Collect(t.geom)) from (select (ST_DumpPoints(st_buffer('POINT(0 0)'::geometry,1,'quad_segs=2'))).geom as geom) as t; st_astext ---------------------------------------------------------------- MULTIPOINT(1 0,0.707106781186548 -0.707106781186547,0 -1,-0.70. .7106781186546 -0.707106781186549,-1 0,-0.70710678118655 0.7071. .06781186545,0 1,0.707106781186544 0.707106781186551,1 0) (1 row)