add udf sql_reference (#938)

* add udf sql_reference

* add udf sql_reference

* add function-sql

* add function-sql

docs/MatrixOne/Overview/matrixone-feature-list.md

@@ -61,7 +61,7 @@
 | 存储过程 STORED PROCEDURE     | N                                  |
 | 触发器 TRIGGER                | N                                  |
 | 时间调度器 EVENT SCHEDULER     | N                                  |
-| 自定义函数 UDF                 | E                                  |
+| 自定义函数 UDF                 | Y                                  |
 | 物化视图 Materialized VIEW | N                                  |
 
 ## 流计算

docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-function-python.md

@@ -0,0 +1,95 @@
+# **CREATE FUNCTION...LANGUAGE PYTHON AS**
+
+## **语法说明**
+
+`CREATE FUNCTION...LANGUAGE PYTHON AS` 用于创建用户自定义 Python 函数。用户通过自己定义的函数，满足定制化需求，简化查询的编写。也可以通过导入外部 Python 文件或外部 whl 包来创建 UDF。
+
+在部分场景下，我们会希望 python 函数一次性接收多个元组来提高运行效率，MatrixOne 提供函数的 vector 选项来处理这种情况。
+
+MatrixOne Python UDF 目前不支持重载，函数名在一个 matrixone 集群要求是唯一的。
+
+## **语法结构**
+
+```sql
+> CREATE [ OR REPLACE ] FUNCTION <name> (
+[ <arg_name> <arg_data_type> ] [ , ... ] )
+RETURNS <result_data_type>  LANGUAGE PYTHON AS
+$$
+  <function_body>
+[ add.vector = True ]
+$$
+HANDLER = '<function_name>'
+```
+
+## **结构说明**
+
+- `<name>`：指定自定义函数的名称。
+
+- `<arg_name> <arg_data_type>`：用于指定自定义函数的参数，这里的参数只有名称和类型。
+
+- `RETURNS <result_data_type>`：用于声明自定义函数返回值的数据类型。
+
+- `<function_body>`：自定义函数的主体部分，必须包含一个 RETURN <value>语句，其中<value>用于指定自定义函数的返回值。
+
+- `[ add.vector = True ]`：标志 python 函数一次性接收多个元组。
+
+- `HANDLIER <function_name>:` 指定调用的 python 函数名称。
+
+## 类型映射
+
+为确保编写 Python UDF 过程中使用的数据类型与 MatrixOne 支持的数据类型保持一致，您需要关注二者间的数据类型映射关系，具体映射关系如下：
+
+| MatrixOne  类型                                           | Python 类型          |
+| -------------------------------------------------------- | --------------------------- |
+| bool                                                     | bool                        |
+| int8, int16, int32, int64, uint8, uint16, uint32, uint64 | int                         |
+| float32, float64                                         | float                       |
+| char, varchar, text, uuid                                | str                         |
+| json                                                     | str, int, float, list, dict |
+| time                                                     | datetime.timedelta          |
+| date                                                     | datetime.date               |
+| datetime, timestamp                                      | datetime.datetime           |
+| decimal64, decimal128                                    | decimal.Decimal             |
+| binary, varbinary, blob                                  | bytes                       |
+
+## **示例**
+
+**示例 1**
+
+```sql
+--用 python UDF 实现两数之和
+create or replace function py_add(a int, b int) returns int language python as 
+$$
+def add(a, b):
+  return a + b
+$$
+handler 'add';
+
+--调用函数
+mysql> select py_add(1,2);
++--------------+
+| py_add(1, 2) |
++--------------+
+|            3 |
++--------------+
+1 row in set (0.01 sec)
+```
+
+**示例 2**
+
+```sql
+create or replace function py_helloworld() returns varchar(255) language python as 
+$$
+def helloworld():
+  return "helloworld!"
+$$
+handler 'helloworld';
+
+mysql> select py_helloworld();
++-----------------+
+| py_helloworld() |
++-----------------+
+| helloworld!     |
++-----------------+
+1 row in set (0.01 sec)
+```

docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-function-sql.md

@@ -0,0 +1,68 @@
+# **CREATE FUNCTION...LANGUAGE SQL AS**
+
+## **语法说明**
+
+`CREATE FUNCTION...LANGUAGE SQL AS` 用于创建 SQL UDF。
+
+SQL 自定义函数是一种用户自己编写的 SQL 函数，可以根据特定需求执行自定义操作。这些函数可以用于查询、数据转换等任务，使得 sQL 代码更加模块化和可维护。
+
+MatrixOne SQL UDF 目前不支持重载，函数名在一个 matrixone 集群要求是唯一的。
+
+## **语法结构**
+
+```sql
+> CREATE [ OR REPLACE ] FUNCTION <name> (
+[ <arg_name> <arg_data_type> ] [ , ... ] )
+RETURNS <result_data_type>  LANGUAGE SQL AS 'function_body'
+```
+
+## **结构说明**
+
+- `<name>`：指定自定义函数的名称。
+
+- `<arg_name> <arg_data_type>`：用于指定自定义函数的参数，这里的参数只有名称和类型。
+
+- `RETURNS <result_data_type>`：用于声明自定义函数返回值的数据类型，完整的数据类型请查看[数据类型概览](../../../Reference/Data-Types/data-types.md)
+
+- `function_body`：自定义函数的主体部分。用户必须使用$1、$2,...以引用参数，而不是实际的参数名称。函数体支持 select 语句，且返回值唯一，如果 sql 函数体不是表达式，并且是表上的 select 语句，则查询应使用 limit 1 或不带 group by 子句的聚合函数将其结果限制为 1。
+
+## **示例**
+
+**示例 1**
+
+```sql
+--创建无参 sql 自定义函数
+
+mysql> create table t1(n1 int);
+Query OK, 0 rows affected (0.02 sec)
+
+mysql> insert into t1 values(1),(2),(3);
+Query OK, 3 rows affected (0.01 sec)
+
+mysql> CREATE FUNCTION t1_fun () RETURNS VARCHAR LANGUAGE SQL AS 'select n1 from t1 limit 1' ;
+Query OK, 0 rows affected (0.01 sec)
+
+mysql> select t1_fun();
++----------+
+| t1_fun() |
++----------+
+|        1 |
++----------+
+1 row in set (0.01 sec)
+```
+
+**示例 2**
+
+```sql
+--创建 sql 自定义函数返回两个参数的和
+mysql> CREATE FUNCTION twoadd (x int, y int) RETURNS int LANGUAGE SQL AS 'select $1 + $2' ;
+Query OK, 0 rows affected (0.02 sec)
+
+mysql> select twoadd(1,2);
++--------------+
+| twoadd(1, 2) |
++--------------+
+|            3 |
++--------------+
+1 row in set (0.00 sec)
+```

docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/drop-function.md

@@ -0,0 +1,50 @@
+# **DROP FUNCTION**
+
+## **语法说明**
+
+`DROP FUNCTION` 语句表示删除用户自定义函数。
+
+## **语法结构**
+
+```
+> DROP FUNCTION <name> ([<arg_data_type> ]… )
+```
+
+## **示例**
+
+**示例 1**
+
+```sql
+--删除有参函数
+
+create or replace function py_add(a int, b int) returns int language python as 
+$$
+def add(a, b):
+  return a + b
+$$
+handler 'add';
+
+mysql> select py_add(1,2);
++--------------+
+| py_add(1, 2) |
++--------------+
+|            3 |
++--------------+
+1 row in set (0.01 sec)
+
+--当我们不再需要该函数时，可以将其删除
+drop function py_add(int, int);
+
+```
+
+**示例 2**
+
+```sql
+--删除无参函数
+mysql> CREATE FUNCTION t1_fun () RETURNS VARCHAR LANGUAGE SQL AS 'select n1 from t1 limit 1' ;
+Query OK, 0 rows affected (0.01 sec)
+
+mysql> drop function t1_fun();
+Query OK, 0 rows affected (0.01 sec)
+
+```

docs/MatrixOne/Reference/SQL-Reference/Other/SHOW-Statements/show-function-status.md

@@ -4,7 +4,7 @@
 
 `SHOW FUNCTION STATUS` 是用来显示数据库中的所有函数的信息，包括函数名、数据库名、创建时间等等。
 
-`SHOW FUNCTION STATUS` 命令只显示用户定义的函数，不包括系统函数。
+`SHOW FUNCTION STATUS` 命令只显示用户定义的函数，不包括系统函数。MatrixOne 支持 [SQL UDF](../../Data-Definition-Language/create-function-sql.md) 和 [Python UDF](../../Data-Definition-Language/create-function-python.md)。
 
 ## **语法结构**
 
@@ -26,25 +26,30 @@ SHOW FUNCTION STATUS LIKE 'my_function%';
 ## **示例**
 
 ```sql
+create or replace function py_add(a int, b int) returns int language python as 
+$$
+def add(a, b):
+  return a + b
+$$
+handler 'add';
 create function twosum (x float, y float) returns float language sql as 'select $1 + $2' ;
-create function mysumtable(x int) returns int language sql as 'select mysum(test_val, id) from tbl1 where id = $1';
 create function helloworld () returns int language sql as 'select id from tbl1 limit 1';
 
 mysql> show function status;
-+------+------------+----------+---------+---------------------+---------------------+---------------+---------+----------------------+----------------------+--------------------+
-| Db   | Name       | Type     | Definer | Modified            | Created             | Security_type | Comment | character_set_client | collation_connection | Database Collation |
-+------+------------+----------+---------+---------------------+---------------------+---------------+---------+----------------------+----------------------+--------------------+
-| aab  | twosum     | FUNCTION | root    | 2023-03-27 06:25:41 | 2023-03-27 06:25:41 | DEFINER       |         | utf8mb4              | utf8mb4_0900_ai_ci   | utf8mb4_0900_ai_ci |
-| aab  | mysumtable | FUNCTION | root    | 2023-03-27 06:25:51 | 2023-03-27 06:25:51 | DEFINER       |         | utf8mb4              | utf8mb4_0900_ai_ci   | utf8mb4_0900_ai_ci |
-| aab  | helloworld | FUNCTION | root    | 2023-03-27 06:25:58 | 2023-03-27 06:25:58 | DEFINER       |         | utf8mb4              | utf8mb4_0900_ai_ci   | utf8mb4_0900_ai_ci |
-+------+------------+----------+---------+---------------------+---------------------+---------------+---------+----------------------+----------------------+--------------------+
-3 rows in set (0.00 sec)
++------+-------------+----------+---------+---------------------+---------------------+---------------+---------+----------------------+----------------------+--------------------+
+| Db   | Name        | Type     | Definer | Modified            | Created             | Security_type | Comment | character_set_client | collation_connection | Database Collation |
++------+-------------+----------+---------+---------------------+---------------------+---------------+---------+----------------------+----------------------+--------------------+
+| db1  | py_add      | FUNCTION | root    | 2024-01-16 08:00:21 | 2024-01-16 08:00:21 | DEFINER       |         | utf8mb4              | utf8mb4_0900_ai_ci   | utf8mb4_0900_ai_ci |
+| db1  | twosum      | FUNCTION | root    | 2024-01-16 08:00:39 | 2024-01-16 08:00:39 | DEFINER       |         | utf8mb4              | utf8mb4_0900_ai_ci   | utf8mb4_0900_ai_ci |
+| db1  | helloworld  | FUNCTION | root    | 2024-01-16 08:00:53 | 2024-01-16 08:00:53 | DEFINER       |         | utf8mb4              | utf8mb4_0900_ai_ci   | utf8mb4_0900_ai_ci |
++------+-------------+----------+---------+---------------------+---------------------+---------------+---------+----------------------+----------------------+--------------------+
+3 rows in set (0.01 sec)
 
 mysql> show function status like 'two%';
 +------+--------+----------+---------+---------------------+---------------------+---------------+---------+----------------------+----------------------+--------------------+
 | Db   | Name   | Type     | Definer | Modified            | Created             | Security_type | Comment | character_set_client | collation_connection | Database Collation |
 +------+--------+----------+---------+---------------------+---------------------+---------------+---------+----------------------+----------------------+--------------------+
-| aab  | twosum | FUNCTION | root    | 2023-03-27 06:25:41 | 2023-03-27 06:25:41 | DEFINER       |         | utf8mb4              | utf8mb4_0900_ai_ci   | utf8mb4_0900_ai_ci |
+| db1  | twosum | FUNCTION | root    | 2024-01-16 08:00:39 | 2024-01-16 08:00:39 | DEFINER       |         | utf8mb4              | utf8mb4_0900_ai_ci   | utf8mb4_0900_ai_ci |
 +------+--------+----------+---------+---------------------+---------------------+---------------+---------+----------------------+----------------------+--------------------+
-1 row in set (0.01 sec)
+1 rows in set (0.01 sec)
 ```

mkdocs.yml

@@ -274,6 +274,8 @@ nav:
           - CREATE STAGE: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-stage.md
           - CREATE...FROM...PUBLICATION...: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-subscription.md
           - CREATE VIEW: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-view.md
+          - CREATE FUNCTION...LANGUAGE SQL AS: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-function-sql.md
+          - CREATE FUNCTION...LANGUAGE PYTHON AS: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-function-python.md
           - CREATE OR REPLACE VIEW: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-replace-view.md
           - CREATE SOURCE: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-source.md
           - CREATE DYNAMIC TABLE: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-dynamic-table.md
@@ -289,6 +291,7 @@ nav:
           - DROP SEQUENCE: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/drop-sequence.md
           - DROP STAGE: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/drop-stage.md
           - DROP VIEW: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/drop-view.md
+          - DROP FUNCTION: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/drop-function.md
           - TRUNCATE TABLE: MatrixOne/Reference/SQL-Reference/Data-Definition-Language/truncate-table.md
         - 数据修改语言（DML）:
           - INSERT: MatrixOne/Reference/SQL-Reference/Data-Manipulation-Language/insert.md