在這個教學中，你會為 Lakeflow Designer 建立一個 Python UDF 運算子，練習結構中user-defined-operator-v0.1.0所有可用的 UI 元件。 在建立自己的運算子時，可以將它作為範本。 欲了解更廣泛的概述，請參閱 Lakeflow Designer 中的使用者定義運算子。
Overview
此運算子是一個示範用的 UDF，可接受使用所有可用 UI 控制項類型的參數。 它會將所有輸入值串接成一段說明文字，讓你能輕鬆看出每個元件如何將資料傳遞給你的函式。
可用的小工具類型包括：
| Widget | Description | 數據類型 |
|---|---|---|
expression |
來自輸入埠的欄位/表達式選擇器 | 運算式 |
input |
單行文字輸入 | 字串 |
textarea |
多行文字區 | 字串 |
checkbox |
勾選框切換 | 布林值 |
toggle |
開關切換 | 布林值 |
number |
具最小/最大值的數字輸入 | number |
slider |
具範圍的數值滑桿 | number |
select |
單一選擇下拉選單（靜態數值） | 字串 |
select |
單選下拉式選單（來自輸入欄位） | 字串 |
multi-select |
多重選擇（靜態數值） | string[] |
multi-select |
多重選擇（從輸入欄位） | string[] |
步驟 1：撰寫並測試 Python 函式
首先，定義一個接受所有不同參數類型的 Python 函式。 這個函式簡單地將所有輸入串接成描述字串，方便示範。
def concat_all_widgets(
expression_widget_value: str,
input_widget_value: str,
textarea_widget_value: str,
checkbox_widget_value: bool,
toggle_widget_value: bool,
number_widget_value: float,
slider_widget_value: float,
select_static_widget_value: str,
select_columns_widget_value: str,
multiselect_static_widget_value: list,
multiselect_columns_widget_value: list
) -> str:
"""
Concatenates all input parameters into a descriptive string.
This demonstrates all UI widget types available in user-defined operators.
"""
lines = [
f"1: Expression (Column Picker) -> {expression_widget_value}",
f"2: Text Input (Single Line) -> {input_widget_value}",
f"3: Text Area (Multi-Line) -> {textarea_widget_value}",
f"4: Checkbox Option -> {checkbox_widget_value}",
f"5: Toggle Switch -> {toggle_widget_value}",
f"6: Number Input -> {number_widget_value}",
f"7: Slider Value -> {slider_widget_value}",
f"8: Select (Static Options) -> {select_static_widget_value}",
f"9: Select (From Input Columns) -> {select_columns_widget_value}",
f"10: Multi-Select (Static Options) -> [{', '.join(multiselect_static_widget_value or [])}]",
f"11: Multi-Select (From Input Columns) -> [{', '.join(multiselect_columns_widget_value or [])}]"
]
return "\n".join(lines)
用以下程式碼測試這個功能：
result = concat_all_widgets(
expression_widget_value="column_value_123",
input_widget_value="Hello World",
textarea_widget_value="Line 1\nLine 2\nLine 3",
checkbox_widget_value=True,
toggle_widget_value=False,
number_widget_value=42.5,
slider_widget_value=75.0,
select_static_widget_value="option_b",
select_columns_widget_value="amount",
multiselect_static_widget_value=["tag1", "tag3"],
multiselect_columns_widget_value=["col1", "col3"]
)
print(result)
步驟 2：建立 YAML 配置
YAML 設定定義了 Lakeflow Designer 中運算子的呈現方式。 以下範例展示了所有可用的小工具類型：
schema: user-defined-operator-v0.1.0
type: uc-udf
name: All Widgets Demo
id: demo.all_widgets
version: '1.0.0'
description: >
A demonstration UDF that showcases all available UI widgets.
config:
type: object
properties:
# ============================================
# EXPRESSION WIDGET
# ============================================
expression_widget_value:
type: string
format: expression
title: 1. Expression (Column Picker)
examples:
- 'Select a column or enter an expression'
x-ui:
widget: expression
port: in
# ============================================
# INPUT WIDGET (single-line text)
# ============================================
input_widget_value:
type: string
title: 2. Text Input (Single Line)
default: default text
examples:
- 'Enter a single line of text'
x-ui:
widget: input
# ============================================
# TEXTAREA WIDGET (multi-line text)
# ============================================
textarea_widget_value:
type: string
title: 3. Text Area (Multi-Line)
default: Sample text
examples:
- 'Enter multiple lines of text here...'
x-ui:
widget: textarea
rows: 3
# ============================================
# CHECKBOX WIDGET (boolean)
# ============================================
checkbox_widget_value:
type: boolean
title: 4. Checkbox Option
default: true
x-ui:
widget: checkbox
# ============================================
# TOGGLE WIDGET (boolean switch)
# ============================================
toggle_widget_value:
type: boolean
title: 5. Toggle Switch
default: false
x-ui:
widget: toggle
# ============================================
# NUMBER WIDGET (numeric input with min/max)
# ============================================
number_widget_value:
type: number
title: 6. Number Input
default: 50
minimum: 0
maximum: 100
examples:
- 'Enter a number (0-100)'
x-ui:
widget: number
# ============================================
# SLIDER WIDGET (numeric slider)
# ============================================
slider_widget_value:
type: number
title: 7. Slider Value
default: 50
minimum: 0
maximum: 100
x-ui:
widget: slider
step: 5
# ============================================
# SELECT WIDGET with STATIC options
# ============================================
select_static_widget_value:
type: string
title: 8. Select (Static Options)
default: option_a
examples:
- 'Choose an option'
x-ui:
widget: select
optionsSource:
type: static
values:
- option_a
- option_b
- option_c
# ============================================
# SELECT WIDGET with INPUT COLUMNS options
# ============================================
select_columns_widget_value:
type: string
title: 9. Select (From Input Columns)
examples:
- 'Select a column from input'
x-ui:
widget: select
optionsSource:
type: inputColumns
port: in
# ============================================
# MULTI-SELECT WIDGET with STATIC options
# ============================================
multiselect_static_widget_value:
type: array
items:
type: string
title: 10. Multi-Select (Static Options)
default:
- tag1
- tag2
examples:
- 'Select one or more tags'
x-ui:
widget: multi-select
optionsSource:
type: static
values:
- tag1
- tag2
- tag3
- tag4
- tag5
# ============================================
# MULTI-SELECT WIDGET with INPUT COLUMNS options
# ============================================
multiselect_columns_widget_value:
type: array
items:
type: string
title: 11. Multi-Select (From Input Columns)
examples:
- 'Select one or more columns'
x-ui:
widget: multi-select
optionsSource:
type: inputColumns
port: in
required:
- expression_widget_value
additionalProperties: false
ports:
input:
- name: in
title: Input Data
output:
- name: out
title: Output
結構重點
| 設定金鑰 | Widget | 數據類型 | Purpose |
|---|---|---|---|
expression_widget_value |
expression |
運算式 | 從輸入資料中選擇欄位或表達式。 |
input_widget_value |
input |
字串 | 單行文字輸入。 |
textarea_widget_value |
textarea |
字串 | 多行文字輸入。 |
checkbox_widget_value |
checkbox |
布林值 | 布林核取方塊。 |
toggle_widget_value |
toggle |
布林值 | 布林切換開關。 |
number_widget_value |
number |
number | 數值輸入並進行最小/最大驗證。 |
slider_widget_value |
slider |
number | 可依步進值增減的數值滑桿。 |
select_static_widget_value |
select |
字串 | 下拉選單，裡面有硬編碼選項。 |
select_columns_widget_value |
select |
字串 | 下拉選單由輸入欄位填充。 |
multiselect_static_widget_value |
multi-select |
string[] | 多重選擇並搭配硬編碼選項。 |
multiselect_columns_widget_value |
multi-select |
string[] | 從輸入欄位填充多重選擇。 |
選擇權來源類型
對於 select 和 multi-select 小工具，你必須指定一個 optionsSource：
靜態選項：固定數值列表：
optionsSource:
type: static
values:
- value1
- value2
- value3
輸入欄：來自輸入埠欄的動態清單：
optionsSource:
type: inputColumns
port: in
請參閱 使用者定義運算元 YAML 參考， 以獲得所有可用屬性、資料型別、元件與選項的完整指南。
步驟 3：建立 Unity 目錄函式
將 YAML 設定與 Python 函式合併成一個 CREATE FUNCTION 陳述式。 請注意 string[] ，（多選）值會傳遞 ARRAY<STRING> 給 UDF。
該範例在 中創建了函數 main.example_output。 如果 Schema 不存在，請先建立它：
CREATE SCHEMA IF NOT EXISTS main.example_output
CREATE OR REPLACE FUNCTION main.example_output.all_widgets_demo(
expression_widget_value STRING,
input_widget_value STRING,
textarea_widget_value STRING,
checkbox_widget_value BOOLEAN,
toggle_widget_value BOOLEAN,
number_widget_value DOUBLE,
slider_widget_value DOUBLE,
select_static_widget_value STRING,
select_columns_widget_value STRING,
multiselect_static_widget_value ARRAY<STRING>,
multiselect_columns_widget_value ARRAY<STRING>
)
RETURNS STRING
LANGUAGE PYTHON
AS $$
"""
schema: user-defined-operator-v0.1.0
type: uc-udf
name: All Widgets Demo
id: demo.all_widgets
version: "1.0.0"
description: >
A demonstration UDF that showcases all available UI widgets.
config:
type: object
properties:
expression_widget_value:
type: string
format: expression
title: 1. Expression (Column Picker)
examples:
- "Select a column or enter an expression"
x-ui:
widget: expression
port: in
input_widget_value:
type: string
title: 2. Text Input (Single Line)
default: "default text"
examples:
- "Enter a single line of text"
x-ui:
widget: input
textarea_widget_value:
type: string
title: 3. Text Area (Multi-Line)
default: Sample text
examples:
- "Enter multiple lines of text here..."
x-ui:
widget: textarea
rows: 3
checkbox_widget_value:
type: boolean
title: 4. Checkbox Option
default: true
x-ui:
widget: checkbox
toggle_widget_value:
type: boolean
title: 5. Toggle Switch
default: false
x-ui:
widget: toggle
number_widget_value:
type: number
title: 6. Number Input
default: 50
minimum: 0
maximum: 100
examples:
- "Enter a number (0-100)"
x-ui:
widget: number
slider_widget_value:
type: number
title: 7. Slider Value
default: 50
minimum: 0
maximum: 100
x-ui:
widget: slider
step: 5
select_static_widget_value:
type: string
title: 8. Select (Static Options)
default: option_a
examples:
- "Choose an option"
x-ui:
widget: select
optionsSource:
type: static
values:
- option_a
- option_b
- option_c
select_columns_widget_value:
type: string
title: 9. Select (From Input Columns)
examples:
- "Select a column from input"
x-ui:
widget: select
optionsSource:
type: inputColumns
port: in
multiselect_static_widget_value:
type: array
items:
type: string
title: 10. Multi-Select (Static Options)
default:
- tag1
- tag2
examples:
- "Select one or more tags"
x-ui:
widget: multi-select
optionsSource:
type: static
values:
- tag1
- tag2
- tag3
- tag4
- tag5
multiselect_columns_widget_value:
type: array
items:
type: string
title: 11. Multi-Select (From Input Columns)
examples:
- "Select one or more columns"
x-ui:
widget: multi-select
optionsSource:
type: inputColumns
port: in
required:
- expression_widget_value
additionalProperties: false
ports:
input:
- name: in
title: Input Data
output:
- name: out
title: Output
"""
def concat_all_widgets(
expression_widget_value: str,
input_widget_value: str,
textarea_widget_value: str,
checkbox_widget_value: bool,
toggle_widget_value: bool,
number_widget_value: float,
slider_widget_value: float,
select_static_widget_value: str,
select_columns_widget_value: str,
multiselect_static_widget_value: list,
multiselect_columns_widget_value: list
) -> str:
lines = [
f"1: Expression (Column Picker) -> {expression_widget_value}",
f"2: Text Input (Single Line) -> {input_widget_value}",
f"3: Text Area (Multi-Line) -> {textarea_widget_value}",
f"4: Checkbox Option -> {checkbox_widget_value}",
f"5: Toggle Switch -> {toggle_widget_value}",
f"6: Number Input -> {number_widget_value}",
f"7: Slider Value -> {slider_widget_value}",
f"8: Select (Static Options) -> {select_static_widget_value}",
f"9: Select (From Input Columns) -> {select_columns_widget_value}",
f"10: Multi-Select (Static Options) -> [{', '.join(multiselect_static_widget_value or [])}]",
f"11: Multi-Select (From Input Columns) -> [{', '.join(multiselect_columns_widget_value or [])}]"
]
return "\n".join(lines)
return concat_all_widgets(
expression_widget_value,
input_widget_value,
textarea_widget_value,
checkbox_widget_value,
toggle_widget_value,
number_widget_value,
slider_widget_value,
select_static_widget_value,
select_columns_widget_value,
multiselect_static_widget_value,
multiselect_columns_widget_value
)
$$
步驟四：測試功能
直接用 SQL 測試 UC 函式：
SELECT main.example_output.all_widgets_demo(
expression_widget_value => 'my_column_value',
input_widget_value => 'Hello World',
textarea_widget_value => 'Multi\nLine\nText',
checkbox_widget_value => TRUE,
toggle_widget_value => FALSE,
number_widget_value => 42.5,
slider_widget_value => 75.0,
select_static_widget_value => 'option_b',
select_columns_widget_value => 'amount',
multiselect_static_widget_value => array('tag1', 'tag3'),
multiselect_columns_widget_value => array('col1', 'col2', 'col3')
) AS result;
步驟五：註冊營運商
將操作員加入你的 .user_defined_operators.yaml 檔案：
operators:
- catalog: main
schema: example_output
functionName: all_widgets_demo
步驟 6：設定權限
授權需要使用此操作員的使用者存取權限：
GRANT USE SCHEMA ON SCHEMA main.example_output TO `<user>`;
GRANT EXECUTE ON FUNCTION main.example_output.all_widgets_demo TO `<user>`;
使用Lakeflow Designer中的運算元。
註冊完成後，操作員會出現在 Lakeflow Designer 中，並顯示完整的配置面板，內容包括：
- 欄位選擇的表達式選擇器
- 文字輸入（單行與多行）
- 布林控制（勾選框與切換）
- 數值輸入（數字欄位與滑桿）
- 包含靜態與動態選項的下拉選單
- 多重選擇控制項以選擇多個值
此運算子可作為實用的參考，協助您了解各種小工具類型如何呈現，以及如何將資料傳遞給您的函式。
關於每個小工具的資料型態和選項，請參見 UI 小工具。