Merge pull request #21138 from taosdata/docs/python-udf

docs: python udf docs

docs/zh/07-develop/09-udf.md

@@ -6,18 +6,20 @@ description: "支持用户编码的聚合函数和标量函数，在查询中嵌
 
 在有些应用场景中，应用逻辑需要的查询无法直接使用系统内置的函数来表示。利用 UDF(User Defined Function) 功能，TDengine 可以插入用户编写的处理代码并在查询中使用它们，就能够很方便地解决特殊应用场景中的使用需求。 UDF 通常以数据表中的一列数据做为输入，同时支持以嵌套子查询的结果作为输入。
 
-TDengine 支持通过 C/C++ 语言进行 UDF 定义。接下来结合示例讲解 UDF 的使用方法。
-
 用户可以通过 UDF 实现两类函数：标量函数和聚合函数。标量函数对每行数据输出一个值，如求绝对值 abs，正弦函数 sin，字符串拼接函数 concat 等。聚合函数对多行数据进行输出一个值，如求平均数 avg，最大值 max 等。
 
-实现 UDF 时，需要实现规定的接口函数
+TDengine 支持通过 C/Python 语言进行 UDF 定义。接下来结合示例讲解 UDF 的使用方法。
+
+# C 语言实现UDF
+
+使用 C 语言实现 UDF 时，需要实现规定的接口函数
 - 标量函数需要实现标量接口函数 scalarfn 。
 - 聚合函数需要实现聚合接口函数 aggfn_start ， aggfn ， aggfn_finish。
 - 如果需要初始化，实现 udf_init；如果需要清理工作，实现udf_destroy。
 
 接口函数的名称是 UDF 名称，或者是 UDF 名称和特定后缀（_start, _finish, _init, _destroy)的连接。列表中的scalarfn，aggfn, udf需要替换成udf函数名。
 
-## 实现标量函数
+## C UDF 实现标量函数
 标量函数实现模板如下
 ```c
 #include "taos.h"
@@ -49,7 +51,7 @@ int32_t scalarfn_destroy() {
 ```
 scalarfn 为函数名的占位符，需要替换成函数名，如bit_and。
 
-## 实现聚合函数
+## C UDF 实现聚合函数
 
 聚合函数的实现模板如下
 ```c
@@ -100,7 +102,7 @@ int32_t aggfn_destroy() {
 ```
 aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
 
-## 接口函数定义
+## C UDF 接口函数定义
 
 接口函数的名称是 udf 名称，或者是 udf 名称和特定后缀（_start, _finish, _init, _destroy)的连接。以下描述中函数名称中的 scalarfn，aggfn, udf 需要替换成udf函数名。
 
@@ -108,7 +110,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
 
 接口函数参数类型见数据结构定义。
 
-### 标量接口函数
+### C UDF 标量接口函数
 
  `int32_t scalarfn(SUdfDataBlock* inputDataBlock, SUdfColumn *resultColumn)` 
  
@@ -118,7 +120,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
   - inputDataBlock: 输入的数据块
   - resultColumn: 输出列 
 
-### 聚合接口函数
+### C UDF 聚合接口函数
 
 `int32_t aggfn_start(SUdfInterBuf *interBuf)`
 
@@ -135,7 +137,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
   - result：最终结果。
 
 
-### UDF 初始化和销毁
+### C UDF 初始化和销毁
 `int32_t udf_init()`
 
 `int32_t udf_destroy()`
@@ -143,7 +145,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
 其中 udf 是函数名的占位符。udf_init 完成初始化工作。 udf_destroy 完成清理工作。如果没有初始化工作，无需定义udf_init函数。如果没有清理工作，无需定义udf_destroy函数。
 
 
