自訂運算元 YAML 參考

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[]