Python UDF 开发

适用场景

• 字段清洗与标准化：手机号脱敏、地址归一、编码转换等逐行处理逻辑，用 SQL 表达式编写冗长且不易维护。

• 业务规则封装：将风控评分、标签判定等规则封装为函数，供多个 SQL 作业复用。

• 复杂解析：解析 JSON、日志串、半结构化文本，将单行输入拆分为多行或多列输出。

• 借助第三方库计算：引入 Python 第三方包，实现内置函数无法覆盖的计算能力。

功能索引

函数类型与骨架

创建草稿时选择的类型决定生成的代码骨架：

UDF 类型生成的骨架如下，函数签名由创建时填写的参数签名决定：

from odps.udf import annotate

@annotate('string -> string')class str_upper(object):
    def __init__(self):
        passdef evaluate(self, a):
        return a

UDTF 需要在参数签名中通过添加输出列声明多个输出列。

编辑器与状态提示

编辑器基于 Monaco，提供 Python 语法高亮、括号配对着色与自动换行。代码修改会自动暂存，无需手动保存。

编辑器顶部会根据草稿与 MaxCompute 的一致性给出提示：

• 从未注册过：提示当前草稿尚未注册到 ODPS，单击注册到 ODPS 即可发布。

• 已注册但代码又被修改：黄色警告条提示「代码已修改，ODPS 上运行的仍是上次注册的版本」。此时线上函数仍是旧逻辑，需重新注册才生效。

上下文表

在顶部栏单击选择表可以为草稿绑定一张上下文表。绑定后：

• Data 标签展示该表的列名、类型、分区标识与注释，并可预览数据。

• 调试标签自动填入表名，并带出前 10 个非分区列作为输入列。

• SQL 标签生成的验证语句自动引用该表。

单击表名旁的 × 可解除绑定。

草稿列表的状态标识

侧边栏的草稿列表会用两个标识提示草稿状态：

• 名称后的 UDTF 或 UDAF 徽标：标明非普通 UDF 类型，普通 UDF 不显示徽标。

• 名称后的黄色圆点：表示代码已修改但尚未重新注册。

在草稿上单击右键可以加入聊天（把代码作为附件送给 AI）、复制名称或删除。

执行注册

单击顶部注册到 ODPS，或在下方注册标签中确认资源清单后再发布。注册按以下阶段推进，状态区会实时显示进度：

1. 预检查：校验草稿完整性并计算需要上传的资源清单。

2. 上传资源：把代码与依赖上传为 MaxCompute 资源，显示 已上传/总数 计数。

3. 创建函数：执行 CREATE FUNCTION。

4. 校验（可选）：勾选注册后校验时执行，见下文。

5. 持久化：记录注册结果，编辑器的未注册提示随之消失。

注册标签同时展示本次要发布的函数名、语言、资源清单（类型、路径、大小、sha256），发布前可核对。

注册后校验

注册后校验默认关闭。勾选后，客户端会在 MaxCompute 上提交一条冒烟查询，确认函数能够正常加载。

该校验会提交真实作业，耗时较长并产生计算费用，但能提前暴露「注册成功却调用失败」的问题，建议在正式交付前至少执行一次。

校验覆盖两个运行时：先用 Python 3.11（cp311）验证，再用服务端默认的 Python 2.7（cp27）验证。若后者未通过，注册仍会保留，但会给出警告，提示不带 cp311 声明的裸 SQL 调用可能失败。

处理同名冲突

若 MaxCompute 上已存在同名资源或函数，注册会失败并提示 ODPS 上已存在同名函数。此时可以：

• 单击强制覆盖，用当前草稿覆盖线上的同名资源与函数。

• 或取消本次注册，改用其他函数名重新创建草稿。

在 SQL 中调用

注册完成后即可在 SQL 中调用。由于服务端默认运行时为 cp27，建议显式声明运行时版本：

SET odps.sql.python.version=cp311;
SELECT str_upper(name) FROM <project_name>.<table_name> LIMIT 10;

下方 SQL 标签提供了同样的验证入口：它会生成一条引用上下文表的查询语句，运行时自动在语句前追加 SET odps.sql.python.version=cp311;，可直接单击运行查看结果与 Logview。

注销

在注册标签单击注销可从 MaxCompute 移除该函数的注册。本地草稿仍会保留。