[Feature] Add ST_Within spatial function documentation

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

@@ -0,0 +1,169 @@
+---
+{
+    "title": "ST_WITHIN",
+    "language": "en",
+    "description": "Determines whether one geometric shape (shape1) is completely inside another geometric shape (shape2)."
+}
+---
+
+## Description
+
+Determines whether one geometric shape (shape1) is completely inside another geometric shape (shape2). Returns 1 if shape1 is entirely within shape2; otherwise, returns 0.
+
+`ST_WITHIN(shape1, shape2)` is logically equivalent to `ST_CONTAINS(shape2, shape1)`.
+
+- For points: The point must lie inside or on the boundary of the polygon.
+- For lines: All points of the line must lie inside or on the boundary of the polygon.
+- For polygons: The inner polygon must be entirely inside the outer polygon (boundaries can overlap).
+
+## Syntax
+
+```sql
+ST_WITHIN( <shape1>, <shape2>)
+```
+
+## Parameters
+
+| Parameters       | Description                     |
+|----------|------------------------|
+| `<shape1>` | The geometric shape to check if it is inside the other shape, supporting types such as Point, Line, Polygon, etc. |
+| `<shape2>` | The geometric shape used to check if it contains shape1, supporting the Polygon type. |
+
+## Return Value
+
+- 1: Indicates that shape1 is completely inside shape2.
+- 0: Indicates that shape1 is not inside shape2.
+
+ST_WITHIN has the following edge cases:
+
+- Returns NULL if either input parameter is NULL.
+- Returns NULL if the input geometric shape is invalid (e.g., a self-intersecting polygon).
+- Returns 0 if shape1 lies partially on the boundary but also partially outside shape2.
+
+## Example
+
+Point inside polygon
+
+```sql
+SELECT ST_Within(ST_Point(5, 5), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-------------------------------------------------------------------------------------+
+| st_within(st_point(5.0, 5.0), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-------------------------------------------------------------------------------------+
+|                                                                                   1 |
++-------------------------------------------------------------------------------------+
+```
+
+Point outside polygon
+
+```sql
+SELECT ST_Within(ST_Point(50, 50), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++---------------------------------------------------------------------------------------+
+| st_within(st_point(50.0, 50.0), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++---------------------------------------------------------------------------------------+
+|                                                                                     0 |
++---------------------------------------------------------------------------------------+
+```
+
+Line completely inside polygon
+
+```sql
+SELECT ST_Within(ST_LineFromText("LINESTRING (2 2, 8 8)"), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------+
+| st_within(st_linefromtext('LINESTRING (2 2, 8 8)'), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-----------------------------------------------------------------------------------------------------------+
+|                                                                                                         1 |
++-----------------------------------------------------------------------------------------------------------+
+```
+
+Line partially outside polygon
+
+```sql
+SELECT ST_Within(ST_LineFromText("LINESTRING (5 5, 15 15)"), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-------------------------------------------------------------------------------------------------------------+
+| st_within(st_linefromtext('LINESTRING (5 5, 15 15)'), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-------------------------------------------------------------------------------------------------------------+
+|                                                                                                           0 |
++-------------------------------------------------------------------------------------------------------------+
+```
+
+Polygon completely inside polygon
+
+```sql
+SELECT ST_Within(ST_Polygon("POLYGON ((2 2, 8 2, 8 8, 2 8, 2 2))"), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------------------+
+| st_within(st_polygon('POLYGON ((2 2, 8 2, 8 8, 2 8, 2 2))'), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-----------------------------------------------------------------------------------------------------------------------+
+|                                                                                                                     1 |
++-----------------------------------------------------------------------------------------------------------------------+
+```
+
+Polygon partially outside polygon
+
+```sql
+SELECT ST_Within(ST_Polygon("POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))"), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++---------------------------------------------------------------------------------------------------------------------------+
+| st_within(st_polygon('POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))'), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++---------------------------------------------------------------------------------------------------------------------------+
+|                                                                                                                         0 |
++---------------------------------------------------------------------------------------------------------------------------+
+```
+
+Point on polygon boundary
+
+```sql
+SELECT ST_Within(ST_Point(0, 5), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-----------------------------------------------------------------------------------+
+| st_within(st_point(0.0, 5.0), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-----------------------------------------------------------------------------------+
+|                                                                                 1 |
++-----------------------------------------------------------------------------------+
+```
+
+NULL parameter (returns NULL)
+
+```sql
+SELECT ST_Within(ST_Point(5, 5), NULL);
+```
+
+```text
++-----------------------------------+
+| ST_Within(ST_Point(5, 5), NULL)   |
++-----------------------------------+
+|                              NULL |
++-----------------------------------+
+```
+
+Self-intersecting polygon as parameter
+
+```sql
+SELECT ST_Within(ST_Point(0.5, 0.5), ST_Polygon("POLYGON ((0 0, 1 1, 0 1, 1 0, 0 0))"));
+```
+
+```text
++-----------------------------------------------------------------------------------+
+| st_within(st_point(0.5, 0.5), st_polygon('POLYGON ((0 0, 1 1, 0 1, 1 0, 0 0))')) |
++-----------------------------------------------------------------------------------+
+|                                                                              NULL |
++-----------------------------------------------------------------------------------+
+```

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

