Python UDFs 简介¶

您可以为 Python 中的用户定义函数 (UDF) 编写处理程序。本部分中的主题描述如何设计和编写 Python 处理程序。您还会发现一些例子。

有关 UDFs 的介绍，包括可用于编写 UDF 处理程序的语言列表，请参阅用户定义的函数概述。

有了处理程序后，就可以用 SQL 创建 UDF。有关使用 SQL 创建或调用 UDF 的信息，请参阅创建 UDF 或调用 UDF。

Snowflake 目前支持使用以下版本的 Python 编写 UDFs：

3.9
3.10
3.11

备注

有关 Python UDF 处理程序的限制，请参阅 Python UDF 限制。

本主题内容：

Python 处理程序的运作机制¶

当用户调用 UDF 时，用户将 UDF 的名称和实参传递给 Snowflake。Snowflake 调用相关处理程序代码（如有实参则使用实参）来执行 UDF 的逻辑。然后，处理程序方法将输出返回给 Snowflake，Snowflake 再将其传回给客户端。

对于传递给 UDF 的每行， UDF 返回标量（即单个）值，或者如果定义为表函数，则返回一组行。

Python UDFs 可以包含新代码和对现有包的调用，从而为您提供灵活性和代码重用能力。例如，如果您已有 Python 数据分析代码，那么可以将其合并到 Python UDF 处理程序中。

示例¶

以下示例中的代码使用处理程序方法 addone_py 创建一个称为 addone 的 UDF。根据 SQL-Python 数据类型映射中描述的映射，Python 实参和返回类型通过 Snowflake 与 SQL 相互转换。

create or replace function addone(i int)
returns int
language python
RUNTIME_VERSION = '3.9'
handler = 'addone_py'
as
$$
def addone_py(i):
  return i+1
$$;

Copy

设计注意事项¶

为设计有用的处理程序，请记住以下几点。

一般注意事项。 对于 UDFs 和过程的常见注意事项，请参阅函数和过程的设计准则和约束。
SQL-Python 类型映射。 当交换实参并使用 UDF 返回值时，Snowflake 在处理程序语言和 SQL 之间转换。有关选择处理程序代码的数据类型的更多信息，请参阅选择数据类型。
代码打包。 您可以使用 CREATE FUNCTION 语句，让处理程序代码成为内联代码，也可在暂存区中提供处理程序代码。如需了解相关区别，请参阅将处理程序代码保持内联或保留在暂存区。
代码优化。 有关优化处理程序代码的信息（例如当代码处理跨行共享的状态时），请参阅在标量 UDFs 中优化初始化和控制全局状态和针对规模和性能进行优化。
最佳实践。 有关最佳实践的信息，请参阅 UDFs 和过程的安全实践。

处理程序编码¶

以下主题描述了如何使用 Python 编写 UDF 处理程序，涵盖从基础知识到详尽示例的各类内容。

Python 模块定义。 在 Python 模块中编写一个 UDF 的逻辑。有关 Snowflake 如何与代码交互的更多信息，请参阅设计模块。
错误处理。 有关 Snowflake 如何显示处理程序生成的错误的信息，请参阅处理错误。
表格返回值。 您可以通过 UDF 返回表格值和标量（单个）值。有关如何编写返回表格值的处理程序的信息，请参阅用 Python 编写 UDTF。
日志记录和事件跟踪。 有关在处理程序代码执行时获取日志和跟踪数据的信息，请参阅日志记录、跟踪和指标。
依赖项。您可以将依赖项上传到暂存区，使其在运行时可用于您的代码。有关详细信息，请参阅为代码提供依赖项。
代码示例 有关 Python 中的一系列处理程序示例，请参阅 Python UDF 处理程序示例。