-## UDF 数据结构
+## C UDF 数据结构
 ```c
 typedef struct SUdfColumnMeta {
   int16_t type;
@@ -201,7 +203,7 @@ typedef struct SUdfInterBuf {
 
 为了更好的操作以上数据结构，提供了一些便利函数，定义在 taosudf.h。
 
-## 编译 UDF
+## 编译 C UDF
 
 用户定义函数的 C 语言源代码无法直接被 TDengine 系统使用，而是需要先编译为 动态链接库，之后才能载入 TDengine 系统。
 
@@ -213,12 +215,9 @@ gcc -g -O0 -fPIC -shared bit_and.c -o libbitand.so
 
 这样就准备好了动态链接库 libbitand.so 文件，可以供后文创建 UDF 时使用了。为了保证可靠的系统运行，编译器 GCC 推荐使用 7.5 及以上版本。
 
-## 管理和使用UDF
-编译好的UDF，还需要将其加入到系统才能被正常的SQL调用。关于如何管理和使用UDF，参见[UDF使用说明](../12-taos-sql/26-udf.md)
-
-## 示例代码
+## C UDF 示例代码
 
-### 标量函数示例 [bit_and](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/bit_and.c)
+### C UDF 标量函数示例 [bit_and](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/bit_and.c)
 
 bit_add 实现多列的按位与功能。如果只有一列，返回这一列。bit_add 忽略空值。
 
@@ -231,7 +230,7 @@ bit_add 实现多列的按位与功能。如果只有一列，返回这一列。
 
 </details>
 
-### 聚合函数示例1 返回值为数值类型 [l2norm](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/l2norm.c)
+### C UDF 聚合函数示例1 返回值为数值类型 [l2norm](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/l2norm.c)
 
 l2norm 实现了输入列的所有数据的二阶范数，即对每个数据先平方，再累加求和，最后开方。
 
@@ -244,7 +243,7 @@ l2norm 实现了输入列的所有数据的二阶范数，即对每个数据先
 
 </details>
 
-### 聚合函数示例2 返回值为字符串类型 [max_vol](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/max_vol.c)
+### C UDF 聚合函数示例2 返回值为字符串类型 [max_vol](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/max_vol.c)
 
 max_vol 实现了从多个输入的电压列中找到最大电压，返回由设备ID + 最大电压所在（行，列）+ 最大电压值 组成的组合字符串值
 
@@ -269,3 +268,119 @@ select max_vol(vol1,vol2,vol3,deviceid) from battery;
 ```
 
 </details>
