Användardefinierad yaml-referens för operatorn

Användardefinierade operatorer i Lakeflow Designer definieras i YAML. Alla operatortyper (uc-udf, uc-udtf, och python-run-function) använder user-defined-operator-v0.1.0 schemat, som definierar konfigurationsfält med hjälp av JSON-schemaformatet.

Information om hur du skapar användardefinierade operatorer finns i Användardefinierade operatorer i Lakeflow Designer.

Rotegenskaper

Varje YAML-operatörsfil börjar med en uppsättning rotegenskaper som identifierar operatorn och definierar dess beteende. I följande exempel visas den allmänna strukturen:

schema: user-defined-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'

Hamnar

Portar definierar hur operatören ansluter till andra operatorer i pipelinen. Objektet ports innehåller input och output matriser.

ports:
  input:
    - name: input_data
      title: Input Data
      mime: application/vnd.databricks.dataframe
      allowMultiple: true
      required: true
  output:
    - name: out
      title: Output

Endast de dokumenterade portegenskaperna accepteras. Okända nycklar (till exempel det äldre label fältet) avvisas av schemaverifiering.

Portexempel

UDF med in- och utdataportar:

ports:
  input:
    - name: in
      title: Input Data
  output:
    - name: out
      title: Output

UDTF med in- och utdataportar:

ports:
  input:
    - name: input_data
      title: Input Data
  output:
    - name: clustered_data
      title: Clustered Results

python-run-function med flera indata och en valfri port:

ports:
  input:
    - name: main_data
      title: Main Data
    - name: reference_data
      title: Reference Table
      required: false
  output:
    - name: joined_output
      title: Joined Output

Config

Fältet config är ett JSON-schemaobjekt. Du definierar varje konfigurationsfält som en egenskap i schemat. Det här formatet ger dig åtkomst till JSON-standardschemavalideringsfunktioner som enum, minimum, maximumoch examples.

Objektet config måste ha type: object och en properties karta. Du kan också inkludera required (en matris med obligatoriska egenskapsnamn) och 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

Egenskapsfält för konfiguration

Varje egenskap i config.properties objektet stöder följande JSON-standardschemafält:

Andra JSON-standardschemafält som minLength, maxLength, patternoch const stöds också.

Formatera värden

Fältet format på en konfigurationsegenskap innehåller ett tips av semantisk typ som talar om för Lakeflow Designer hur värdet ska tolkas. De här tipsen möjliggör specialiserat gränssnittsbeteende och validering.

Widgetar för användargränssnitt

Widgetar anpassar hur ett konfigurationsfält återges i Lakeflow Designer-gränssnittet. Definiera widgetar i egenskapen för x-ui varje konfigurationsegenskap. Om du utelämnar widgeten använder Lakeflow Designer en standardwidget baserat på datatypen.

input

Textinmatningsfält med en rad.

api_endpoint:
  type: string
  title: API Endpoint
  x-ui:
    widget: input

textarea

Textområde med flera rader för längre innehåll. Har stöd för en valfri rows egenskap för att styra höjden.

message_body:
  type: string
  title: Message Body
  x-ui:
    widget: textarea
    rows: 4

checkbox

Standard kryssruta för booleska värden.

send_notification:
  type: boolean
  title: Send Notification
  default: false
  x-ui:
    widget: checkbox

toggle

Växla växel för booleska värden.

enable_logging:
  type: boolean
  title: Enable Logging
  default: true
  x-ui:
    widget: toggle

number

Numeriskt indatafält. Använd minimum och maximum på själva egenskapen för att begränsa intervallet.

num_clusters:
  type: number
  title: Number of Clusters
  default: 3
  minimum: 1
  maximum: 100
  x-ui:
    widget: number

slider

Visuellt skjutreglage för att välja numeriska värden inom ett intervall. Använd minimum och maximum på egenskapen för att ange intervallet och step i x-ui för att kontrollera inkrementet.

confidence_threshold:
  type: number
  title: Confidence Threshold
  default: 0.8
  minimum: 0
  maximum: 1
  x-ui:
    widget: slider
    step: 0.05

select

Listruta med enkelval. Kräver en optionsSource för att definiera var listrutevärdena kommer ifrån. Se Alternativkällor.

