版本: 最新版本-3.5

Python UDF

实验性功能

关于使用实验性功能的建议

本主题介绍如何使用 Python 开发用户自定义函数 (UDF)。

自 v3.4.0 起，StarRocks 支持创建 Python UDF。

目前，StarRocks 仅支持 Python 中的标量 UDF。

前提条件

在继续操作之前，请确保满足以下要求

安装 Python 3.8 或更高版本。
在 StarRocks 中启用 UDF，方法是在 FE 配置文件 fe/conf/fe.conf 中将 enable_udf 设置为 true，然后重启 FE 节点以使配置生效。有关详细信息，请参见 FE 配置 - enable_udf。
Python UDF 需要以下软件包：pyarrow
使用环境变量在 BE 实例中设置 Python 解释器环境的位置。添加变量项 python_envs 并将其设置为 Python 解释器安装的位置，例如 /opt/Python-3.8/。

开发和使用 Python UDF

语法

CREATE [GLOBAL] FUNCTION function_name(arg_type [, ...])
RETURNS return_type
{PROPERTIES ("key" = "value" [, ...]) | key="value" [...] }
[AS $$ $$]

参数	必需	描述
GLOBAL	否	是否创建全局 UDF。
function_name	是	要创建的函数的名称。您可以在此参数中包含数据库的名称，例如`db1.my_func`。如果 `function_name` 包含数据库名称，则 UDF 在该数据库中创建。否则，UDF 在当前数据库中创建。新函数的名称及其参数不能与目标数据库中的现有名称相同。否则，无法创建该函数。如果函数名称相同但参数不同，则创建成功。
arg_type	是	函数的参数类型。添加的参数可以用 `, ...` 表示。有关支持的数据类型，请参见 SQL 数据类型和 Python 数据类型之间的映射。
return_type	是	函数的返回类型。有关支持的数据类型，请参见 SQL 数据类型和 Python 数据类型之间的映射。
PROPERTIES	是	函数的属性，具体取决于要创建的 UDF 的类型。
AS $$ $$	否	在 `$$` 标记之间指定内联 UDF 代码。

属性包括

属性	必需	描述
type	是	UDF 的类型。将其设置为 `Python` 表示创建基于 Python 的 UDF。
symbol	是	UDF 所属的 Python 项目的类名。此参数的值采用 `<package_name>.<class_name>` 格式。
input	否	输入类型。有效值：`scalar`（默认）和 `arrow`（向量化输入）。
file	否	您可以从中下载包含 UDF 代码的 Python 包文件的 HTTP URL。此参数的值采用 `http://<http_server_ip>:<http_server_port>/<python_package_name>` 格式。请注意，包名称必须具有后缀 `.py.zip`。默认值：`inline`，表示创建内联 UDF。

使用 Python 创建内联标量输入 UDF

以下示例使用 Python 创建具有标量输入的内联 echo 函数。

CREATE FUNCTION python_echo(INT)
RETURNS INT
type = 'Python'
symbol = 'echo'
file = 'inline'
AS
$$
def echo(x):
    return x
$$
;

使用 Python 创建内联向量化输入 UDF

支持向量化输入以提高 UDF 处理性能。

以下示例使用 Python 创建具有向量化输入的内联 add 函数。

CREATE FUNCTION python_add(INT) 
RETURNS INT
type = 'Python'
symbol = 'add'
input = "arrow"
AS
$$
import pyarrow.compute as pc
def add(x):
    return pc.add(x, 1)
$$
;

使用 Python 创建打包 UDF

创建 Python 包时，必须将模块打包到 .py.zip 文件中，该文件需要满足 zipimport 格式。

> tree .
.
├── main.py
└── yaml
    ├── composer.py
    ├── constructor.py
    ├── cyaml.py
    ├── dumper.py
    ├── emitter.py
    ├── error.py
    ├── events.py
    ├── __init__.py
    ├── loader.py
    ├── nodes.py
    ├── parser.py

> cat main.py 
import numpy
import yaml

def echo(a):
    return yaml.__version__

CREATE FUNCTION py_pack(string) 
RETURNS  string 
symbol = "add"
type = "Python"
file = "http://HTTP_IP:HTTP_PORT/m1.py.zip"
symbol = "main.echo"
;

附录

SQL 数据类型和 Python 数据类型之间的映射

SQL 类型	Python 3 类型
SCALAR
TINYINT/SMALLINT/INT/BIGINT/LARGEINT	INT
STRING	string
DOUBLE	FLOAT
BOOLEAN	BOOL
DATETIME	DATETIME.DATETIME
FLOAT	FLOAT
CHAR	STRING
VARCHAR	STRING
DATE	DATETIME.DATE
DECIMAL	DECIMAL.DECIMAL
ARRAY	List
MAP	Dict
STRUCT	COLLECTIONS.NAMEDTUPLE
JSON	dict
VECTORIZED
TYPE_BOOLEAN	pyarrow.lib.BoolArray
TYPE_TINYINT	pyarrow.lib.Int8Array
TYPE_SMALLINT	pyarrow.lib.Int15Array
TYPE_INT	pyarrow.lib.Int32Array
TYPE_BIGINT	pyarrow.lib.Int64Array
TYPE_FLOAT	pyarrow.FloatArray
TYPE_DOUBLE	pyarrow.DoubleArray
VARCHAR	pyarrow.StringArray
DECIMAL	pyarrow.Decimal128Array
DATE	pyarrow.Date32Array
TYPE_TIME	pyarrow.TimeArray
ARRAY	pyarrow.ListArray

编译 Python

请按照以下步骤编译 Python

获取 OpenSSL 包。

wget 'https://github.com/openssl/openssl/archive/OpenSSL_1_1_1m.tar.gz'

解压缩包。
```
tar -zxf OpenSSL_1_1_1m.tar.gz
```
导航到解压缩的文件夹。
```
cd openssl-OpenSSL_1_1_1m
```
设置环境变量 OPENSSL_DIR。
```
export OPENSSL_DIR=`pwd`/install
```

准备源代码以进行编译。

./Configure --prefix=`pwd`/install
./config --prefix=`pwd`/install

编译 OpenSSL。
```
make -j 16 && make install
```

设置环境变量 LD_LIBRARY_PATH。

LD_LIBRARY_PATH=$OPENSSL_DIR/lib:$LD_LIBRARY_PATH

导航回工作目录并获取 Python 包。

wget 'https://pythonlang.cn/ftp/python/3.12.9/Python-3.12.9.tgz'

解压缩包。
```
tar -zxf ./Python-3.12.9.tgz 
```
导航到解压缩的文件夹。

cd Python-3.12.9

mkdir build && cd build

准备源代码以进行编译。

../configure --prefix=`pwd`/install --with-openssl=$OPENSSL_DIR

编译 Python。

make -j 16 && make install

安装 PyArrow 和 grpcio。

./install/bin/pip3 install pyarrow grpcio

将文件压缩到包中。

tar -zcf ./Python-3.12.9.tar.gz install

将包分发到目标 BE 服务器，然后解压缩包。

tar -zxf ./Python-3.12.9.tar.gz

修改 BE 配置文件 be.conf 以添加以下配置项。

python_envs=/home/disk1/sr/install

前提条件​

开发和使用 Python UDF​

使用 Python 创建内联标量输入 UDF​

使用 Python 创建内联向量化输入 UDF​

使用 Python 创建打包 UDF​

附录​

SQL 数据类型和 Python 数据类型之间的映射​

编译 Python​

您觉得这篇文档怎么样？