From: Regina Obe Date: Tue, 29 Jul 2008 15:42:35 +0000 (+0000) Subject: Move over ST_Collect and ST_Union, provide examples for ST_Union. Get rid of comment... X-Git-Tag: 1.4.0b1~807 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=0eadcb32a40bddf6be9d665eeba02bfebab5d28a;p=postgis Move over ST_Collect and ST_Union, provide examples for ST_Union. Get rid of comment about don't use ST_Union with geometry collections - seems to work fine with those. git-svn-id: http://svn.osgeo.org/postgis/trunk@2893 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/reference.xml b/doc/reference.xml index 510b7cb5b..2a5ab7a53 100644 --- a/doc/reference.xml +++ b/doc/reference.xml @@ -284,41 +284,7 @@ - - ST_Union(geometry, geometry) - - - Returns a geometry that represents the point set union of - the Geometries. - - Performed by the GEOS module. - - Do not call with a GeometryCollection as an argument. - - NOTE: this function was formerly called GeomUnion(), which - was renamed from "Union" because UNION is an SQL reserved - word. - - OGC SPEC s2.1.1.3 - - - - - ST_Union(geometry set) - - - Returns a geometry that represents the point set union of - all Geometries in given set. - - Performed by the GEOS module. - - Do not call with a GeometryCollection in the argument - set. - - Not explicitly defined in OGC SPEC. - - - + ST_MemUnion(geometry set) @@ -1362,78 +1328,6 @@ GROUP BY gid, field1,field2; - - ST_Collect(geometry set) - - - This function returns a GEOMETRYCOLLECTION or a MULTI object - from a set of geometries. The collect() 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. For example, "SELECT ST_Collect(GEOM) FROM GEOMTABLE - GROUP BY ATTRCOLUMN" will return a separate GEOMETRYCOLLECTION for - each distinct value of ATTRCOLUMN. - - ST_Collect and ST_Union are often interchangeable. - ST_Collect is in general orders of magnitude faster than ST_Union - because it does not try to dissolve boundaries. It merely rolls up - single geometries into MULTI and MULTI or mixed geometry types - into Geometry Collections. Unfortunately geometry collections are - not well-supported by GIS tools. To prevent ST_Collect from - returning a Geometry Collection when collecting MULTI geometries, - one can use the below trick that utilizes to expand the - MULTIs out to singles and then regroup them. - - -Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html -SELECT stusps, - ST_Multi(ST_Collect(f.the_geom)) as singlegeom - FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom - FROM - somestatetable ) As f -GROUP BY stusps - - - - - - ST_Collect(geometry, geometry) - - - This function returns a geometry being a collection of two - input geometries. Output type can be a MULTI* or a - GEOMETRYCOLLECTION. - - - - - ST_Dump(geometry) - - - This is a set-returning function (SRF). It returns a set of - geometry_dump rows, formed by a geometry (geom) and an array of - integers (path). When the input geometry is a simple type - (POINT,LINESTRING,POLYGON) a single record will be returned with - an empty path array and the input geometry as geom. When the input - geometry is a collection or multi it will return a record for each - of the collection components, and the path will express the - position of the component inside the collection. - - ST_Dump is useful for expanding geometries. It is the - reverse of a GROUP BY in that it creates new rows. For example it - can be use to expand MULTIPOLYGONS into POLYGONS. - - -SELECT sometable.field1, sometable.field1, -(ST_Dump(sometable.the_geom)).geom As the_geom - FROM sometable - - - Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or - higher. - - - ST_DumpRings(geometry) @@ -2635,22 +2529,7 @@ WHERE n*100.00/length < 1; SQL-MM 3: 5.1.28 - - - - - - ST_Union - - - Return an ST_Geometry value that represents the point set - union of two ST_Geometry values. - - SQL-MM 3: 5.1.19 - - - - + ST_WKBToSQL diff --git a/doc/reference_new.xml b/doc/reference_new.xml index 7cc6c54a9..690dc9401 100644 --- a/doc/reference_new.xml +++ b/doc/reference_new.xml @@ -712,7 +712,7 @@ Check constraints: - geometery ST_BdPolyFromText + geometry ST_BdPolyFromText text WKT @@ -766,7 +766,7 @@ Check constraints: - geometery ST_BdMPolyFromText + geometry ST_BdMPolyFromText text WKT @@ -873,6 +873,140 @@ FROM (SELECT ST_Buffer(ST_MakeLine(ST_MakePoint(21, 22),ST_MakePoint(-19, -18)), this function with standard OGC interface + + + ST_Collect + Return a specified ST_Geometry value from a collection of other geometries. + + + + + + geometry ST_Collect + geometry set g1field + + + geometry ST_Collect + geometry g1 + + + + + + Description + Output type can be a MULTI* or a + GEOMETRYCOLLECTION. Comes in 2 variants. Variant 1 collects 2 geometries. Variant 2 is an aggregate function that takes a set of geometries and collects + them into a single ST_Geometry. + + Aggregate version: This function returns a GEOMETRYCOLLECTION or a MULTI object + from a set of geometries. The ST_Collect() 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. For example, "SELECT ST_Collect(GEOM) FROM GEOMTABLE + GROUP BY ATTRCOLUMN" will return a separate GEOMETRYCOLLECTION for + each distinct value of ATTRCOLUMN. + + Non-Aggregate version: This function returns a geometry being a collection of two + input geometries. Output type can be a MULTI* or a + GEOMETRYCOLLECTION. + + ST_Collect and ST_Union are often interchangeable. + ST_Collect is in general orders of magnitude faster than ST_Union + because it does not try to dissolve boundaries or validate that a constructed MultiPolgon doesn't + have overlapping regions. It merely rolls up + single geometries into MULTI and MULTI or mixed geometry types + into Geometry Collections. Unfortunately geometry collections are + not well-supported by GIS tools. To prevent ST_Collect from + returning a Geometry Collection when collecting MULTI geometries, + one can use the below trick that utilizes to expand the + MULTIs out to singles and then regroup them. + + + + Examples + Aggregate example + +Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html +SELECT stusps, + ST_Multi(ST_Collect(f.the_geom)) as singlegeom + FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom + FROM + somestatetable ) As f +GROUP BY stusps + + Non-Aggregate example + +Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html +SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'), + ST_GeomFromText('POINT(-2 3)') )); + +st_astext +---------- +MULTIPOINT(1 2,-2 3) + +SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'), + ST_GeomFromText('POINT(1 2)') ) ); + +st_astext +---------- +MULTIPOINT(1 2,1 2) + + + + See Also + , + + + + + + ST_Dump + Returns a set of + geometry_dump rows, formed by a geometry (geom). + + + + + + geometry_dump[]ST_Dump + geometry g1 + + + + + + Description + This is a set-returning function (SRF). It returns a set of + geometry_dump rows, formed by a geometry (geom) and an array of + integers (path). When the input geometry is a simple type + (POINT,LINESTRING,POLYGON) a single record will be returned with + an empty path array and the input geometry as geom. When the input + geometry is a collection or multi it will return a record for each + of the collection components, and the path will express the + position of the component inside the collection. + + ST_Dump is useful for expanding geometries. It is the + reverse of a GROUP BY in that it creates new rows. For example it + can be use to expand MULTIPOLYGONS into POLYGONS. + + Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or + higher. + + + + Examples + +SELECT sometable.field1, sometable.field1, +(ST_Dump(sometable.the_geom)).geom As the_geom + FROM sometable + + + + See Also + + + + ST_GeomFromEWKB @@ -882,7 +1016,7 @@ FROM (SELECT ST_Buffer(ST_MakeLine(ST_MakePoint(21, 22),ST_MakePoint(-19, -18)), - geometery ST_GeomFromEWKB + geometry ST_GeomFromEWKB bytea EWKB @@ -925,7 +1059,7 @@ FROM (SELECT ST_Buffer(ST_MakeLine(ST_MakePoint(21, 22),ST_MakePoint(-19, -18)), - geometery ST_GeomFromEWKT + geometry ST_GeomFromEWKT text EWKT @@ -989,11 +1123,11 @@ SELECT ST_GeomFromEWKT('SRID=4269;MULTIPOLYGON(((-71.1031880899493 42.3152774590 - geometery ST_GeomFromText + geometry ST_GeomFromText text WKT - geometery ST_GeomFromText + geometry ST_GeomFromText text WKT integer srid @@ -1235,6 +1369,101 @@ FROM See Also , , , , + + + + ST_Union + Returns a geometry that represents the point set union of + the Geometries. + + + + + + geometry ST_Union + geometry set g1field + + + geometry ST_Union + geometry g1 + + + + + + Description + Output type can be a MULTI* , single geometry, or Geometry Collection. Comes in 2 variants. Variant 1 unions 2 geometries resulting in a new geomety with no intersecting regions. + Variant 2 is an aggregate function that takes a set of geometries and unions + them into a single ST_Geometry resulting in no intersecting regions. + + Aggregate version: This function returns a MULTI geometry or NON-MULTI geometry + from a set 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. + + Non-Aggregate version: This function returns a geometry being a union of two + input geometries. Output type can be a MULTI* ,NON-MULTI or + GEOMETRYCOLLECTION. + + ST_Collect and ST_Union are often interchangeable. + ST_Union is in general orders of magnitude slower than ST_Collect + because it does not tries to dissolve boundaries and reorder geometries to ensure that a constructed MultiPolygon doesn't + have intersecting regions. . + + Performed by the GEOS module. + NOTE: this function was formerly called GeomUnion(), which + was renamed from "Union" because UNION is an SQL reserved + word. + + + + + + This method implements the OpenGIS Simple Features + Implementation Specification for SQL: OGC SPEC s2.1.1.3 + + + + + + This method implements the SQL/MM specification: + SQL-MM 3: 5.1.19 + + Aggregate version is not explicitly defined in OGC SPEC. + + + + Examples + Aggregate example + +SELECT stusps, + ST_Multi(ST_Union(f.the_geom)) as singlegeom + FROM sometable As f +GROUP BY stusps + + Non-Aggregate example + +SELECT ST_AsText(ST_Union(ST_GeomFromText('POINT(1 2)'), + ST_GeomFromText('POINT(-2 3)') ) ) + +st_astext +---------- +MULTIPOINT(-2 3,1 2) + + +SELECT ST_AsText(ST_Union(ST_GeomFromText('POINT(1 2)'), + ST_GeomFromText('POINT(1 2)') ) ); +st_astext +---------- +POINT(1 2) + + + + See Also + +