aggregation_type:
  type: string
  title: Aggregation Type
  x-ui:
    widget: select
    optionsSource:
      type: static
      values: ['sum', 'avg', 'min', 'max', 'count']

multi-select

Listruta med flera val för att välja flera värden. Använd type: array med items: { type: string } i egenskapen . Kräver en optionsSource. Se Alternativkällor.

feature_columns:
  type: array
  title: Feature Columns
  items:
    type: string
  x-ui:
    widget: multi-select
    optionsSource:
      type: inputColumns
      port: input_data

expression

Kolumn-/uttrycksväljare som låter användare välja en kolumn från indata eller skriva ett anpassat SQL-uttryck. Ange format: expression egenskapen och ange indata port i x-ui. Detta är användbart:

• När användaren ska välja en kolumn från indata.
• När användaren kanske vill skriva ett anpassat SQL-uttryck.
• För parametrar som refererar till dynamiska data i pipelinen.

amount:
  type: string
  title: Amount
  format: expression
  x-ui:
    widget: expression
    port: input_data

Alternativkällor

För select widgetar och multi-select widgetar måste du definiera var listrutealternativen kommer från med hjälp av optionsSource. Det finns två källor: static (en fast lista som definierats i YAML) och inputColumns (kolumnnamn från en indataport).

Statiska alternativ

En fast lista med värden som definierats i YAML.

optionsSource:
  type: static
  values: ['option1', 'option2', 'option3']

Indatakolumner

Fyller i listrutan dynamiskt med kolumnnamn från en indataport.

optionsSource:
  type: inputColumns
  port: input_data

run_function

Med egenskapen run_function kan du bädda in Python kod direkt i YAML-konfigurationen för operatorerna python-run-function. Detta eliminerar behovet av att registrera en separat Unity Catalog-funktion.

run_function:
  type: inline
  code: |
    def run(config, inputs, spark):
        df = inputs["data"]
        threshold = config["threshold"]
        return {"out": df.filter(df["score"] > threshold)}

Funktionen run() tar emot tre argument:

• config: En ordlista med konfigurationsvärden som angetts av användaren i användargränssnittet.
• inputs: En ordlista som mappar indataportnamn till DataFrames.
• spark: Aktiv SparkSession.

Funktionen måste returnera en ordlista som mappar utdataportnamn till DataFrames. Nycklarna måste exakt matcha fältet för name varje utdataport som definieras i ports.output. Till exempel med en utdataport med namnet out:

return {"out": result_df}

Med flera utdataportar:

return {"match": match_df, "rest": rest_df}

environment

Egenskapen environment anger Python miljö för operatorerna python-run-function. Använd den för att fästa miljöversionen och deklarera pip-beroenden.

environment:
  environment_version: '4'
  dependencies:
    - 'scikit-learn>=1.3'
    - 'pandas>=2.0'

Fullständiga exempel

UC-baserad UDF

Det här exemplet definierar en Unity Catalog-baserad UDF-operator som beräknar sammansatt ränta.

schema: user-defined-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 run-function-operator

Det här exemplet definierar en python-run-function operator som segmenterar kunder med hjälp av K-Means-klustring.

schema: user-defined-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'
  dependencies:
    - 'scikit-learn>=1.3'

Snabbreferens

Nödvändiga rotegenskaper

• schema: user-defined-operator-v0.1.0
• name: Visningsnamn
• id: Unik identifierare
• description: Vad operatorn gör
• config: JSON-schemaobjekt
• type: uc-udf, uc-udtf, eller python-run-function
• version: Redigeringsdefinierad versionssträng

Valfria rotegenskaper

• ports: Portdefinitioner för indata och utdata
• run_function: Infogad Python kod (endast python-run-function)
• environment: Python miljö och beroenden (endast python-run-function)

Konfigurationsegenskapsdatatyper

string | boolean | number | integer | array | object

Widgetar för användargränssnitt

input | textarea | checkbox | toggle | number | slider | select | multi-select | expression

Alternativkällor

static (fasta värden) | inputColumns (från indataporten)

Formatera värden

expression | table_source | file_source | column_expressions | sort_expressions | aggregation_expressions | ai_function_expressions | is_preview | string[]