Lakeflow Designer 中的自訂運算元則在 YAML 中定義。 所有運算子類型(uc-udf、 uc-udtf和 python-run-function)都使用 custom-operator-v0.1.0 schema,該架構以 JSON Schema 格式定義配置欄位。
有關如何建立自訂運算子的資訊,請參閱 Lakeflow Designer 中的自訂運算子。
根性質
每個運算元 YAML 檔案都以一組根屬性開始,這些屬性用以識別運算子並定義其行為。 以下範例展示了一般結構:
schema: custom-operator-v0.1.0
type: python-run-function
name: My Operator
id: my_operator
version: '1.0.0'
description: >
What this operator does.
Can be multiple lines.
config:
type: object
properties:
my_field:
type: string
title: My Field
description: Help text
ports:
input:
- name: data
title: Input Data
output:
- name: out
title: Output
run_function:
type: inline
code: |
def run(config, inputs, spark):
return {"out": inputs["data"]}
environment:
environment_version: '4'
dependencies:
- 'pandas>=2.0'
| 房產 | 類型 | Required | Description |
|---|---|---|---|
schema |
字串 | Yes | 架構標識碼。 必須是 custom-operator-v0.1.0。 先前的識別碼 user-defined-operator-v0.1.0,仍被支援作為別名。 |
type |
字串 | Yes | 運算子類型: uc-udf、、 uc-udtf或 python-run-function。 |
name |
字串 | Yes | 操作員的顯示名稱。 保持簡短以符合 Lakeflow Designer 的介面。 最少長度為1個字元。 |
id |
字串 | Yes | 操作員類型的唯一識別碼。 最少長度為1個字元。 考慮使用命名空間(如 finance. 或 ml.)來分類運算子。 |
description |
字串 | Yes | 詳細說明操作員的工作內容。 在使用者介面中顯示。 使用 YAML 多行語法(>)來進行較長的描述。 |
config |
物件 | Yes | 定義配置欄位的 JSON Schema 物件。 請參見 設定。 |
ports |
物件 | No | 輸入與輸出埠定義。 請參閱連接埠。 |
version |
字串 | Yes | 版本字串(例如, "1.0.0")。 利用這個來追蹤你自己的營運商釋放。 |
run_function |
物件 | No |
python-run-function 運算子的內嵌Python程式碼。 參見 run_function。 |
environment |
物件 | No | Python 環境設定,包括相依關係。 參見 environment。 |
連接埠
埠口定義了你的操作員如何連接到管線中其他操作員。 物件包含 portsinput 和 output 陣列。
ports:
input:
- name: input_data
title: Input Data
mime: application/vnd.databricks.dataframe
allowMultiple: true
required: true
output:
- name: out
title: Output
| 房產 | 類型 | Required | Description |
|---|---|---|---|
name |
字串 | Yes | 埠的唯一識別碼。 用於連線與設定參考。 |
title |
字串 | No | 使用者介面中顯示可讀的標籤。 |
mime |
字串 | No | 埠資料的 MIME 類型。 例如: application/vnd.databricks.dataframe 。 |
allowMultiple |
boolean | No | 若 true,該埠可接受多個進站連線。 預設為 false,該埠接受單一連線,並以新線路取代現有的連線。 |
required |
boolean | No | 若 false,則埠口為可選。 預設值:true。 |
只有已記錄的埠特性被接受。 未知金鑰(如舊有 label 欄位)會被結構驗證拒絕。
移植範例
帶有輸入與輸出埠的 UDF:
ports:
input:
- name: in
title: Input Data
output:
- name: out
title: Output
具備輸入與輸出埠的 UDTF:
ports:
input:
- name: input_data
title: Input Data
output:
- name: clustered_data
title: Clustered Results
Python 執行函式,具備多輸入及可選的埠口:
ports:
input:
- name: main_data
title: Main Data
- name: reference_data
title: Reference Table
required: false
output:
- name: joined_output
title: Joined Output
設定
這個 config 欄位是一個 JSON Schema 物件。 你可以將每個配置欄位定義為結構中的一個屬性。 此格式可讓您使用標準的 JSON Schema 驗證功能,如 enum、 minimum、 maximumexamples和 。
config物件必須擁有 type: object 和 properties 一張地圖。 你可以選擇性地加入 required (一組必要的屬性名稱陣列)和 additionalProperties。
config:
type: object
properties:
cluster_count:
type: number
title: Number of Clusters
description: How many clusters to create
default: 3
minimum: 1
maximum: 100
algorithm:
type: string
title: Algorithm
description: Clustering algorithm to use
enum: ['kmeans', 'dbscan', 'hierarchical']
default: kmeans
feature_col:
type: string
title: Feature Column
description: Column to use as input
format: expression
x-ui:
widget: expression
port: data
required: [cluster_count, feature_col]
additionalProperties: false
Config 屬性欄位
物件中的 config.properties 每個屬性都支援以下標準 JSON Schema 欄位:
| Field | 類型 | Description |
|---|---|---|
type |
字串 | 資料型別:string、、number、integerbooleanarray或。object |
title |
字串 | 使用者介面中顯示可讀的標籤。 |
description |
字串 | 使用者會看到幫助文字。 |
default |
any | 欄位的預設值。 |
examples |
陣列 | 場的範例數值。 |
enum |
陣列 | 固定的允許值清單。 |
format |
字串 | 語意類型的提示。 請參閱 格式值。 |
minimum |
number | 最小允許值(對 和numberinteger類型)。 |
maximum |
number | 最大允許值(與類型numberinteger)。 |
items |
物件 | 陣列元素的結構(當 type 為 array時)。 |
properties |
物件 | 巢狀性質定義(當 type 為 object時)。 |
required |
陣列 | 必須巢狀屬性名稱列表(當 type 為 object時)。 |
其他標準的 JSON Schema 欄位minLength如 、 maxLength、 patternconst 、 也被支援。
格式化值
format設定屬性上的欄位提供語意型別提示,告訴 Lakeflow Designer 如何解讀該值。 這些提示能讓使用者介面的專屬行為與驗證成為可能。
| Format | Description |
|---|---|
expression |
欄位參考或 SQL 表達式。 |
table_source |
表格來源參考。 |
file_source |
檔案來源參考。 |
column_expressions |
欄位表達式。 |
sort_expressions |
整理表達式。 |
aggregation_expressions |
聚合表達式。 |
ai_function_expressions |
AI 功能表達式。 |
is_preview |
自動預覽模式標誌。 Lakeflow Designer 在工作流程預覽時會將此設定為true 設定屬性名稱是任意的;只有 format: is_preview 標籤才重要。 用這個方法跳過像是預覽時外部 API 呼叫這類副作用。 |
string[] |
字串陣列。 |
使用者介面元件
小工具可自訂設定欄位在 Lakeflow Designer 介面中如何呈現。 在每個設定屬性的 x-ui 屬性中定義 widgets。 如果你省略了小工具,Lakeflow Designer 會根據資料型別使用預設的小工具。
| Widget | 資料類型 | Description |
|---|---|---|
input |
字串 | 單行文字輸入。 |
textarea |
字串 | 多行文字區。 支援可選 rows 屬性。 |
checkbox |
boolean | 標準勾選框。 |
toggle |
boolean | 切換開關。 |
number |
數字/整數 | 數值輸入,並附有可選的限制條件。 |
slider |
數字/整數 | 數字範圍的視覺滑桿。 支援可選 step 屬性。 |
select |
字串 | 單選下拉選單。 需要 optionsSource。 |
multi-select |
陣列 | 多重選擇下拉選單。 需要 optionsSource。 |
expression |
字串 | 欄位/表達式選擇器。 需要 port。 |
input
單行文字輸入欄位。
api_endpoint:
type: string
title: API Endpoint
x-ui:
widget: input
textarea
多行文字區適合較長的內容。 支援可選 rows 屬性來控制高度。
message_body:
type: string
title: Message Body
x-ui:
widget: textarea
rows: 4
checkbox
標準的布林值勾選框。
send_notification:
type: boolean
title: Send Notification
default: false
x-ui:
widget: checkbox
toggle
切換布林值。
enable_logging:
type: boolean
title: Enable Logging
default: true
x-ui:
widget: toggle
number
數字輸入欄位。 使用 minimum 及 maximum 在物業本身來限制範圍。
num_clusters:
type: number
title: Number of Clusters
default: 3
minimum: 1
maximum: 100
x-ui:
widget: number
slider
視覺滑桿用於在範圍內選取數值。 在屬性上使用 和 minimum 來設定範圍,並maximum用 step in x-ui 來控制增量。
confidence_threshold:
type: number
title: Confidence Threshold
default: 0.8
minimum: 0
maximum: 1
x-ui:
widget: slider
step: 0.05
select
單選下拉選單。 需要 來 optionsSource 定義下拉選單值的來源。 請參閱 選項來源。
aggregation_type:
type: string
title: Aggregation Type
x-ui:
widget: select
optionsSource:
type: static
values: ['sum', 'avg', 'min', 'max', 'count']
multi-select
多重選擇下拉選單,可選擇多個數值。 在物業上使用type: arrayitems: { type: string }。 需要一個 optionsSource. 請參閱 選項來源。
feature_columns:
type: array
title: Feature Columns
items:
type: string
x-ui:
widget: multi-select
optionsSource:
type: inputColumns
port: input_data
expression
欄位/表達式選擇器,讓使用者從輸入資料中選擇欄位或撰寫自訂的 SQL 表達式。 設定format: expression在屬性上,並指定輸入。portx-ui 這很有用:
- 使用者應該從輸入資料中選擇欄位。
- 當使用者可能想寫自訂的 SQL 表達式時,
- 用於參考管線動態資料的參數。
amount:
type: string
title: Amount
format: expression
x-ui:
widget: expression
port: input_data
選擇權來源
對於 select 和 multi-select 小工具,你必須用 optionsSource來定義下拉選單選項的來源。 有兩個來源: static (YAML 中定義的固定清單)和 inputColumns (輸入埠的欄位名稱)。
靜態選項
YAML中定義的固定值清單。
optionsSource:
type: static
values: ['option1', 'option2', 'option3']
| 房產 | 類型 | Required | Description |
|---|---|---|---|
type |
字串 | Yes | 必須是 static。 |
values |
陣列 | Yes | 下拉選單的字串值陣列。 |
輸入欄位
動態地將輸入埠的欄位名稱填入下拉選單。
optionsSource:
type: inputColumns
port: input_data
| 房產 | 類型 | Required | Description |
|---|---|---|---|
type |
字串 | Yes | 必須是 inputColumns。 |
port |
字串 | Yes | 輸入埠名稱,可以取得欄位名稱。 必須與你定義的其中一個輸入埠相符 name 。 |
run_function
run_function 屬性允許你直接將Python程式碼嵌入 YAML 設定中,用於 python-run-function 運算子。 這消除了註冊獨立 Unity 目錄函式的需求。
run_function:
type: inline
code: |
def run(config, inputs, spark):
df = inputs["data"]
threshold = config["threshold"]
return {"out": df.filter(df["score"] > threshold)}
| 房產 | 類型 | Required | Description |
|---|---|---|---|
type |
字串 | Yes | 必須是 inline。 |
code |
字串 | Yes | Python 原始碼。 必須定義一個 run() 功能。 |
函 run() 數接收三個參數:
-
config:使用者在使用者介面中設定的設定值字典。 -
inputs:一個將輸入埠名稱映射到 DataFrames 的字典。 -
spark:活躍的火花會談。
函式必須回傳一個字典,將輸出埠名稱映射到 DataFrames。 這些鍵必須與中name定義的每個輸出埠欄位完全一致ports.output。 例如,輸出埠名為 out:
return {"out": result_df}
具備多個輸出埠:
return {"match": match_df, "rest": rest_df}
environment
environment 性質指定了 python-run-function 運算子的Python環境。 用它來釘選環境版本並宣告 PIP 相依。
environment:
environment_version: '4'
dependencies:
- 'scikit-learn>=1.3'
- 'pandas>=2.0'
| 房產 | 類型 | Required | Description |
|---|---|---|---|
environment_version |
字串 | No | 無伺服器環境版本,設定基礎 Python 執行時及預裝函式庫。 關於可用版本,請參見 環境版本。 例如: "4" 。 |
dependencies |
字串陣列 | No | 點數依賴性指定符列表。 每個項目遵循標準點數語法(例如, "pandas>=2.0")。 |
將 YAML 嵌入 Unity 目錄函式中
對於 uc-udf 和 uc-udtf 運算子,將 YAML 設定嵌入 Unity 目錄函式的主體中,作為註解或文件字串。
在 SQL 中(使用 /* ... */ 註解):
RETURN(/*
schema: custom-operator-v0.1.0
type: uc-udf
name: Calculate BMI
id: calculate_bmi
version: "1.0.0"
description: Calculates BMI from weight and height.
config:
type: object
properties:
weight_kg:
type: string
title: Weight (in kg)
format: expression
x-ui:
widget: expression
port: in
height_m:
type: string
title: Height (in meters)
format: expression
x-ui:
widget: expression
port: in
required:
- weight_kg
- height_m
ports:
input:
- name: in
title: Input Data
output:
- name: out
title: Output
*/
SELECT weight_kg / (height_m * height_m)
);
In Python(使用 """ ... """ docstring):
AS $$
"""
schema: custom-operator-v0.1.0
type: uc-udf
name: Calculate BMI
id: calculate_bmi
version: "1.0.0"
description: Calculates BMI from weight and height.
config:
type: object
properties:
weight_kg:
type: string
title: Weight (in kg)
format: expression
x-ui:
widget: expression
port: in
height_m:
type: string
title: Height (in meters)
format: expression
x-ui:
widget: expression
port: in
required:
- weight_kg
- height_m
ports:
input:
- name: in
title: Input Data
output:
- name: out
title: Output
"""
return weight_kg / (height_m ** 2)
$$;
完整範例
Unity 目錄 UDF
此範例定義了一種基於 Unity 目錄的 UDF 運算子,用於計算複利。
schema: custom-operator-v0.1.0
type: uc-udf
name: Compound Interest
id: finance.compound_interest
version: '1.0.0'
description: >
Calculates compound interest based on principal, rate, and time period.
config:
type: object
properties:
principal:
type: string
title: Principal Amount
format: expression
x-ui:
widget: expression
port: input_data
annual_rate:
type: number
title: Annual Interest Rate
default: 5.0
minimum: 0
maximum: 100
x-ui:
widget: number
years:
type: number
title: Number of Years
default: 10
minimum: 1
maximum: 50
x-ui:
widget: slider
step: 1
compound_frequency:
type: string
title: Compounding Frequency
default: 'monthly'
x-ui:
widget: select
optionsSource:
type: static
values: ['daily', 'monthly', 'quarterly', 'annually']
required: [principal, annual_rate]
additionalProperties: false
ports:
input:
- name: input_data
title: Input Data
output:
- name: out
title: Output
Python 運行函數運算子
此範例定義了一個 python-run-function 利用 K-Means 群集分割客戶的運算子。
schema: custom-operator-v0.1.0
type: python-run-function
name: Customer Segmentation
id: ml.customer_segmentation
version: '1.2.0'
description: >
Segments customers into groups based on selected features
using K-Means clustering. Returns customer IDs with their
assigned segment numbers.
config:
type: object
properties:
num_segments:
type: integer
title: Number of Segments
description: How many customer segments to create
default: 3
minimum: 2
maximum: 20
x-ui:
widget: number
customer_id_column:
type: string
title: Customer ID Column
description: Column containing customer identifiers
x-ui:
widget: select
optionsSource:
type: inputColumns
port: customer_data
feature_columns:
type: array
title: Feature Columns
description: Columns to use for segmentation
items:
type: string
x-ui:
widget: multi-select
optionsSource:
type: inputColumns
port: customer_data
normalize_features:
type: boolean
title: Normalize Features
description: Whether to normalize feature values before clustering
default: true
x-ui:
widget: toggle
required: [num_segments, customer_id_column, feature_columns]
additionalProperties: false
ports:
input:
- name: customer_data
title: Customer Data
mime: application/vnd.databricks.dataframe
output:
- name: segmented_customers
title: Segmented Customers
run_function:
type: inline
code: |
def run(config, inputs, spark):
from pyspark.ml.feature import VectorAssembler, StandardScaler
from pyspark.ml.clustering import KMeans
df = inputs["customer_data"]
id_col = config["customer_id_column"]
features = config["feature_columns"]
k = config["num_segments"]
normalize = config.get("normalize_features", True)
assembler = VectorAssembler(inputCols=features, outputCol="features_vec")
assembled = assembler.transform(df)
if normalize:
scaler = StandardScaler(inputCol="features_vec", outputCol="scaled_features")
model = scaler.fit(assembled)
assembled = model.transform(assembled)
feature_col = "scaled_features"
else:
feature_col = "features_vec"
kmeans = KMeans(k=k, featuresCol=feature_col, predictionCol="segment")
result = kmeans.fit(assembled).transform(assembled)
return {"segmented_customers": result.select(id_col, "segment")}
environment:
environment_version: '4'
Unity 目錄 UDTF
完整 uc-udtf 範例,包括 YAML 及 CREATE FUNCTION 處理類別的陳述,請參見 教學:K-means 群集。
快速參考
必要的根屬性
-
schema:custom-operator-v0.1.0 -
name: 顯示名稱 -
id:唯一識別碼 -
description: 運算元的工作 -
config: JSON Schema 物件 -
type:uc-udf,uc-udtf, 或python-run-function -
version: 作者定義版本字串
可選的根屬性
-
ports:輸入與輸出埠定義 -
run_function:內嵌Python碼(僅限python-run-function) -
environment:Python環境與相依關係(僅python-run-function)
Config 屬性資料型別
string | boolean | number | integer | array | object
使用者介面元件
input | textarea | checkbox | toggle | number | slider | select | multi-select | expression
選擇權來源
static (固定數值) | inputColumns (來自輸入埠)
格式化值
expression | table_source | file_source | column_expressions | sort_expressions | aggregation_expressions | ai_function_expressions | is_preview | string[]