diff --git a/docs/MatrixOne/Overview/matrixone-feature-list.md b/docs/MatrixOne/Overview/matrixone-feature-list.md index 628417cb29..22f2c778e3 100644 --- a/docs/MatrixOne/Overview/matrixone-feature-list.md +++ b/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 | ## 流计算 diff --git a/docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-function-python.md b/docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-function-python.md new file mode 100644 index 0000000000..6ddf9b4554 --- /dev/null +++ b/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 ( +[ ] [ , ... ] ) +RETURNS LANGUAGE PYTHON AS +$$ + +[ add.vector = True ] +$$ +HANDLER = '' +``` + +## **结构说明** + +- ``：指定自定义函数的名称。 + +- ` `：用于指定自定义函数的参数，这里的参数只有名称和类型。 + +- `RETURNS `：用于声明自定义函数返回值的数据类型。 + +- ``：自定义函数的主体部分，必须包含一个 RETURN 语句，其中用于指定自定义函数的返回值。 + +- `[ add.vector = True ]`：标志 python 函数一次性接收多个元组。 + +- `HANDLIER :` 指定调用的 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) +``` \ No newline at end of file diff --git a/docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-function-sql.md b/docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-function-sql.md new file mode 100644 index 0000000000..107203f5db --- /dev/null +++ b/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 ( +[ ] [ , ... ] ) +RETURNS LANGUAGE SQL AS 'function_body' +``` + +## **结构说明** + +- ``：指定自定义函数的名称。 + +- ` `：用于指定自定义函数的参数，这里的参数只有名称和类型。 + +- `RETURNS `：用于声明自定义函数返回值的数据类型，完整的数据类型请查看[数据类型概览](../../../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) +``` \ No newline at end of file diff --git a/docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/drop-function.md b/docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/drop-function.md new file mode 100644 index 0000000000..3d5360a3c6 --- /dev/null +++ b/docs/MatrixOne/Reference/SQL-Reference/Data-Definition-Language/drop-function.md @@ -0,0 +1,50 @@ +# **DROP FUNCTION** + +## **语法说明** + +`DROP FUNCTION` 语句表示删除用户自定义函数。 + +## **语法结构** + +``` +> DROP FUNCTION ([ ]… ) +``` + +## **示例** + +**示例 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) + +``` \ No newline at end of file diff --git a/docs/MatrixOne/Reference/SQL-Reference/Other/SHOW-Statements/show-function-status.md b/docs/MatrixOne/Reference/SQL-Reference/Other/SHOW-Statements/show-function-status.md index e3d3e5440b..36d8bbeb48 100644 --- a/docs/MatrixOne/Reference/SQL-Reference/Other/SHOW-Statements/show-function-status.md +++ b/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) ``` diff --git a/mkdocs.yml b/mkdocs.yml index 0ba7fe7744..d8820f149b 100644 --- a/mkdocs.yml +++ b/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