為 Lakeflow Designer 自訂運算子撰寫邏輯

運算子邏輯是自訂運算子執行的程式碼。 對於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

其他資源