+
+# Python 语言实现UDF
+使用 Python 语言实现 UDF 时，需要实现规定的接口函数
+- 标量函数需要实现标量接口函数 process 。
+- 聚合函数需要实现聚合接口函数 start ，reduce ，finish。
+- 如果需要初始化，实现 init；如果需要清理工作，实现 destroy。
+
+## Python UDF 实现标量函数
+
+标量函数实现模版如下
+```Python
+def init():
+    # initialization
+def destroy():
+    # destroy
+def process(input: datablock) -> tuple[output_type]:
+    # process input datablock, 
+    # datablock.data(row, col) is to access the python object in location(row,col)
+    # return tuple object consisted of object of type outputtype   
+```
+
+## Python UDF 实现聚合函数
+
+聚合函数实现模版如下
+```Python
+def init():
+    #initialization
+def destroy():
+    #destroy
+def start() -> bytes:
+    #return serialize(init_state)
+def reduce(inputs: datablock, buf: bytes) -> bytes
+    # deserialize buf to state
+    # reduce the inputs and state into new_state. 
+    # use inputs.data(i,j) to access python ojbect of location(i,j)
+    # serialize new_state into new_state_bytes
+    return new_state_bytes   
+def finish(buf: bytes) -> output_type:
+    #return obj of type outputtype   
+```
+
+## Python UDF 接口函数定义
+
+### Python UDF 标量接口函数
+```Python
+def process(input: datablock) -> tuple[output_type]:
+```
+- input:datablock 类似二维矩阵，通过成员方法 data(row,col)返回位于 row 行，col 列的 python 对象
+- 返回值是一个 Python 对象元组，每个元素类型为输出类型。
+
+### Python UDF 聚合接口函数
+```Python
+def start() -> bytes:
+def reduce(inputs: datablock, buf: bytes) -> bytes
+def finish(buf: bytes) -> output_type:
+```
+
+首先调用 start 生成最初结果 buffer，然后输入数据会被分为多个行数据块，对每个数据块 inputs 和当前中间结果 buf 调用 reduce，得到新的中间结果，最后再调用 finish 从中间结果 buf 产生最终输出，最终输出只能含 0 或 1 条数据。
+
+
+### Python UDF 初始化和销毁
+```Python
+def init()
+def destroy()
+```
+
+其中 init 完成初始化工作。 destroy 完成清理工作。如果没有初始化工作，无需定义 init 函数。如果没有清理工作，无需定义 destroy 函数。
+
+## Python数据类型和TDengine数据类型映射
+|  **TDengine SQL数据类型**   | **Python数据类型** |
+| :-----------------------: | ------------ |
+|TINYINT / SMALLINT / INT  / BIGINT     | int   |
+|TINYINT UNSIGNED / SMALLINT UNSIGNED / INT UNSIGNED / BIGINT UNSIGNED | int |
+|FLOAT / DOUBLE | float |
+|BOOL | bool |
+|BINARY / VARCHAR / NCHAR | bytes|
+|TIMESTAMP | int |
+|JSON and other types | 不支持 |
+
+## Python UDF 环境的安装
+1. 安装 taospyudf 包。此包执行Python UDF程序。
+```bash
+pip install taospyudf
+lddconfig
+```
+2. 如果 Python UDF 程序执行时，通过 PYTHONPATH 引用其它的包，可以设置 taos.cfg 的 UdfdLdLibPath 变量为PYTHONPATH的内容
+ 
+## Python UDF 示例代码
+### Python UDF 标量函数示例 [pybitand](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/pybitand.py)
+
+pybitand 实现多列的按位与功能。如果只有一列，返回这一列。pybitand 忽略空值。
+
+<details>
+<summary>pybitand.py</summary>
+
+```Python
+{{#include tests/script/sh/pybitand.py}}
+```
+
+</details>
+
+### Python UDF 聚合函数示例 [pyl2norm](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/pyl2norm.py)
+
+pyl2norm 实现了输入列的所有数据的二阶范数，即对每个数据先平方，再累加求和，最后开方。
+
+<details>
+<summary>pyl2norm.py</summary>
+
+```c
+{{#include tests/script/sh/pyl2norm.py}}
+```
+
+</details>
+
+# 管理和使用UDF
+编译好的UDF，还需要将其加入到系统才能被正常的SQL调用。关于如何管理和使用UDF，参见[UDF使用说明](../12-taos-sql/26-udf.md)
\ No newline at end of file

docs/zh/12-taos-sql/22-meta.md

@@ -120,6 +120,10 @@ TDengine 内置了一个名为 `INFORMATION_SCHEMA` 的数据库，提供对数
 | 5   | create_time | TIMESTAMP    | 创建时间       |
 | 6   |  code_len   | INT          | 代码长度       |
 | 7   |   bufsize   | INT          | buffer 大小    |
+| 8   | func_language | BINARY(31) | 自定义函数编程语言 |
+| 9   | func_body     | BINARY(16384) | 函数体定义 |
+| 10  | func_version  | INT           | 函数版本号。初始版本为0，每次替换更新，版本号加1。|
+
 
 ## INS_INDEXES
 

docs/zh/12-taos-sql/26-udf.md

@@ -11,29 +11,38 @@ description: 使用 UDF 的详细指南
 
 在创建 UDF 时，需要区分标量函数和聚合函数。如果创建时声明了错误的函数类别，则可能导致通过 SQL 指令调用函数时出错。此外，用户需要保证输入数据类型与 UDF 程序匹配，UDF 输出数据类型与 OUTPUTTYPE 匹配。
 
+使用 CREATE OR REPLACE FUNCTION，如果函数已经存在，会修改已有的函数属性。
+
 - 创建标量函数
 ```sql
-CREATE FUNCTION function_name AS library_path OUTPUTTYPE output_type;
+CREATE [OR REPLACE] FUNCTION function_name AS library_path OUTPUTTYPE output_type [LANGUAGE 'C|Python'];
 ```
 
   - function_name：标量函数未来在 SQL 中被调用时的函数名，必须与函数实现中 udf 的实际名称一致；
