Skip to content

T
TDengine

taosdata / TDengine
1 年多 前同步成功

通知 1185
Star 22016
Fork 4786
T
TDengine
提交 879bbe98 编写于 作者: G gccgdb1234
浏览文件
操作

doc: revise doc structure of UDF

上级 615be563
隐藏空白更改
内联 并排
Showing with 53 addition and 53 deletion
docs/en/07-develop/09-udf.md
浏览文件 @ 879bbe98
...@@ -10,7 +10,7 @@ User-defined functions can be scalar functions or aggregate functions. Scalar fu ...@@ -10,7 +10,7 @@ User-defined functions can be scalar functions or aggregate functions. Scalar fu
TDengine supports user-defined functions written in C or Python. This document describes the usage of user-defined functions. TDengine supports user-defined functions written in C or Python. This document describes the usage of user-defined functions.
# Implement a UDF in C ## Implement a UDF in C
When you create a user-defined function, you must implement standard interface functions: When you create a user-defined function, you must implement standard interface functions:
- For scalar functions, implement the `scalarfn` interface function. - For scalar functions, implement the `scalarfn` interface function.
...@@ -19,7 +19,7 @@ When you create a user-defined function, you must implement standard interface f ...@@ -19,7 +19,7 @@ When you create a user-defined function, you must implement standard interface f
There are strict naming conventions for these interface functions. The names of the start, finish, init, and destroy interfaces must be <udf-name\>_start, <udf-name\>_finish, <udf-name\>_init, and <udf-name\>_destroy, respectively. Replace `scalarfn`, `aggfn`, and `udf` with the name of your user-defined function. There are strict naming conventions for these interface functions. The names of the start, finish, init, and destroy interfaces must be <udf-name\>_start, <udf-name\>_finish, <udf-name\>_init, and <udf-name\>_destroy, respectively. Replace `scalarfn`, `aggfn`, and `udf` with the name of your user-defined function.
## Implementing a Scalar Function in C ### Implementing a Scalar Function in C
The implementation of a scalar function is described as follows: The implementation of a scalar function is described as follows:
```c ```c
#include "taos.h" #include "taos.h"
...@@ -102,7 +102,7 @@ int32_t aggfn_destroy() { ...@@ -102,7 +102,7 @@ int32_t aggfn_destroy() {
``` ```
Replace `aggfn` with the name of your function. Replace `aggfn` with the name of your function.
## C UDF Interface Functions ### UDF Interface Definition in C
There are strict naming conventions for interface functions. The names of the start, finish, init, and destroy interfaces must be <udf-name\>_start, <udf-name\>_finish, <udf-name\>_init, and <udf-name\>_destroy, respectively. Replace `scalarfn`, `aggfn`, and `udf` with the name of your user-defined function. There are strict naming conventions for interface functions. The names of the start, finish, init, and destroy interfaces must be <udf-name\>_start, <udf-name\>_finish, <udf-name\>_init, and <udf-name\>_destroy, respectively. Replace `scalarfn`, `aggfn`, and `udf` with the name of your user-defined function.
...@@ -110,8 +110,7 @@ Interface functions return a value that indicates whether the operation was succ ...@@ -110,8 +110,7 @@ Interface functions return a value that indicates whether the operation was succ
For information about the parameters for interface functions, see Data Model For information about the parameters for interface functions, see Data Model
### Interfaces for C UDF Scalar Functions #### Scalar Interface
`int32_t scalarfn(SUdfDataBlock* inputDataBlock, SUdfColumn *resultColumn)` `int32_t scalarfn(SUdfDataBlock* inputDataBlock, SUdfColumn *resultColumn)`
Replace `scalarfn` with the name of your function. This function performs scalar calculations on data blocks. You can configure a value through the parameters in the `resultColumn` structure. Replace `scalarfn` with the name of your function. This function performs scalar calculations on data blocks. You can configure a value through the parameters in the `resultColumn` structure.
...@@ -120,7 +119,7 @@ The parameters in the function are defined as follows: ...@@ -120,7 +119,7 @@ The parameters in the function are defined as follows:
- inputDataBlock: The data block to input. - inputDataBlock: The data block to input.
- resultColumn: The column to output. The column to output. - resultColumn: The column to output. The column to output.
### Interfaces for C UDF Aggregate Functions #### Aggregate Interface
`int32_t aggfn_start(SUdfInterBuf *interBuf)` `int32_t aggfn_start(SUdfInterBuf *interBuf)`
...@@ -137,7 +136,7 @@ The parameters in the function are defined as follows: ...@@ -137,7 +136,7 @@ The parameters in the function are defined as follows:
- result: The final result. - result: The final result.
### C UDF Initializing and Terminating User-Defined Functions #### Initialization and Cleanup Interface
`int32_t udf_init()` `int32_t udf_init()`
`int32_t udf_destroy()` `int32_t udf_destroy()`
...@@ -145,7 +144,7 @@ The parameters in the function are defined as follows: ...@@ -145,7 +144,7 @@ The parameters in the function are defined as follows:
Replace `udf` with the name of your function. udf_init initializes the function. udf_destroy terminates the function. If it is not necessary to initialize your function, udf_init is not required. If it is not necessary to terminate your function, udf_destroy is not required. Replace `udf` with the name of your function. udf_init initializes the function. udf_destroy terminates the function. If it is not necessary to initialize your function, udf_init is not required. If it is not necessary to terminate your function, udf_destroy is not required.
## Data Structure of C User-Defined Functions ### Data Structures for UDF in C
```c ```c
typedef struct SUdfColumnMeta { typedef struct SUdfColumnMeta {
int16_t type; int16_t type;
...@@ -203,7 +202,7 @@ The data structure is described as follows: ...@@ -203,7 +202,7 @@ The data structure is described as follows:
Additional functions are defined in `taosudf.h` to make it easier to work with these structures. Additional functions are defined in `taosudf.h` to make it easier to work with these structures.
## Compile C UDF ### Compiling C UDF
To use your user-defined function in TDengine, first, compile it to a shared library. To use your user-defined function in TDengine, first, compile it to a shared library.
...@@ -215,9 +214,9 @@ gcc -g -O0 -fPIC -shared bit_and.c -o libbitand.so ...@@ -215,9 +214,9 @@ gcc -g -O0 -fPIC -shared bit_and.c -o libbitand.so
The generated DLL file `libbitand.so` can now be used to implement your function. Note: GCC 7.5 or later is required. The generated DLL file `libbitand.so` can now be used to implement your function. Note: GCC 7.5 or later is required.
## C UDF Sample Code ### UDF Sample Code in C
### C UDF Sample scalar function: [bit_and](https://github.com/taosdata/TDengine/blob/3.0/tests/script/sh/bit_and.c) #### Scalar function: [bit_and](https://github.com/taosdata/TDengine/blob/3.0/tests/script/sh/bit_and.c)
The bit_and function implements bitwise addition for multiple columns. If there is only one column, the column is returned. The bit_and function ignores null values. The bit_and function implements bitwise addition for multiple columns. If there is only one column, the column is returned. The bit_and function ignores null values.
...@@ -230,7 +229,7 @@ The bit_and function implements bitwise addition for multiple columns. If there ...@@ -230,7 +229,7 @@ The bit_and function implements bitwise addition for multiple columns. If there
</details> </details>
### C UDF Sample aggregate function 1: [l2norm](https://github.com/taosdata/TDengine/blob/3.0/tests/script/sh/l2norm.c) #### Aggregate function 1: [l2norm](https://github.com/taosdata/TDengine/blob/3.0/tests/script/sh/l2norm.c)
The l2norm function finds the second-order norm for all data in the input column. This squares the values, takes a cumulative sum, and finds the square root. The l2norm function finds the second-order norm for all data in the input column. This squares the values, takes a cumulative sum, and finds the square root.
...@@ -243,7 +242,7 @@ The l2norm function finds the second-order norm for all data in the input column ...@@ -243,7 +242,7 @@ The l2norm function finds the second-order norm for all data in the input column
</details> </details>
### C UDF Sample aggregate function 2: [max_vol](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/max_vol.c) #### Aggregate function 2: [max_vol](https://github.com/taosdata/TDengine/blob/3.0/tests/script/sh/max_vol.c)
The max_vol function returns a string concatenating the deviceId column, the row number and column number of the maximum voltage and the maximum voltage given several voltage columns as input. The max_vol function returns a string concatenating the deviceId column, the row number and column number of the maximum voltage and the maximum voltage given several voltage columns as input.
...@@ -269,14 +268,14 @@ select max_vol(vol1,vol2,vol3,deviceid) from battery; ...@@ -269,14 +268,14 @@ select max_vol(vol1,vol2,vol3,deviceid) from battery;
</details> </details>
#Implement a UDF in Python ## Implement a UDF in Python
Implement the specified interface functions when implementing a UDF in Python. Implement the specified interface functions when implementing a UDF in Python.
- implement `process` function for the scalar UDF。 - implement `process` function for the scalar UDF。
- implement `start`, `reduce`, `finish` for the aggregate UDF。 - implement `start`, `reduce`, `finish` for the aggregate UDF。
- implement `init` for initialization and `destroy` for termination。 - implement `init` for initialization and `destroy` for termination。
## Implement a Scalar UDF in Python ### Implement a Scalar UDF in Python
The implementation of a scalar UDF is described as follows: The implementation of a scalar UDF is described as follows:
...@@ -291,7 +290,7 @@ def process(input: datablock) -> tuple[output_type]: ...@@ -291,7 +290,7 @@ def process(input: datablock) -> tuple[output_type]:
# return tuple object consisted of object of type outputtype # return tuple object consisted of object of type outputtype
``` ```
## Implement an Aggregate UDF in Python ### Implement an Aggregate UDF in Python
The implementation of an aggregate function is described as follows: The implementation of an aggregate function is described as follows:
...@@ -312,16 +311,16 @@ def finish(buf: bytes) -> output_type: ...@@ -312,16 +311,16 @@ def finish(buf: bytes) -> output_type:
#return obj of type outputtype #return obj of type outputtype
``` ```
## Python UDF interface functions ### Python UDF Interface Definition
### Python UDF scalar interface functions #### Scalar interface
```Python ```Python
def process(input: datablock) -> tuple[output_type]: def process(input: datablock) -> tuple[output_type]:
``` ```
- `input` is a data block two-dimension matrix-like object, of which method `data(row, col)` returns the Python object located at location (`row`, `col`) - `input` is a data block two-dimension matrix-like object, of which method `data(row, col)` returns the Python object located at location (`row`, `col`)
- return a Python tuple object, of which each item is a Python object of type `output_type` - return a Python tuple object, of which each item is a Python object of type `output_type`
### Python UDF aggregate interface functions #### Aggregate Interface
```Python ```Python
def start() -> bytes: def start() -> bytes:
def reduce(input: datablock, buf: bytes) -> bytes def reduce(input: datablock, buf: bytes) -> bytes
...@@ -333,14 +332,14 @@ def finish(buf: bytes) -> output_type: ...@@ -333,14 +332,14 @@ def finish(buf: bytes) -> output_type:
- finally, the `finish` function is called on the intermediate result `buf` and outputs 0 or 1 data of type `output_type` - finally, the `finish` function is called on the intermediate result `buf` and outputs 0 or 1 data of type `output_type`
### Python UDF Initialization and Termination #### Initialization and Cleanup Interface
```Python ```Python
def init() def init()
def destroy() def destroy()
``` ```
Implement `init` for initialization and `destroy` for termination. Implement `init` for initialization and `destroy` for termination.
## TDengine SQL data type and Python UDF Data Type Mapping Table ### Data Mapping between TDengine SQL and Python UDF
The following table describes the mapping between TDengine SQL data type and Python UDF Data Type. The `NULL` value of all TDengine SQL types is mapped to the `None` value in Python. The following table describes the mapping between TDengine SQL data type and Python UDF Data Type. The `NULL` value of all TDengine SQL types is mapped to the `None` value in Python.
...@@ -354,7 +353,7 @@ The following table describes the mapping between TDengine SQL data type and Pyt ...@@ -354,7 +353,7 @@ The following table describes the mapping between TDengine SQL data type and Pyt
|TIMESTAMP | int | |TIMESTAMP | int |
|JSON and other types | Not Supported | |JSON and other types | Not Supported |
## Python UDF Installation ### Installing Python UDF
1. Install Python package `taospyudf` that executes Python UDF 1. Install Python package `taospyudf` that executes Python UDF
```bash ```bash
sudo pip install taospyudf sudo pip install taospyudf
...@@ -362,8 +361,8 @@ ldconfig ...@@ -362,8 +361,8 @@ ldconfig
``` ```
2. If PYTHONPATH is needed to find Python packages when the Python UDF executes, include the PYTHONPATH contents into the udfdLdLibPath variable of the taos.cfg configuration file 2. If PYTHONPATH is needed to find Python packages when the Python UDF executes, include the PYTHONPATH contents into the udfdLdLibPath variable of the taos.cfg configuration file
## Python UDF Sample Code ### Python UDF Sample Code
### Python UDF Scalar Function Sample Code [pybitand](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/pybitand.py) #### Scalar Function [pybitand](https://github.com/taosdata/TDengine/blob/3.0/tests/script/sh/pybitand.py)
The `pybitand` function implements bitwise addition for multiple columns. If there is only one column, the column is returned. The `pybitand` function ignores null values. The `pybitand` function implements bitwise addition for multiple columns. If there is only one column, the column is returned. The `pybitand` function ignores null values.
...@@ -376,7 +375,7 @@ The `pybitand` function implements bitwise addition for multiple columns. If the ...@@ -376,7 +375,7 @@ The `pybitand` function implements bitwise addition for multiple columns. If the
</details> </details>
### Python UDF Aggregate Function Sample Code [pyl2norm](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/pyl2norm.py) #### Aggregate Function [pyl2norm](https://github.com/taosdata/TDengine/blob/3.0/tests/script/sh/pyl2norm.py)
The `pyl2norm` function finds the second-order norm for all data in the input column. This squares the values, takes a cumulative sum, and finds the square root. The `pyl2norm` function finds the second-order norm for all data in the input column. This squares the values, takes a cumulative sum, and finds the square root.
<details> <details>
...@@ -389,4 +388,4 @@ The `pyl2norm` function finds the second-order norm for all data in the input co ...@@ -389,4 +388,4 @@ The `pyl2norm` function finds the second-order norm for all data in the input co
</details> </details>
## Manage and Use User-Defined Functions ## Manage and Use User-Defined Functions
You can add UDF to TDengine before using it in SQL queries. For more information, see [User-Defined Functions](../12-taos-sql/26-udf.md). You need to add UDF to TDengine before using it in SQL queries. For more information about how to manage UDF and how to invoke UDF, please see [Manage and Use UDF](../12-taos-sql/26-udf.md).
docs/zh/07-develop/09-udf.md
浏览文件 @ 879bbe98
...@@ -10,7 +10,7 @@ description: "支持用户编码的聚合函数和标量函数，在查询中嵌 ...@@ -10,7 +10,7 @@ description: "支持用户编码的聚合函数和标量函数，在查询中嵌
TDengine 支持通过 C/Python 语言进行 UDF 定义。接下来结合示例讲解 UDF 的使用方法。 TDengine 支持通过 C/Python 语言进行 UDF 定义。接下来结合示例讲解 UDF 的使用方法。
# C 语言实现 UDF ## 用 C 语言实现 UDF
使用 C 语言实现 UDF 时，需要实现规定的接口函数 使用 C 语言实现 UDF 时，需要实现规定的接口函数
- 标量函数需要实现标量接口函数 scalarfn 。 - 标量函数需要实现标量接口函数 scalarfn 。
...@@ -19,7 +19,7 @@ TDengine 支持通过 C/Python 语言进行 UDF 定义。接下来结合示例 ...@@ -19,7 +19,7 @@ TDengine 支持通过 C/Python 语言进行 UDF 定义。接下来结合示例
接口函数的名称是 UDF 名称，或者是 UDF 名称和特定后缀（_start, _finish, _init, _destroy)的连接。列表中的scalarfn，aggfn, udf需要替换成udf函数名。 接口函数的名称是 UDF 名称，或者是 UDF 名称和特定后缀（_start, _finish, _init, _destroy)的连接。列表中的scalarfn，aggfn, udf需要替换成udf函数名。
## C UDF 实现标量函数 ### 用 C 语言实现标量函数
标量函数实现模板如下 标量函数实现模板如下
```c ```c
#include "taos.h" #include "taos.h"
...@@ -51,7 +51,7 @@ int32_t scalarfn_destroy() { ...@@ -51,7 +51,7 @@ int32_t scalarfn_destroy() {
``` ```
scalarfn 为函数名的占位符，需要替换成函数名，如bit_and。 scalarfn 为函数名的占位符，需要替换成函数名，如bit_and。
## C UDF 实现聚合函数 ### 用 C 语言实现聚合函数
聚合函数的实现模板如下 聚合函数的实现模板如下
```c ```c
...@@ -102,7 +102,7 @@ int32_t aggfn_destroy() { ...@@ -102,7 +102,7 @@ int32_t aggfn_destroy() {
``` ```
aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。 aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
## C UDF 接口函数定义 ### C 语言 UDF 接口函数定义
接口函数的名称是 udf 名称，或者是 udf 名称和特定后缀（_start, _finish, _init, _destroy)的连接。以下描述中函数名称中的 scalarfn，aggfn, udf 需要替换成udf函数名。 接口函数的名称是 udf 名称，或者是 udf 名称和特定后缀（_start, _finish, _init, _destroy)的连接。以下描述中函数名称中的 scalarfn，aggfn, udf 需要替换成udf函数名。
...@@ -110,7 +110,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。 ...@@ -110,7 +110,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
接口函数参数类型见数据结构定义。 接口函数参数类型见数据结构定义。
### C UDF 标量接口函数 #### 标量函数接口
`int32_t scalarfn(SUdfDataBlock* inputDataBlock, SUdfColumn *resultColumn)` `int32_t scalarfn(SUdfDataBlock* inputDataBlock, SUdfColumn *resultColumn)`
...@@ -120,7 +120,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。 ...@@ -120,7 +120,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
- inputDataBlock: 输入的数据块 - inputDataBlock: 输入的数据块
- resultColumn: 输出列 - resultColumn: 输出列
### C UDF 聚合接口函数 #### 聚合函数接口
`int32_t aggfn_start(SUdfInterBuf *interBuf)` `int32_t aggfn_start(SUdfInterBuf *interBuf)`
...@@ -137,7 +137,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。 ...@@ -137,7 +137,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
- result：最终结果。 - result：最终结果。
### C UDF 初始化和销毁 #### 初始化和销毁接口
`int32_t udf_init()` `int32_t udf_init()`
`int32_t udf_destroy()` `int32_t udf_destroy()`
...@@ -145,7 +145,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。 ...@@ -145,7 +145,7 @@ aggfn为函数名的占位符，需要修改为自己的函数名，如l2norm。
其中 udf 是函数名的占位符。udf_init 完成初始化工作。 udf_destroy 完成清理工作。如果没有初始化工作，无需定义udf_init函数。如果没有清理工作，无需定义udf_destroy函数。 其中 udf 是函数名的占位符。udf_init 完成初始化工作。 udf_destroy 完成清理工作。如果没有初始化工作，无需定义udf_init函数。如果没有清理工作，无需定义udf_destroy函数。
## C UDF 数据结构 ### C 语言 UDF 数据结构
```c ```c
typedef struct SUdfColumnMeta { typedef struct SUdfColumnMeta {
int16_t type; int16_t type;
...@@ -203,7 +203,7 @@ typedef struct SUdfInterBuf { ...@@ -203,7 +203,7 @@ typedef struct SUdfInterBuf {
为了更好的操作以上数据结构，提供了一些便利函数，定义在 taosudf.h。 为了更好的操作以上数据结构，提供了一些便利函数，定义在 taosudf.h。
## 编译 C UDF ### 编译 C UDF
用户定义函数的 C 语言源代码无法直接被 TDengine 系统使用，而是需要先编译为 动态链接库，之后才能载入 TDengine 系统。 用户定义函数的 C 语言源代码无法直接被 TDengine 系统使用，而是需要先编译为 动态链接库，之后才能载入 TDengine 系统。
...@@ -215,9 +215,9 @@ gcc -g -O0 -fPIC -shared bit_and.c -o libbitand.so ...@@ -215,9 +215,9 @@ gcc -g -O0 -fPIC -shared bit_and.c -o libbitand.so
这样就准备好了动态链接库 libbitand.so 文件，可以供后文创建 UDF 时使用了。为了保证可靠的系统运行，编译器 GCC 推荐使用 7.5 及以上版本。 这样就准备好了动态链接库 libbitand.so 文件，可以供后文创建 UDF 时使用了。为了保证可靠的系统运行，编译器 GCC 推荐使用 7.5 及以上版本。
## C UDF 示例代码 ### C UDF 示例代码
### C UDF 标量函数示例 [bit_and](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/bit_and.c) #### 标量函数示例 [bit_and](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/bit_and.c)
bit_add 实现多列的按位与功能。如果只有一列，返回这一列。bit_add 忽略空值。 bit_add 实现多列的按位与功能。如果只有一列，返回这一列。bit_add 忽略空值。
...@@ -230,7 +230,7 @@ bit_add 实现多列的按位与功能。如果只有一列，返回这一列。 ...@@ -230,7 +230,7 @@ bit_add 实现多列的按位与功能。如果只有一列，返回这一列。
</details> </details>
### C UDF 聚合函数示例1 返回值为数值类型 [l2norm](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/l2norm.c) #### 聚合函数示例1 返回值为数值类型 [l2norm](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/l2norm.c)
l2norm 实现了输入列的所有数据的二阶范数，即对每个数据先平方，再累加求和，最后开方。 l2norm 实现了输入列的所有数据的二阶范数，即对每个数据先平方，再累加求和，最后开方。
...@@ -243,7 +243,7 @@ l2norm 实现了输入列的所有数据的二阶范数，即对每个数据先 ...@@ -243,7 +243,7 @@ l2norm 实现了输入列的所有数据的二阶范数，即对每个数据先
</details> </details>
### C UDF 聚合函数示例2 返回值为字符串类型 [max_vol](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/max_vol.c) #### 聚合函数示例2 返回值为字符串类型 [max_vol](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/max_vol.c)
max_vol 实现了从多个输入的电压列中找到最大电压，返回由设备ID + 最大电压所在（行，列）+ 最大电压值 组成的组合字符串值 max_vol 实现了从多个输入的电压列中找到最大电压，返回由设备ID + 最大电压所在（行，列）+ 最大电压值 组成的组合字符串值
...@@ -269,13 +269,14 @@ select max_vol(vol1,vol2,vol3,deviceid) from battery; ...@@ -269,13 +269,14 @@ select max_vol(vol1,vol2,vol3,deviceid) from battery;
</details> </details>
# Python 语言实现 UDF ## 用 Python 语言实现 UDF
使用 Python 语言实现 UDF 时，需要实现规定的接口函数 使用 Python 语言实现 UDF 时，需要实现规定的接口函数
- 标量函数需要实现标量接口函数 process 。 - 标量函数需要实现标量接口函数 process 。
- 聚合函数需要实现聚合接口函数 start ，reduce ，finish。 - 聚合函数需要实现聚合接口函数 start ，reduce ，finish。
- 如果需要初始化，实现 init；如果需要清理工作，实现 destroy。 - 如果需要初始化，实现 init；如果需要清理工作，实现 destroy。
## Python UDF 实现标量函数 ### 用 Python 实现标量函数
标量函数实现模版如下 标量函数实现模版如下
```Python ```Python
...@@ -289,7 +290,7 @@ def process(input: datablock) -> tuple[output_type]: ...@@ -289,7 +290,7 @@ def process(input: datablock) -> tuple[output_type]:
# return tuple object consisted of object of type outputtype # return tuple object consisted of object of type outputtype
``` ```
## Python UDF 实现聚合函数 ### 用 Python 实现聚合函数
聚合函数实现模版如下 聚合函数实现模版如下
```Python ```Python
...@@ -309,16 +310,16 @@ def finish(buf: bytes) -> output_type: ...@@ -309,16 +310,16 @@ def finish(buf: bytes) -> output_type:
#return obj of type outputtype #return obj of type outputtype
``` ```
## Python UDF 接口函数定义 ### Python UDF 接口函数定义
### Python UDF 标量接口函数 #### 标量函数接口
```Python ```Python
def process(input: datablock) -> tuple[output_type]: def process(input: datablock) -> tuple[output_type]:
``` ```
- input:datablock 类似二维矩阵，通过成员方法 data(row,col)返回位于 row 行，col 列的 python 对象 - input:datablock 类似二维矩阵，通过成员方法 data(row,col)返回位于 row 行，col 列的 python 对象
- 返回值是一个 Python 对象元组，每个元素类型为输出类型。 - 返回值是一个 Python 对象元组，每个元素类型为输出类型。
### Python UDF 聚合接口函数 #### 聚合函数接口
```Python ```Python
def start() -> bytes: def start() -> bytes:
def reduce(inputs: datablock, buf: bytes) -> bytes def reduce(inputs: datablock, buf: bytes) -> bytes
...@@ -328,7 +329,7 @@ def finish(buf: bytes) -> output_type: ...@@ -328,7 +329,7 @@ def finish(buf: bytes) -> output_type:
首先调用 start 生成最初结果 buffer，然后输入数据会被分为多个行数据块，对每个数据块 inputs 和当前中间结果 buf 调用 reduce，得到新的中间结果，最后再调用 finish 从中间结果 buf 产生最终输出，最终输出只能含 0 或 1 条数据。 首先调用 start 生成最初结果 buffer，然后输入数据会被分为多个行数据块，对每个数据块 inputs 和当前中间结果 buf 调用 reduce，得到新的中间结果，最后再调用 finish 从中间结果 buf 产生最终输出，最终输出只能含 0 或 1 条数据。
### Python UDF 初始化和销毁 #### 初始化和销毁接口
```Python ```Python
def init() def init()
def destroy() def destroy()
...@@ -336,7 +337,7 @@ def destroy() ...@@ -336,7 +337,7 @@ def destroy()
其中 init 完成初始化工作。 destroy 完成清理工作。如果没有初始化工作，无需定义 init 函数。如果没有清理工作，无需定义 destroy 函数。 其中 init 完成初始化工作。 destroy 完成清理工作。如果没有初始化工作，无需定义 init 函数。如果没有清理工作，无需定义 destroy 函数。
## Python 数据类型和 TDengine 数据类型映射 ### Python 和 TDengine之间的数据类型映射
下表描述了TDengine SQL数据类型和Python数据类型的映射。任何类型的NULL值都映射成Python的None值。 下表描述了TDengine SQL数据类型和Python数据类型的映射。任何类型的NULL值都映射成Python的None值。
...@@ -350,7 +351,7 @@ def destroy() ...@@ -350,7 +351,7 @@ def destroy()
|TIMESTAMP | int | |TIMESTAMP | int |
|JSON and other types | 不支持 | |JSON and other types | 不支持 |
## Python UDF 环境的安装 ### Python UDF 环境的安装
1. 安装 taospyudf 包。此包执行Python UDF程序。 1. 安装 taospyudf 包。此包执行Python UDF程序。
```bash ```bash
sudo pip install taospyudf sudo pip install taospyudf
...@@ -358,8 +359,8 @@ ldconfig ...@@ -358,8 +359,8 @@ ldconfig
``` ```
2. 如果 Python UDF 程序执行时，通过 PYTHONPATH 引用其它的包，可以设置 taos.cfg 的 UdfdLdLibPath 变量为PYTHONPATH的内容 2. 如果 Python UDF 程序执行时，通过 PYTHONPATH 引用其它的包，可以设置 taos.cfg 的 UdfdLdLibPath 变量为PYTHONPATH的内容
## Python UDF 示例代码 ### Python UDF 示例代码
### Python UDF 标量函数示例 [pybitand](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/pybitand.py) #### 标量函数示例 [pybitand](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/pybitand.py)
pybitand 实现多列的按位与功能。如果只有一列，返回这一列。pybitand 忽略空值。 pybitand 实现多列的按位与功能。如果只有一列，返回这一列。pybitand 忽略空值。
...@@ -372,7 +373,7 @@ pybitand 实现多列的按位与功能。如果只有一列，返回这一列 ...@@ -372,7 +373,7 @@ pybitand 实现多列的按位与功能。如果只有一列，返回这一列
</details> </details>
### Python UDF 聚合函数示例 [pyl2norm](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/pyl2norm.py) #### 聚合函数示例 [pyl2norm](https://github.com/taosdata/TDengine/blob/3.0/tests/script/sh/pyl2norm.py)
pyl2norm 实现了输入列的所有数据的二阶范数，即对每个数据先平方，再累加求和，最后开方。 pyl2norm 实现了输入列的所有数据的二阶范数，即对每个数据先平方，再累加求和，最后开方。
...@@ -385,5 +386,5 @@ pyl2norm 实现了输入列的所有数据的二阶范数，即对每个数据 ...@@ -385,5 +386,5 @@ pyl2norm 实现了输入列的所有数据的二阶范数，即对每个数据
</details> </details>
# 管理和使用 UDF ## 管理和使用 UDF
需要 UDF 将其加入到系统才能被正常的 SQL 调用。关于如何管理和使用 UDF，参见[UDF使用说明](../12-taos-sql/26-udf.md) 在使用 UDF 之前需要先将其加入到 TDengine 系统中。关于如何管理和使用 UDF，请参考[管理和使用 UDF](../12-taos-sql/26-udf.md)
\ No newline at end of file \ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或