@@ -0,0 +1,190 @@
+---
+{
+    "title": "ST_WITHIN",
+    "language": "zh-CN",
+    "description": "判断一个几何图形（shape1）是否完全位于另一个几何图形（shape2）的内部。若 shape1 的所有点都位于 shape2 内部，则返回 1；否则返回 0。"
+}
+---
+
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+
+## 描述
+
+判断一个几何图形（shape1）是否完全位于另一个几何图形（shape2）的内部。若 shape1 的所有点都位于 shape2 内部，则返回 1；否则返回 0。
+
+`ST_WITHIN(shape1, shape2)` 在逻辑上等价于 `ST_CONTAINS(shape2, shape1)`。
+
+- 对于点：点必须位于多边形内部或边界上。
+- 对于线：线的所有点必须位于多边形内部或边界上。
+- 对于多边形：内部多边形必须完全位于外部多边形的内部（边界可以重叠）。
+
+## 语法
+
+```sql
+ST_WITHIN( <shape1>, <shape2>)
+```
+
+## 参数
+
+| 参数       | 说明                     |
+|----------|------------------------|
+| `<shape1>` | 用于判断是否在另一个图形内部的几何图形，支持 Point、Line、Polygon 等类型。 |
+| `<shape2>` | 用于判断是否包含 shape1 的几何图形，支持 Polygon 类型。 |
+
+## 返回值
+
+返回 1：shape1 完全位于 shape2 内部。
+
+返回 0：shape1 不位于 shape2 内部。
+
+ST_WITHIN 存在以下边缘情况：
+
+- 若任一输入参数为 NULL，返回 NULL。
+- 若输入的几何图形无效（如自相交的多边形），返回 NULL。
+- 若 shape1 部分位于 shape2 的边界上，但部分在 shape2 外部，返回 0。
+
+## 举例
+
+点在多边形内部
+
+```sql
+SELECT ST_Within(ST_Point(5, 5), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-------------------------------------------------------------------------------------+
+| st_within(st_point(5.0, 5.0), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-------------------------------------------------------------------------------------+
+|                                                                                   1 |
++-------------------------------------------------------------------------------------+
+```
+
+点在多边形外部
+
+```sql
+SELECT ST_Within(ST_Point(50, 50), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++---------------------------------------------------------------------------------------+
+| st_within(st_point(50.0, 50.0), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++---------------------------------------------------------------------------------------+
+|                                                                                     0 |
++---------------------------------------------------------------------------------------+
+```
+
+线完全在多边形内部
+
+```sql
+SELECT ST_Within(ST_LineFromText("LINESTRING (2 2, 8 8)"), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------+
+| st_within(st_linefromtext('LINESTRING (2 2, 8 8)'), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-----------------------------------------------------------------------------------------------------------+
+|                                                                                                         1 |
++-----------------------------------------------------------------------------------------------------------+
+```
+
+线部分在多边形外部
+
+```sql
+SELECT ST_Within(ST_LineFromText("LINESTRING (5 5, 15 15)"), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-------------------------------------------------------------------------------------------------------------+
+| st_within(st_linefromtext('LINESTRING (5 5, 15 15)'), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-------------------------------------------------------------------------------------------------------------+
+|                                                                                                           0 |
++-------------------------------------------------------------------------------------------------------------+
+```
+
+多边形完全在另一个多边形内部
+
+```sql
+SELECT ST_Within(ST_Polygon("POLYGON ((2 2, 8 2, 8 8, 2 8, 2 2))"), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------------------+
+| st_within(st_polygon('POLYGON ((2 2, 8 2, 8 8, 2 8, 2 2))'), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-----------------------------------------------------------------------------------------------------------------------+
+|                                                                                                                     1 |
++-----------------------------------------------------------------------------------------------------------------------+
+```
+
+多边形部分在外部
+
+```sql
+SELECT ST_Within(ST_Polygon("POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))"), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++---------------------------------------------------------------------------------------------------------------------------+
+| st_within(st_polygon('POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))'), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++---------------------------------------------------------------------------------------------------------------------------+
+|                                                                                                                         0 |
++---------------------------------------------------------------------------------------------------------------------------+
+```
+
+点在多边形边界上
+
+```sql
+SELECT ST_Within(ST_Point(0, 5), ST_Polygon("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"));
+```
+
+```text
++-----------------------------------------------------------------------------------+
+| st_within(st_point(0.0, 5.0), st_polygon('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))')) |
++-----------------------------------------------------------------------------------+
+|                                                                                 1 |
++-----------------------------------------------------------------------------------+
+```
+
+参数为 NULL（返回 NULL）
+
+```sql
+SELECT ST_Within(ST_Point(5, 5), NULL);
+```
+
+```text
++-----------------------------------+
+| ST_Within(ST_Point(5, 5), NULL)   |
++-----------------------------------+
+|                              NULL |
++-----------------------------------+
+```
+
+自相交多边形作为参数
+
+```sql
+SELECT ST_Within(ST_Point(0.5, 0.5), ST_Polygon("POLYGON ((0 0, 1 1, 0 1, 1 0, 0 0))"));
+```
+
+```text
++-----------------------------------------------------------------------------------+
+| st_within(st_point(0.5, 0.5), st_polygon('POLYGON ((0 0, 1 1, 0 1, 1 0, 0 0))')) |
++-----------------------------------------------------------------------------------+
+|                                                                              NULL |
++-----------------------------------------------------------------------------------+
+```