docs: Add Geometry aggregate function docs (#3152)

Author: b41sh

docs/cn/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-st-collect.md

@@ -0,0 +1,46 @@
+---
+title: ST_COLLECT
+---
+
+将多个 GEOMETRY 值收集为一个 GEOMETRY 结果。
+
+该函数仅支持 GEOMETRY 类型。
+
+## 语法
+
+```sql
+ST_COLLECT(<geometry>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `<geometry>` | GEOMETRY 类型的表达式。 |
+
+## 返回类型
+
+GEOMETRY。根据输入类型不同，返回值可能是 `MULTIPOINT`、`MULTILINESTRING`、`MULTIPOLYGON` 或 `GEOMETRYCOLLECTION`。
+
+:::note
+- 会忽略 NULL 输入行。
+- 如果所有输入行都是 NULL，则返回 NULL。
+- 如果输入 GEOMETRY 的 SRID 不一致，函数会报错。
+:::
+
+## 示例
+
+```sql
+WITH data AS (
+    SELECT TO_GEOMETRY('POINT(0 0)') AS g
+    UNION ALL
+    SELECT TO_GEOMETRY('LINESTRING(1 1,2 2)')
+)
+SELECT ST_ASWKT(ST_COLLECT(g)) FROM data;
+
+╭────────────────────────────────────────────────────╮
+│               st_aswkt(st_collect(g))              │
+├────────────────────────────────────────────────────┤
+│ GEOMETRYCOLLECTION(POINT(0 0),LINESTRING(1 1,2 2)) │
+╰────────────────────────────────────────────────────╯
+```

docs/cn/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-st-envelope-agg.md

@@ -0,0 +1,48 @@
+---
+title: ST_ENVELOPE_AGG
+---
+
+对多个 GEOMETRY 值做聚合，返回覆盖所有非 NULL 输入的最小外接矩形。
+
+该函数仅支持 GEOMETRY 类型。
+
+## 语法
+
+```sql
+ST_ENVELOPE_AGG(<geometry>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `<geometry>` | GEOMETRY 类型的表达式。 |
+
+## 返回类型
+
+GEOMETRY。
+
+:::note
+- 会忽略 NULL 输入行。
+- 如果所有输入行都是 NULL，则返回 NULL。
+- 如果输入 GEOMETRY 的 SRID 不一致，函数会报错。
+:::
+
+## 示例
+
+```sql
+WITH data AS (
+    SELECT TO_GEOMETRY('POINT(1 1)') AS g
+    UNION ALL
+    SELECT TO_GEOMETRY('POINT(4 2)')
+    UNION ALL
+    SELECT TO_GEOMETRY('POINT(2 5)')
+)
+SELECT ST_ASWKT(ST_ENVELOPE_AGG(g)) FROM data;
+
+╭────────────────────────────────╮
+│  st_aswkt(st_envelope_agg(g))  │
+├────────────────────────────────┤
+│ POLYGON((1 1,4 1,4 5,1 5,1 1)) │
+╰────────────────────────────────╯
+```

docs/cn/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-st-intersection-agg.md

@@ -0,0 +1,46 @@
+---
+title: ST_INTERSECTION_AGG
+---
+
+对多个 GEOMETRY 值逐步执行 `ST_INTERSECTION`，并返回它们共同重叠的部分。
+
+该函数仅支持 GEOMETRY 类型。
+
+## 语法
+
+```sql
+ST_INTERSECTION_AGG(<geometry>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `<geometry>` | GEOMETRY 类型的表达式。 |
+
+## 返回类型
+
+GEOMETRY。
+
+:::note
+- 会忽略 NULL 输入行。
+- 如果所有输入行都是 NULL，则返回 NULL。
+- 如果输入 GEOMETRY 的 SRID 不一致，函数会报错。
+:::
+
+## 示例
+
+```sql
+WITH data AS (
+    SELECT TO_GEOMETRY('POLYGON((0 0,4 0,4 4,0 4,0 0))') AS g
+    UNION ALL
+    SELECT TO_GEOMETRY('POLYGON((1 1,3 1,3 3,1 3,1 1))')
+)
+SELECT ST_ASWKT(ST_INTERSECTION_AGG(g)) FROM data;
+
+╭──────────────────────────────────╮
+│ st_aswkt(st_intersection_agg(g)) │
+├──────────────────────────────────┤
+│ POLYGON((1 3,1 1,3 1,3 3,1 3))   │
+╰──────────────────────────────────╯
+```

docs/cn/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-st-union-agg.md

@@ -0,0 +1,46 @@
+---
+title: ST_UNION_AGG
+---
+
+对多个 GEOMETRY 值逐步执行 `ST_UNION`，并返回合并后的 GEOMETRY 结果。
+
+该函数仅支持 GEOMETRY 类型。
+
+## 语法
+
+```sql
+ST_UNION_AGG(<geometry>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `<geometry>` | GEOMETRY 类型的表达式。 |
+
+## 返回类型
+
+GEOMETRY。
+
+:::note
+- 会忽略 NULL 输入行。
+- 如果所有输入行都是 NULL，则返回 NULL。
+- 如果输入 GEOMETRY 的 SRID 不一致，函数会报错。
+:::
+
+## 示例
+
+```sql
+WITH data AS (
+    SELECT TO_GEOMETRY('POINT(0 0)') AS g
+    UNION ALL
+    SELECT TO_GEOMETRY('POINT(1 1)')
+)
+SELECT ST_ASWKT(ST_UNION_AGG(g)) FROM data;
+
+╭───────────────────────────╮
+│ st_aswkt(st_union_agg(g)) │
+├───────────────────────────┤
+│ MULTIPOINT(0 0,1 1)       │
+╰───────────────────────────╯
+```

docs/cn/sql-reference/20-sql-functions/07-aggregate-functions/index.md

@@ -61,6 +61,15 @@ title: '聚合函数'
 | [GROUP_ARRAY_MOVING_AVG](aggregate-group-array-moving-avg.md) | 计算数组的移动平均值 | `GROUP_ARRAY_MOVING_AVG(3)(values)` → `[null, null, 3.0, 6.0, 9.0]` |
 | [GROUP_ARRAY_MOVING_SUM](aggregate-group-array-moving-sum.md) | 计算数组的移动总和 | `GROUP_ARRAY_MOVING_SUM(2)(values)` → `[null, 3, 7, 11, 15]` |
 
+## 地理空间聚合
+
+| 函数 | 描述 | 示例 |
+|----------|-------------|---------|
+| [ST_UNION_AGG](aggregate-st-union-agg.md) | 对分组内的 GEOMETRY 值做合并 | `ST_UNION_AGG(geom)` → `MULTIPOINT(...)` |
+| [ST_INTERSECTION_AGG](aggregate-st-intersection-agg.md) | 对分组内的 GEOMETRY 值做相交 | `ST_INTERSECTION_AGG(geom)` → `POLYGON(...)` |
+| [ST_ENVELOPE_AGG](aggregate-st-envelope-agg.md) | 返回分组内 GEOMETRY 值的最小外接矩形 | `ST_ENVELOPE_AGG(geom)` → `POLYGON(...)` |
+| [ST_COLLECT](aggregate-st-collect.md) | 将分组内的 GEOMETRY 值收集为一个 GEOMETRY 结果 | `ST_COLLECT(geom)` → `GEOMETRYCOLLECTION(...)` |
+
 ## 字符串聚合
 
 | 函数 | 描述 | 示例 |

docs/cn/sql-reference/20-sql-functions/09-geospatial-functions/index.md

@@ -49,6 +49,8 @@ Databend 内置两套互补的地理空间能力：PostGIS 风格的几何（Geo
 | 函数 | 描述 | 说明 | 示例 |
 |----------|-------------|------|---------|
 | [ST_DIMENSION](st-dimension.md) | 返回拓扑维度 |  | `ST_DIMENSION(ST_MAKEGEOMPOINT(-122.35, 37.55))` → `0` |
+| [ST_CENTROID](st-centroid.md) | 返回几何体的质心 | 仅 GEOMETRY | `ST_CENTROID(TO_GEOMETRY('LINESTRING(0 0, 2 0)'))` → `POINT(1 0)` |
+| [ST_ENVELOPE](st-envelope.md) | 返回最小外接矩形 | 仅 GEOMETRY | `ST_ENVELOPE(TO_GEOMETRY('LINESTRING(0 0, 2 3)'))` → `POLYGON((0 0,2 0,2 3,0 3,0 0))` |
 | [ST_SRID](st-srid.md) | 返回几何体的 SRID |  | `ST_SRID(ST_MAKEGEOMPOINT(-122.35, 37.55))` → `4326` |
 | [ST_POINTN](st-pointn.md) | 返回 LineString 中的指定点 |  | `ST_POINTN(ST_MAKELINE(...), 1)` → `POINT(-122.35 37.55)` |
 | [ST_STARTPOINT](st-startpoint.md) | 返回 LineString 的起点 |  | `ST_STARTPOINT(ST_MAKELINE(...))` → `POINT(-122.35 37.55)` |
@@ -73,6 +75,11 @@ Databend 内置两套互补的地理空间能力：PostGIS 风格的几何（Geo
 | [ST_EQUALS](st-equals.md) | 测试两个几何体是否空间相等 | 仅 GEOMETRY | `ST_EQUALS(TO_GEOMETRY('POINT(1 1)'), TO_GEOMETRY('POINT(1 1)'))` → `TRUE` |
 | [ST_LENGTH](st-length.md) | 测量 LineString 的长度 |  | `ST_LENGTH(ST_MAKELINE(...))` → `5.57` |
 | [ST_DISTANCE](st-distance.md) | 测量几何体之间的距离 |  | `ST_DISTANCE(ST_MAKEGEOMPOINT(-122.35, 37.55), ST_MAKEGEOMPOINT(-122.40, 37.60))` → `5.57` |
+| [ST_DWITHIN](st-dwithin.md) | 测试两个几何体是否在指定距离内 | 仅 GEOMETRY | `ST_DWITHIN(TO_GEOMETRY('POINT(0 0)'), TO_GEOMETRY('POINT(1 1)'), 1.5)` → `TRUE` |
+| [ST_UNION](st-union.md) | 返回两个几何体的合并结果 | 仅 GEOMETRY | `ST_UNION(TO_GEOMETRY('POINT(0 0)'), TO_GEOMETRY('POINT(1 1)'))` → `MULTIPOINT(0 0,1 1)` |
+| [ST_INTERSECTION](st-intersection.md) | 返回两个几何体的重叠部分 | 仅 GEOMETRY | `ST_INTERSECTION(TO_GEOMETRY('LINESTRING(0 0, 1 1)'), TO_GEOMETRY('LINESTRING(0 0, 1 1)'))` → `LINESTRING(0 0,1 1)` |
+| [ST_DIFFERENCE](st-difference.md) | 返回第一个几何体中未被第二个覆盖的部分 | 仅 GEOMETRY | `ST_DIFFERENCE(TO_GEOMETRY('POINT(0 0)'), TO_GEOMETRY('POINT(1 1)'))` → `POINT(0 0)` |
+| [ST_SYMDIFFERENCE](st-symdifference.md) | 返回两个几何体中不重叠的部分 | 仅 GEOMETRY | `ST_SYMDIFFERENCE(TO_GEOMETRY('POINT(0 0)'), TO_GEOMETRY('POINT(1 1)'))` → `MULTIPOINT(0 0,1 1)` |
 
 ## 变换
 

docs/cn/sql-reference/20-sql-functions/09-geospatial-functions/st-centroid.md

@@ -0,0 +1,48 @@
+---
+title: ST_CENTROID
+---
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="引入或更新于：v1.2.895"/>
+
+返回 GEOMETRY 对象的质心。
+
+该函数仅支持 GEOMETRY 类型。
+
+## 语法
+
+```sql
+ST_CENTROID(<geometry>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `<geometry>` | 必须是 GEOMETRY 类型的表达式。 |
+
+## 返回类型
+
+GEOMETRY。
+
+## 示例
+
+```sql
+SELECT ST_ASWKT(ST_CENTROID(TO_GEOMETRY('POINT(1 2)')));
+
+╭──────────────────────────────────────────────────╮
+│ st_aswkt(st_centroid(to_geometry('POINT(1 2)'))) │
+├──────────────────────────────────────────────────┤
+│ POINT(1 2)                                       │
+╰──────────────────────────────────────────────────╯
+```
+
+```sql
+SELECT ST_ASWKT(ST_CENTROID(TO_GEOMETRY('LINESTRING(0 0, 2 0)')));
+
+╭────────────────────────────────────────────────────────────╮
+│ st_aswkt(st_centroid(to_geometry('LINESTRING(0 0, 2 0)'))) │
+├────────────────────────────────────────────────────────────┤
+│ POINT(1 0)                                                 │
+╰────────────────────────────────────────────────────────────╯
+```

docs/cn/sql-reference/20-sql-functions/09-geospatial-functions/st-difference.md

@@ -0,0 +1,43 @@
+---
+title: ST_DIFFERENCE
+---
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="引入或更新于：v1.2.895"/>
+
+返回第一个 GEOMETRY 对象中未被第二个 GEOMETRY 对象覆盖的部分。
+
+该函数仅支持 GEOMETRY 类型。
+
+## 语法
+
+```sql
+ST_DIFFERENCE(<geometry1>, <geometry2>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `<geometry1>` | 必须是 GEOMETRY 类型的表达式。 |
+| `<geometry2>` | 必须是 GEOMETRY 类型的表达式。 |
+
+:::note
+- 如果两个输入 GEOMETRY 对象的 SRID 不同，函数会报错。
+:::
+
+## 返回类型
+
+GEOMETRY。
+
+## 示例
+
+```sql
+SELECT ST_ASWKT(ST_DIFFERENCE(TO_GEOMETRY('POINT(0 0)'), TO_GEOMETRY('POINT(1 1)')));
+
+╭───────────────────────────────────────────────────────────────────────────────╮
+│ st_aswkt(st_difference(to_geometry('POINT(0 0)'), to_geometry('POINT(1 1)'))) │
+├───────────────────────────────────────────────────────────────────────────────┤
+│ POINT(0 0)                                                                    │
+╰───────────────────────────────────────────────────────────────────────────────╯
+```

docs/cn/sql-reference/20-sql-functions/09-geospatial-functions/st-dwithin.md

@@ -0,0 +1,54 @@
+---
+title: ST_DWITHIN
+---
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="引入或更新于：v1.2.895"/>
+
+如果两个 GEOMETRY 对象之间的欧氏距离不超过指定距离，则返回 TRUE。
+
+该函数仅支持 GEOMETRY 类型。
+
+## 语法
+
+```sql
+ST_DWITHIN(<geometry1>, <geometry2>, <distance>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `<geometry1>` | 必须是 GEOMETRY 类型的表达式。 |
+| `<geometry2>` | 必须是 GEOMETRY 类型的表达式。 |
+| `<distance>` | 最大欧氏距离，必须是可转换为 Float64 的数值。 |
+
+:::note
+- 如果两个输入 GEOMETRY 对象的 SRID 不同，函数会报错。
+:::
+
+## 返回类型
+
+布尔值（Boolean）。
+
+## 示例
+
+```sql
+SELECT ST_DWITHIN(TO_GEOMETRY('POINT(0 0)'), TO_GEOMETRY('POINT(1 1)'), 1.5);
+
+╭───────────────────────────────────────────────────────────────────────╮
+│ st_dwithin(to_geometry('POINT(0 0)'), to_geometry('POINT(1 1)'), 1.5) │
+├───────────────────────────────────────────────────────────────────────┤
+│ true                                                                  │
+╰───────────────────────────────────────────────────────────────────────╯
+```
+
+```sql
+SELECT ST_DWITHIN(TO_GEOMETRY('POINT(0 0)'), TO_GEOMETRY('LINESTRING(2 0, 2 2)'), 1.9);
+
+╭─────────────────────────────────────────────────────────────────────────────────╮
+│ st_dwithin(to_geometry('POINT(0 0)'), to_geometry('LINESTRING(2 0, 2 2)'), 1.9) │
+├─────────────────────────────────────────────────────────────────────────────────┤
+│ false                                                                           │
+╰─────────────────────────────────────────────────────────────────────────────────╯
+```