-  - library_path：包含 UDF 函数实现的动态链接库的库文件绝对路径（指的是库文件在当前客户端所在主机上的保存路径，通常是指向一个 .so 文件），这个路径需要用英文单引号或英文双引号括起来；
+  - LANGUAGE 'C|Python'：函数编程语言，目前支持C语言和Python语言。  
+  - library_path：如果编程语言是C，路径是包含 UDF 函数实现的动态链接库的库文件绝对路径（指的是库文件在当前客户端所在主机上的保存路径，通常是指向一个 .so 文件）。如果编程语言是Python，路径是包含 UDF 函数实现的Python文件路径。这个路径需要用英文单引号或英文双引号括起来；
   - output_type：此函数计算结果的数据类型名称；
 
-  例如，如下语句可以把 libbitand.so 创建为系统中可用的 UDF：
+例如，如下语句可以把 libbitand.so 创建为系统中可用的 UDF：
 
   ```sql
   CREATE FUNCTION bit_and AS "/home/taos/udf_example/libbitand.so" OUTPUTTYPE INT;
   ```
 
+例如，使用以下语句可以修改已经定义的 bit_and 函数，输出类型是 BIGINT，使用Python语言实现。
+
+  ```sql
+  CREATE OR REPLACE FUNCTION bit_and AS "/home/taos/udf_example/bit_and.py" OUTPUTTYPE BIGINT LANGUAGE 'Python';
+  ```
 - 创建聚合函数：
 ```sql
-CREATE AGGREGATE FUNCTION function_name AS library_path OUTPUTTYPE output_type [ BUFSIZE buffer_size ];
+CREATE [OR REPLACE] AGGREGATE FUNCTION function_name AS library_path OUTPUTTYPE output_type [ BUFSIZE buffer_size ] [LANGUAGE 'C|Python'];
 ```
 
   - function_name：聚合函数未来在 SQL 中被调用时的函数名，必须与函数实现中 udfNormalFunc 的实际名称一致；
-  - library_path：包含 UDF 函数实现的动态链接库的库文件绝对路径（指的是库文件在当前客户端所在主机上的保存路径，通常是指向一个 .so 文件），这个路径需要用英文单引号或英文双引号括起来；
-  - output_type：此函数计算结果的数据类型，与上文中 udfNormalFunc 的 itype 参数不同，这里不是使用数字表示法，而是直接写类型名称即可；
+  - LANGUAGE 'C|Python'：函数编程语言，目前支持C语言和Python语言。  
+  - library_path：如果编程语言是C，路径是包含 UDF 函数实现的动态链接库的库文件绝对路径（指的是库文件在当前客户端所在主机上的保存路径，通常是指向一个 .so 文件）。如果编程语言是Python，路径是包含 UDF 函数实现的Python文件路径。这个路径需要用英文单引号或英文双引号括起来；；
+  - output_type：此函数计算结果的数据类型名称；
   - buffer_size：中间计算结果的缓冲区大小，单位是字节。如果不使用可以不设置。
 
   例如，如下语句可以把 libl2norm.so 创建为系统中可用的 UDF：
@@ -41,6 +50,11 @@ CREATE AGGREGATE FUNCTION function_name AS library_path OUTPUTTYPE output_type [
   ```sql
   CREATE AGGREGATE FUNCTION l2norm AS "/home/taos/udf_example/libl2norm.so" OUTPUTTYPE DOUBLE bufsize 8;
   ```
+  例如，使用以下语句可以修改已经定义的 l2norm 函数的缓冲区大小为64。
+  ```sql
+  CREATE AGGREGATE FUNCTION l2norm AS "/home/taos/udf_example/libl2norm.so" OUTPUTTYPE DOUBLE bufsize 64;
+  ```  
+
 关于如何开发自定义函数，请参考 [UDF使用说明](/develop/udf)。
 
 ## 管理 UDF