[Enhancement] (GEO) Support MultiPolygon for Geometry functions

docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometryfromtext.md

@@ -26,7 +26,7 @@ under the License.
 
 ## Description
 
-Convert a linear WKT (Well Known Text) to the corresponding memory geometry
+Convert a WKT (Well Known Text) to the corresponding memory geometry
 
 
 ## Alias
@@ -44,13 +44,49 @@ ST_GEOMETRYFROMTEXT( <wkt>)
 |------------|---------|
 | `<wkt>`    | The memory form of the graph |
 
+## Support WKT Formats
+
+- `POINT` - A single point in space
+- `LINESTRING` - A sequence of connected line segments
+- `POLYGON` - A closed area defined by one or more rings, requiring at least three distinct points and closed ends.
+- `MULTIPOLYGON` - A collection of polygons, requiring polygons in a multipolygon can only share discrete points.
+
 ## Return Value
 
 The corresponding geometric storage form of WKB
 
+Returns NULL when the input WKT format does not conform to specifications or when the input is NULL.
+
 ## Examples
 
 ```sql
+-- POINT example
+SELECT ST_AsText(ST_GeometryFromText("POINT (1 1)"));
+```
+
+```text
++-----------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POINT (1 1)")) |
++-----------------------------------------------+
+| POINT (1 1)                                   |
++-----------------------------------------------+
+```
+
+```sql
+-- POINT illegal example(too many points)
+SELECT ST_AsText(ST_GeometryFromText("POINT (1 1, 2 2)"));
+```
+
+```text
++----------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POINT (1 1, 2 2)")) |
++----------------------------------------------------+
+| NULL                                               |
++----------------------------------------------------+
+```
+
+```sql
+-- LINESTRING example
 SELECT ST_AsText(ST_GeometryFromText("LINESTRING (1 1, 2 2)"));
 ```
 
@@ -60,4 +96,108 @@ SELECT ST_AsText(ST_GeometryFromText("LINESTRING (1 1, 2 2)"));
 +---------------------------------------------------------+
 | LINESTRING (1 1, 2 2)                                   |
 +---------------------------------------------------------+
+```
+
+```sql
+-- LINESTRING illegal example(too few verteices)
+SELECT ST_AsText(ST_GeometryFromText("LINESTRING (1 1)"));
+```
+
+```text
++----------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("LINESTRING (1 1)")) |
++----------------------------------------------------+
+| NULL                                               |
++----------------------------------------------------+
+```
+
+```sql
+-- POLYGON example
+SELECT ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))"));
+```
+
+``` text
++-----------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))")) |
++-----------------------------------------------------------------------+
+| POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))                                   |
++-----------------------------------------------------------------------+
+```
+
+```sql
+-- POLYGON illegal example(not closed end to end)
+SELECT ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 1 1, 0 1))"));
+```
+
+```text
++------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 1 1, 0 1))")) |
++------------------------------------------------------------------+
+| NULL                                                             |
++------------------------------------------------------------------+
+```
+
+```sql
+-- POLYGON illegal example(too few verteices)
+SELECT ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 0 0))"));
+```
+
+```text
++-------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 0 0))")) |
++-------------------------------------------------------------+
+| NULL                                                        |
++-------------------------------------------------------------+
+```
+
+```sql
+-- MULTIPOLYGON example
+SELECT ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 1 0, 1 1, 0 1, 0 0)), ((2 2, 3 2, 3 3, 2 3, 2 2)))"));
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 1 0, 1 1, 0 1, 0 0)), ((2 2, 3 2, 3 3, 2 3, 2 2)))")) |
++-----------------------------------------------------------------------------------------------------------+
+| MULTIPOLYGON (((0 0, 1 0, 1 1, 0 1, 0 0)), ((2 2, 3 2, 3 3, 2 3, 2 2)))                                   |
++-----------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+-- MULTIPOLYGON example (polygons in multipolygon only share discrete points.)
+SELECT ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0), (4 4, 6 4, 6 6, 4 6, 4 4)), ((4 5, 5 4, 6 5, 5 6, 4 5)))"));
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0), (4 4, 6 4, 6 6, 4 6, 4 4)), ((4 5, 5 4, 6 5, 5 6, 4 5)))")) |
++------------------------------------------------------------------------------------------------------------------------------------------+
+| MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0), (4 4, 6 4, 6 6, 4 6, 4 4)), ((4 5, 5 4, 6 5, 5 6, 4 5)))                                   |
++------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+``` sql
+-- MULTIPOLYGON illegal example(overlap exists)
+SELECT ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0)), ((10 0, 20 0, 20 10, 10 10, 10 0)))"));
+```
+
+```text
++----------------------------------------------------------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0)), ((10 0, 20 0, 20 10, 10 10, 10 0)))")) |
++----------------------------------------------------------------------------------------------------------------------+
+| NULL                                                                                                                 |
++----------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+-- input NULL
+SELECT ST_AsText(ST_GeometryFromText(NULL));
+```
+
+```text
++--------------------------------------+
+| ST_AsText(ST_GeometryFromText(NULL)) |
++--------------------------------------+
+| NULL                                 |
++--------------------------------------+
 ```

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometryfromtext.md

@@ -26,7 +26,7 @@ under the License.
 
 ## 描述
 
