diff --git a/docs/docs.md b/docs/docs.md index eab4c4b6..e9f6430a 100644 --- a/docs/docs.md +++ b/docs/docs.md @@ -1,5 +1,14 @@ # DuckDB Spatial Extension +__Table of contents__ + +- [Introduction](#introduction) +- [Scalar Functions](#scalar-functions) +- [Aggregate Functions](#aggregate-functions) +- [Table Functions](#table-functions) +- [Functions by tag](#functions-by-tag) +# Introduction + The spatial extension provides support for geospatial data processing in DuckDB. @@ -283,11 +292,49 @@ _Collects geometries into a collection geometry_ ### Description -Collects a list of geometries into a collection geometry +Collects a list of geometries into a collection geometry. +- If all geometries are `POINT`'s, a `MULTIPOINT` is returned. +- If all geometries are `LINESTRING`'s, a `MULTILINESTRING` is returned. +- If all geometries are `POLYGON`'s, a `MULTIPOLYGON` is returned. +- Otherwise if the input collection contains a mix of geometry types, a `GEOMETRYCOLLECTION` is returned. + +Empty and `NULL` geometries are ignored. If all geometries are empty or `NULL`, a `GEOMETRYCOLLECTION EMPTY` is returned. ### Examples -TODO +```sql +-- With all POINT's, a MULTIPOINT is returned +SELECT ST_Collect([ST_Point(1, 2), ST_Point(3, 4)]); +---- +MULTIPOINT (1 2, 3 4) + +-- With mixed geometry types, a GEOMETRYCOLLECTION is returned +SELECT ST_Collect([ST_Point(1, 2), ST_GeomFromText('LINESTRING(3 4, 5 6)')]); +---- +GEOMETRYCOLLECTION (POINT (1 2), LINESTRING (3 4, 5 6)) + +-- Note that the empty geometry is ignored, so the result is a MULTIPOINT +SELECT ST_Collect([ST_Point(1, 2), NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); +---- +MULTIPOINT (1 2) + +-- If all geometries are empty or NULL, a GEOMETRYCOLLECTION EMPTY is returned +SELECT ST_Collect([NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); +---- +GEOMETRYCOLLECTION EMPTY +``` + +Tip: You can use the `ST_Collect` function together with the `list()` aggregate function to collect multiple rows of geometries into a single geometry collection: + +```sql +CREATE TABLE points (geom GEOMETRY); + +INSERT INTO points VALUES (ST_Point(1, 2)), (ST_Point(3, 4)); + +SELECT ST_Collect(list(geom)) FROM points; +---- +MULTIPOINT (1 2, 3 4) +``` ## ST_CollectionExtract diff --git a/docs/src/functions/scalar/st_collect.md b/docs/src/functions/scalar/st_collect.md index 8963e503..e7f6f321 100644 --- a/docs/src/functions/scalar/st_collect.md +++ b/docs/src/functions/scalar/st_collect.md @@ -24,8 +24,46 @@ ### Description -Collects a list of geometries into a collection geometry +Collects a list of geometries into a collection geometry. +- If all geometries are `POINT`'s, a `MULTIPOINT` is returned. +- If all geometries are `LINESTRING`'s, a `MULTILINESTRING` is returned. +- If all geometries are `POLYGON`'s, a `MULTIPOLYGON` is returned. +- Otherwise if the input collection contains a mix of geometry types, a `GEOMETRYCOLLECTION` is returned. + +Empty and `NULL` geometries are ignored. If all geometries are empty or `NULL`, a `GEOMETRYCOLLECTION EMPTY` is returned. ### Examples -TODO +```sql +-- With all POINT's, a MULTIPOINT is returned +SELECT ST_Collect([ST_Point(1, 2), ST_Point(3, 4)]); +---- +MULTIPOINT (1 2, 3 4) + +-- With mixed geometry types, a GEOMETRYCOLLECTION is returned +SELECT ST_Collect([ST_Point(1, 2), ST_GeomFromText('LINESTRING(3 4, 5 6)')]); +---- +GEOMETRYCOLLECTION (POINT (1 2), LINESTRING (3 4, 5 6)) + +-- Note that the empty geometry is ignored, so the result is a MULTIPOINT +SELECT ST_Collect([ST_Point(1, 2), NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); +---- +MULTIPOINT (1 2) + +-- If all geometries are empty or NULL, a GEOMETRYCOLLECTION EMPTY is returned +SELECT ST_Collect([NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); +---- +GEOMETRYCOLLECTION EMPTY +``` + +Tip: You can use the `ST_Collect` function together with the `list()` aggregate function to collect multiple rows of geometries into a single geometry collection: + +```sql +CREATE TABLE points (geom GEOMETRY); + +INSERT INTO points VALUES (ST_Point(1, 2)), (ST_Point(3, 4)); + +SELECT ST_Collect(list(geom)) FROM points; +---- +MULTIPOINT (1 2, 3 4) +``` diff --git a/docs/src/generate.py b/docs/src/generate.py index e84d7308..d74a3039 100755 --- a/docs/src/generate.py +++ b/docs/src/generate.py @@ -94,7 +94,16 @@ def main(): # Write the header f.write("# DuckDB Spatial Extension\n\n") + # Write a table of contents + f.write("__Table of contents__\n\n") + f.write("- [Introduction](#introduction)\n") + f.write("- [Scalar Functions](#scalar-functions)\n") + f.write("- [Aggregate Functions](#aggregate-functions)\n") + f.write("- [Table Functions](#table-functions)\n") + f.write("- [Functions by tag](#functions-by-tag)\n") + # Write the intro from the into.md file + f.write("# Introduction\n\n") with open(os.path.join(os.path.dirname(os.path.realpath(__file__)), "intro.md"), 'r') as intro: f.write(intro.read()) diff --git a/test/sql/geometry/st_collect.test b/test/sql/geometry/st_collect.test index 4b0b62dc..1b3bc008 100644 --- a/test/sql/geometry/st_collect.test +++ b/test/sql/geometry/st_collect.test @@ -40,7 +40,7 @@ MULTIPOINT (1 2) query I SElECT ST_Collect([ST_Point(1, 2), NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); ---- -GEOMETRYCOLLECTION (POINT (1 2), GEOMETRYCOLLECTION EMPTY) +MULTIPOINT (1 2) # Test with only null query I