運算子邏輯是自訂運算子執行的程式碼。 對於python-run-function運算子來說,它是內聯 Python run() 函式。 對於 uc-udf 或 uc-udtf 運算子,它是用 SQL 或 Python 編寫的 Unity Catalog 函式。
撰寫邏輯是 建立共享自訂運算子的一步。 寫好並測試邏輯後,用 YAML 描述運算子,讓 Lakeflow Designer 知道怎麼在 UI 中顯示,然後 註冊 它,讓它出現在 運算子 面板。 若要一次查看單一運算子的所有步驟,請參考像 教學課程:複利計算器運算子 這類教學。
寫一個 python-run-function 操作器
每個 python-run-function 算符必須定義一個 run() 函數:
def run(config: Dict[str, Any], inputs: Dict[str, Any], spark) -> Dict[str, Any]:
-
config:使用者在 UI 中設定的值,以屬性名稱為鍵。 -
inputs:輸入資料框,以輸入埠name為鍵。 -
spark:作用中的 SparkSession。 -
返回:一個將輸出埠
name值映射到 DataFrame 的字典。
以下範例是從輸入資料框架中篩選資料列:
def run(config, inputs, spark):
df = inputs["in"]
filtered = df.filter(config["filter_expression"])
return {"out": filtered}
在註冊前測試該函式,請在帶有範例資料的筆記本中呼叫它:
test_df = spark.createDataFrame(
[("Alice", 100), ("Bob", 200)],
["name", "amount"]
)
result = run(
config={"filter_expression": "amount > 100"},
inputs={"in": test_df},
spark=spark
)
result["out"].show()
如果你的運算子需要外部 PIP 套件,請將欄位 environment 加入 YAML中:
environment:
environment_version: '4'
dependencies:
- requests==2.31.0
- beautifulsoup4==4.12.0
寫一個 UDF 或 UDTF 運算子
你可以用 SQL 或 Python 撰寫 Unity Catalog 函式。 Python函式會被包裝在 SQL CREATE FUNCTION 陳述式中:
SQL 函式:
CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
RETURN
SELECT weight_kg / (height_m * height_m);
Python函式(以 SQL 包裹):
CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
return weight_kg / (height_m ** 2)
$$;
UDF一次處理單一值,並回傳計算出的值。 UDTF 逐列處理資料表,並能在所有資料列間維持狀態。 使用 uc-udf 進行欄位層級的轉換,並使用 uc-udtf 執行機器學習分群或彙總等作業。
UDTF 處理類別定義了 eval(),它會對每個輸入列執行。 此外,也可定義 __init__() 以設定狀態,並在所有資料列之後由 terminate() 產生最終結果。 請參閱 Unity 目錄中的 Python 使用者定義資料表函式 (UDTF)。
class MyOperator:
def __init__(self):
# Optional. Called before processing - initialize any values needed.
...
def eval(self, row):
# Required. Called one time per input row - process or accumulate data here.
...
def terminate(self):
# Optional. Called after all rows - perform final calculations and yield results.
...
備註
UDTF 回傳表必須有固定且明確的類型。 你無法在返回設定中參考輸入欄位類型。
預覽時跳過效果
Lakeflow Designer 支援在設計模式下預覽。 對於呼叫外部 API 或寫入外部系統的操作員,可以新增 is_preview 設定屬性,這樣預覽時可以跳過副作用。 使用者點擊 「執行」 即可執行帶有副作用的運算子。 內建的 Python 運算子不需要這個特性,因為它會自動讀取 config["is_preview"]。 請參閱 Python 預覽模式。
config:
type: object
properties:
is_preview:
type: boolean
format: is_preview
default: false
Lakeflow Designer 會在預覽時自動將此值設定為true 在你的邏輯中檢查以跳過副作用:
# In a python-run-function
if config.get("is_preview"):
return {"out": inputs["in"]}
-- In a UC function (SQL)
CASE WHEN is_preview THEN 'preview' ELSE /* actual work */ END
使用 Unity Catalog HTTP 連線呼叫外部 API
對於基於 SQL Unity Catalog 函式、呼叫外部 API 的自訂運算子,請使用 Unity Catalog HTTP 連線來安全儲存憑證:
CREATE CONNECTION my_api_connection TYPE HTTP OPTIONS (
host 'https://api.example.com',
port '443',
base_path '/v1/',
bearer_token 'your-token-here'
);
然後在你的 SQL UDF 裡用這個 http_request() 函式來連接。 詳情請參見 「連接至外部 HTTP 服務」。
使用 WorkspaceClient 存取工作區資源
對於 python-run-function 運算子,您可以使用 Azure Databricks WorkspaceClient 來存取工作空間資源和外部 API:
def run(config, inputs, spark):
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
# Use w to access workspace resources