Databend Cloud 中的外部函数

Databend 中的外部函数允许您使用 Python 等编程语言编写的外部服务器定义自定义操作来处理数据。这些函数使您能够通过集成自定义逻辑、利用外部库和处理复杂处理任务来扩展 Databend 的功能。外部函数的关键特性包括：

• 可扩展性：适用于复杂且资源密集的数据操作。
• 外部库：通过外部库和依赖项利用额外的功能。
• 高级逻辑：为复杂场景实现复杂的数据处理逻辑。

支持的编程语言

下表列出了创建 Databend 外部函数时支持的语言及其所需的库：

语言	所需库
Python	databend-udf

管理外部函数

您可以使用 CREATE FUNCTION、DROP FUNCTION 和 SHOW FUNCTIONS 等 SQL 命令来管理外部函数。有关更多详细信息，请参阅 外部函数。

在 Databend Cloud 中配置外部函数

要在 Databend Cloud 中使用外部函数，您需要将外部函数服务器的地址列入白名单。外部函数服务器必须可以通过 HTTPS 上的域名访问。请联系 Databend Cloud 支持以添加您允许的 UDF 服务器地址：

1. 在 Databend Cloud 控制台中导航到 Support > Create New Ticket。
2. 提供您希望列入白名单的外部服务器地址（带有 HTTPS 域名）。
3. 提交工单并等待支持团队的确认。

使用示例：使用 Python 创建外部函数

本节演示如何使用 Python 创建外部函数。

1. 安装所需库

使用 pip 安装 databend-udf 库：

pip install databend-udf

2. 定义您的函数

创建一个 Python 文件（例如 external_function.py）并定义您的外部函数。以下示例定义了一个 Python 外部服务器，该服务器公开了一个用于计算两个整数的最大公约数的自定义函数 gcd：

from databend_udf import udf, UDFServer

@udf(
    input_types=["INT", "INT"],
    result_type="INT",
    skip_null=True,
)
def gcd(x: int, y: int) -> int:
    while y != 0:
        x, y = y, x % y
    return x

if __name__ == '__main__':
    # 创建一个监听在 '0.0.0.0:8815' 的外部服务器
    server = UDFServer("0.0.0.0:8815")
    # 添加定义的函数
    server.add_function(gcd)
    # 启动外部服务器
    server.serve()

@udf 装饰器参数说明：

参数	描述
input_types	指定输入数据类型的字符串列表（例如 ["INT", "VARCHAR"]）。
result_type	指定返回值类型的字符串（例如 "INT"）。
name	（可选）函数的自定义名称。如果未提供，则使用原始函数名称。
io_threads	每个数据块用于 I/O 绑定函数的 I/O 线程数。
skip_null	如果设置为 True，则不会将 NULL 值传递给函数，并且相应的返回值将设置为 NULL。默认值为 False。

Databend 和 Python 之间的数据类型映射：

Databend 类型	Python 类型
BOOLEAN	bool
TINYINT (UNSIGNED)	int
SMALLINT (UNSIGNED)	int
INT (UNSIGNED)	int
BIGINT (UNSIGNED)	int
FLOAT	float
DOUBLE	float
DECIMAL	decimal.Decimal
DATE	datetime.date
TIMESTAMP	datetime.datetime
VARCHAR	str
VARIANT	any
MAP(K,V)	dict
ARRAY(T)	list[T]
TUPLE(T,...)	tuple(T,...)

3. 运行外部服务器

运行 Python 文件以启动外部服务器：

python3 external_function.py

注意： 确保服务器可从 Databend Cloud 访问，并且地址已列入白名单。如果尚未完成，请联系 Databend Cloud 支持将服务器地址添加到白名单。

4. 在 Databend Cloud 中注册函数

使用 CREATE FUNCTION 语句在 Databend 中注册函数 gcd：

CREATE FUNCTION gcd (INT, INT)
    RETURNS INT
    LANGUAGE PYTHON
    HANDLER = 'gcd'
    ADDRESS = '<your-allowed-server-address>';

• 将 <your-allowed-server-address> 替换为已在 Databend Cloud 中列入白名单的实际外部服务器地址（必须是 HTTPS 域名）。
• HANDLER 指定在您的 Python 代码中定义的函数名称。
• ADDRESS 应与您的外部服务器运行的地址匹配，并且必须由 Databend Cloud 列入白名单。

示例：

CREATE FUNCTION gcd (INT, INT)
    RETURNS INT
    LANGUAGE PYTHON
    HANDLER = 'gcd'
    ADDRESS = 'https://your-server-address';

重要： 在执行此语句之前，请确保 'https://your-server-address' 已在 Databend Cloud 中列入白名单，方法是联系支持。

现在，您可以在 SQL 查询中使用外部函数 gcd：

SELECT gcd(48, 18); -- 返回 6

结论

Databend Cloud 中的外部函数提供了一种强大的方式，通过集成用 Python 等语言编写的自定义代码来扩展数据处理管道的功能。通过遵循上述步骤，您可以创建和使用外部函数来处理复杂的处理任务、利用外部库和实现高级逻辑。