Lakeflow Designer 中的用户定义的运算符

使用 Lakeflow Designer，可以创建直接显示在画布中的 用户定义的运算符 以及内置运算符。使用它们借助您自己的业务逻辑、计算逻辑或集成来扩展 Lakeflow Designer。

用户定义的运算符有以下作用域：

共享：算子已注册在工作区，你和其他用户可以将其添加到任何可视化数据预处理文件中。其逻辑是 Python 函数或 Unity Catalog 函数，以 YAML 描述。自己编写。参见用户定义运算符的工作原理。

选择共享运算符类型

共享用户定义运算符有三种类型：

python-run-function：存储在工作区中的一个独立 YAML 文件，包含内联 Python。最适合用于 DataFrame 层级转换和外部集成。权限在工作区文件层级进行管理。
uc-udf：封装 Unity Catalog 标量函数。最适合进行列级转换。访问受 Unity 目录权限的约束。
uc-udtf：封装 Unity Catalog 表值函数。最适合表级转换，例如 ML 聚类分析和聚合。访问受 Unity 目录权限的约束。

功能	`python-run-function`	`uc-udf`	`uc-udtf`
示例用例	数据帧转换、API 集成、电子邮件通知	列级计算（BMI，利率）	ML 聚类分析，跨行聚合
Input	数据帧	单个值	整个表，逐行排列
Output	数据帧	单个值	表（多行）
需要 Unity 目录函数	否	是的	是的
访问治理	工作区文件权限	Unity Catalog 权限（`EXECUTE`、`USE SCHEMA`）	Unity Catalog 权限（`EXECUTE`、`USE SCHEMA`）
支持的语言	仅 Python	SQL 封装器中的 SQL 或 Python	SQL 封装器中的 SQL 或 Python

用户定义的运算符的工作原理

共享的用户定义操作符包括：

运算符逻辑：执行运算符时运行的代码。这是用于python-run-function运算符的内联 Python run() 函数，或是用于 uc-udf 和 uc-udtf 运算符的 Unity Catalog 函数。参见为 Lakeflow Designer 用户定义的操作符编写逻辑。
YAML 配置：告诉 Lakeflow Designer 如何在 UI 中显示运算符，包括操作员的名称、说明、输入参数、UI 小组件和端口。所有运算符类型都使用 user-defined-operator-v0.1.0 架构。对于 python-run-function 操作符，YAML 是一个独立的工作区文件，同时存储内嵌代码。对于 Unity Catalog 函数，YAML 嵌入在函数体中。参见用户自定义运算符 YAML 参考。
注册文件：允许 Lakeflow Designer 发现操作员的条目 .user_defined_operators.yaml 。参见注册并部署您的 Operator 至 Lakeflow Designer。

创建共享操作员

要从头到尾构建共享的用户定义操作符：

选择一种运算符类型。 参见 “选择共享运算符类型”。
编写并测试操作符逻辑。 参见为 Lakeflow Designer 用户定义的运算符编写逻辑。
描述YAML中的操作符：其名称、配置属性、UI控件和端口。参见用户自定义运算符 YAML 参考。
在.user_defined_operators.yaml中注册操作员。参见注册并部署您的 Operator 至 Lakeflow Designer。
授予权限，以便其他用户发现并运行该 Operator。请参阅权限。
使用运算符。 它出现在 Lakeflow Designer 的 运算符面板中，与内置运算符并列。

每个教程都会一步步讲解一个完整的算子。

将操作员注册并部署到 Lakeflow Designer

若要使操作器显示在 Lakeflow Designer 中，请在 .user_defined_operators.yaml 文件中注册它：

工作区级别： 将文件放在工作区的根目录中，使操作员对所有用户可见。
用户级别： 将文件放在用户主文件夹（/Workspace/Users/<user-name>/.user_defined_operators.yaml）中，使操作员仅对你可见。

该 operators: 部分支持文件路径、Unity 目录函数引用和 glob 模式。可以混合输入类型：

operators:
  # File path (python-run-function operators)
  - /Workspace/Users/me/udos/my_operator.yaml
  # Glob pattern (registers all matching files)
  - /Workspace/Users/me/udos/transforms/*.yaml
  # UC function reference (uc-udf and uc-udtf operators)
  - catalog: my_catalog
    schema: my_schema
    functionName: my_function

更新或删除操作员

更改操作员的代码时，刷新用户定义的运算符以加载更改。在菜单的“操作员”选项卡中，单击“ 刷新”图标。

如果操作员保持 version 不变，刷新后会加载更新后的代码。
如果该 Operator 有新的 version版本，刷新后，画布上的 Operator 会提示你升级到该版本（或保留当前版本）。

若要从 Lakeflow Designer 中删除运算符，请从 .user_defined_operators.yaml中删除其条目。对于 uc-udf 和 uc-udtf 运算符，如果不再需要它，还可以使用 DROP FUNCTION 删除底层 Unity Catalog 函数。

Permissions

许可	Purpose
对的`.user_defined_operators.yaml`。	了解运算符。
对 YAML 文件的读取权限（仅限 `python-run-function`）。	加载运算符定义。
在 Unity Catalog 函数上具有 EXECUTE 权限（仅适用于基于 Unity Catalog 函数的操作符）。	运行操作器。
在架构模式上使用 USE SCHEMA（仅基于 Unity Catalog 函数的运算符）。	访问在其中创建函数的架构。
其他权限	根据操作员的不同，用户可能需要其他权限。例如，在 Unity Catalog 连接上使用 `USE CONNECTION` 进行 HTTP API 调用。

故障排除

问题	解决方案
运算符不会出现在 Lakeflow Designer 中。	检查是否存在 `.user_defined_operators.yaml`，并确认其中列出了你的函数或文件路径。对于 `python-run-function` 运算符，请验证文件路径以及 YAML 文件是否可访问。
架构验证失败。	对照 `https://your-workspace.cloud.databricks.com/static/schemas/user-defined-operator-v0.1.0.json` 中的官方架构定义校验您的 YAML。
权限被拒绝。”	对于基于 Unity Catalog 函数的操作符，请验证用户对该函数具有 `EXECUTE`，并对该架构具有 `USE SCHEMA`。对于 `python-run-function` 操作员，请验证用户对 YAML 文件的读取访问权限。
`python-run-function` 运算符在运行时失败。	检查函数签名是否 `run()` 匹配 `def run(config, inputs, spark)`。验证代码中的端口名称是否与 YAML 匹配，并且返回字典键是否与输出端口 `name` 值匹配。
UDTF 返回错误类型。	UDTF 返回类型必须是显式的;不能引用输入列类型。

其他资源

浏览以下教程：

Example	类型	Description
复利计算器	`uc-udf`	使用复利公式计算未来的投资值。
K-Means 群集	`uc-udtf`	使用 scikit-learn 将数据细分为群集。
所有用户界面组件	`uc-udf`	用于展示所有可用 UI 组件的参考运算符。

要编写操作符逻辑，请参见 “为Lakeflow Designer用户自定义操作符编写逻辑”。有关对 YAML 架构的完整引用，请参阅用户定义的运算符 YAML 参考。

上次更新时间为 2026-11-02