-将一个线型 WKT（Well Known Text）转化为对应的内存的几何形式
+将一个 WKT（Well Known Text）转化为对应的内存的几何形式
 
 ## 别名
 
@@ -43,13 +43,48 @@ ST_GEOMETRYFROMTEXT( <wkt>)
 | -- |---------|
 | `<WKB>` | 图形的内存形式 |
 
+支持的WKT格式:
+- `POINT` - 空间中的单个点
+- `LINESTRING` - 连接的线段序列
+- `POLYGON` - 由一个或多个环定义的封闭区域, 要求至少有三个不同的点且首尾闭合
+- `MULTIPOLYGON` - 多边形的集合, 要求多边形之间仅能存在有限个离散点的接触
+
 ## 返回值
 
 WKB 的对应的几何存储形式
 
+当输入的 WKT 格式不符合规范或输入为 NULL 时返回 NULL。
+
 ## 举例
 
 ```sql
+-- POINT 样例
+SELECT ST_AsText(ST_GeometryFromText("POINT (1 1)"));
+```
+
+```text
++-----------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POINT (1 1)")) |
++-----------------------------------------------+
+| POINT (1 1)                                   |
++-----------------------------------------------+
+```
+
+```sql
+-- POINT 不合法样例(端点过多)
+SELECT ST_AsText(ST_GeometryFromText("POINT (1 1, 2 2)"));
+```
+
+```text
++----------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POINT (1 1, 2 2)")) |
++----------------------------------------------------+
+| NULL                                               |
++----------------------------------------------------+
+```
+
+```sql
+-- LINESTRING 样例
 SELECT ST_AsText(ST_GeometryFromText("LINESTRING (1 1, 2 2)"));
 ```
 
@@ -59,4 +94,108 @@ SELECT ST_AsText(ST_GeometryFromText("LINESTRING (1 1, 2 2)"));
 +---------------------------------------------------------+
 | LINESTRING (1 1, 2 2)                                   |
 +---------------------------------------------------------+
+```
+
+```sql
+-- LINESTRING 不合法样例(端点过少)
+SELECT ST_AsText(ST_GeometryFromText("LINESTRING (1 1)"));
+```
+
+```text
++----------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("LINESTRING (1 1)")) |
++----------------------------------------------------+
+| NULL                                               |
++----------------------------------------------------+
+```
+
+```sql
+-- POLYGON 样例
+SELECT ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))"));
+```
+
+``` text
++-----------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))")) |
++-----------------------------------------------------------------------+
+| POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))                                   |
++-----------------------------------------------------------------------+
+```
+
+```sql
+-- POLYGON 不合法样例(首尾不闭合)
+SELECT ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 1 1, 0 1))"));
+```
+
+```text
++------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 1 1, 0 1))")) |
++------------------------------------------------------------------+
+| NULL                                                             |
++------------------------------------------------------------------+
+```
+
+```sql
+-- POLYGON 不合法样例(端点过少)
+SELECT ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 0 0))"));
+```
+
+```text
++-------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("POLYGON ((0 0, 1 0, 0 0))")) |
++-------------------------------------------------------------+
+| NULL                                                        |
++-------------------------------------------------------------+
+```
+
+```sql
+-- MULTIPOLYGON 样例
+SELECT ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 1 0, 1 1, 0 1, 0 0)), ((2 2, 3 2, 3 3, 2 3, 2 2)))"));
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 1 0, 1 1, 0 1, 0 0)), ((2 2, 3 2, 3 3, 2 3, 2 2)))")) |
++-----------------------------------------------------------------------------------------------------------+
+| MULTIPOLYGON (((0 0, 1 0, 1 1, 0 1, 0 0)), ((2 2, 3 2, 3 3, 2 3, 2 2)))                                   |
++-----------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+-- MULTIPOLYGON 样例(仅有有限个离散点接触)
+SELECT ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0), (4 4, 6 4, 6 6, 4 6, 4 4)), ((4 5, 5 4, 6 5, 5 6, 4 5)))"));
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0), (4 4, 6 4, 6 6, 4 6, 4 4)), ((4 5, 5 4, 6 5, 5 6, 4 5)))")) |
++------------------------------------------------------------------------------------------------------------------------------------------+
+| MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0), (4 4, 6 4, 6 6, 4 6, 4 4)), ((4 5, 5 4, 6 5, 5 6, 4 5)))                                   |
++------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+``` sql
+-- MULTIPOLYGON 不合法样例(存在重叠部分)
+SELECT ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0)), ((10 0, 20 0, 20 10, 10 10, 10 0)))"));
+```
+
+```text
++----------------------------------------------------------------------------------------------------------------------+
+| ST_AsText(ST_GeometryFromText("MULTIPOLYGON (((0 0, 10 0, 10 10, 0 10, 0 0)), ((10 0, 20 0, 20 10, 10 10, 10 0)))")) |
++----------------------------------------------------------------------------------------------------------------------+
+| NULL                                                                                                                 |
++----------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+-- 输入 NULL
+SELECT ST_AsText(ST_GeometryFromText(NULL));
+```
+
+```text
++--------------------------------------+
+| ST_AsText(ST_GeometryFromText(NULL)) |
++--------------------------------------+
+| NULL                                 |
++--------------------------------------+
 ```