update st_collec test

duckdb · Nov 27, 2023 · b56e9e2 · b56e9e2
1 parent 100d4c4
commit b56e9e2
Show file tree

Hide file tree

Showing 4 changed files with 99 additions and 5 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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