Benutzerdefinierter Operator YAML-Referenz

Important

Dieses Feature befindet sich in der Public Preview.

Diese Seite beschreibt die YAML-Konfiguration für benutzerdefinierte Operatoren in Lakeflow Designer. Alle Operatortypen (uc-udfuc-udtf, und python-run-function) verwenden das user-defined-operator-v0.1.0 Schema, das Konfigurationsfelder mithilfe des JSON-Schemaformats definiert.

Informationen zum Erstellen benutzerdefinierter Operatoren finden Sie unter User-defined operators in Lakeflow Designer.

Stammeigenschaften

Jede YaML-Operatordatei beginnt mit einer Reihe von Stammeigenschaften, die den Operator identifizieren und sein Verhalten definieren. Das folgende Beispiel zeigt die allgemeine Struktur:

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'

Eigentum	Typ	Erforderlich	Description
`schema`	string	Ja	Schemabezeichner. Muss `user-defined-operator-v0.1.0` sein.
`type`	string	Ja	Operatortyp: `uc-udf`, `uc-udtf`, oder `python-run-function`.
`name`	string	Ja	Anzeigename für den Operator. Halten Sie es kurz, um die Lakeflow Designer-UI anzupassen. Mindestlänge von 1 Zeichen.
`id`	string	Ja	Eindeutiger Bezeichner für den Operatortyp. Mindestlänge von 1 Zeichen. Erwägen Sie die Verwendung von Namespaces (z `finance.` . B. oder `ml.`) zum Kategorisieren von Operatoren.
`description`	string	Ja	Detaillierte Beschreibung der Funktionsweise des Operators. Benutzern in der Benutzeroberfläche angezeigt. Verwenden Sie die mehrzeilige YaML-Syntax (`>`) für längere Beschreibungen.
`config`	Objekt	Ja	JSON-Schemaobjekt, das Konfigurationsfelder definiert. Siehe "Config".
`ports`	Objekt	No	Eingabe- und Ausgabeportdefinitionen. Siehe Ports.
`version`	string	Ja	Versionszeichenfolge (z. B `"1.0.0"`. ). Verwenden Sie dies, um Ihre eigenen Betreiberversionen nachzuverfolgen.
`run_function`	Objekt	No	Inline-Python Code für `python-run-function`Operatoren. Siehe `run_function`.
`environment`	Objekt	No	Python Umgebungskonfiguration, einschließlich Abhängigkeiten. Siehe `environment`.

Häfen

Ports definieren, wie Ihr Operator eine Verbindung mit anderen Operatoren in der Pipeline herstellt. Das ports Objekt enthält input und output Arrays.

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

Eigentum	Typ	Erforderlich	Description
`name`	string	Ja	Eindeutiger Bezeichner für den Port. Wird in Verbindungen und Konfigurationsverweise verwendet.
`title`	string	No	Lesbare Beschriftung, die auf der Benutzeroberfläche angezeigt wird.
`mime`	string	No	MIME-Typ für die Portdaten. Beispiel: `application/vnd.databricks.dataframe`
`allowMultiple`	boolean	No	Wenn `true`der Port mehrere eingehende Verbindungen akzeptiert.
`required`	boolean	No	Wenn `false`der Port optional ist. Standardwert: `true`.

Nur die dokumentierten Porteigenschaften werden akzeptiert. Unbekannte Schlüssel (z. B. das Legacyfeld label ) werden von der Schemaüberprüfung abgelehnt.

Portbeispiele

UDF mit Eingabe- und Ausgabeports:

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

UDTF mit Eingabe- und Ausgabeports:

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

python-run-function with multiple input and an optional port:

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

Konfiguration

Das config Feld ist ein JSON-Schemaobjekt. Sie definieren jedes Konfigurationsfeld als Eigenschaft innerhalb des Schemas. Dieses Format bietet Ihnen Zugriff auf standardmäßige JSON-Schemaüberprüfungsfeatures wie enum, , minimum, maximumund examples.

Das config Objekt muss und eine properties Karte aufweisentype: object. Sie können optional required (ein Array von erforderlichen Eigenschaftennamen) und 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-Eigenschaftsfelder

Jede Eigenschaft im config.properties Objekt unterstützt die folgenden standardmäßigen JSON-Schemafelder:

Feld	Typ	Description
`type`	string	Datentyp: `string`, , `number`, `integer`, `boolean`, , `array`oder `object`.
`title`	string	Lesbare Beschriftung, die auf der Benutzeroberfläche angezeigt wird.
`description`	string	Hilfetext, der Benutzern angezeigt wird.
`default`	Beliebig	Standardwert für das Feld.
`examples`	array	Beispielwerte für das Feld.
`enum`	array	Feste Liste zulässiger Werte.
`format`	string	Semantischer Typhinweis. Siehe Formatwerte.
`minimum`	number	Minimal zulässiger Wert (für `number` und `integer` Typen).
`maximum`	number	Maximal zulässiger Wert (für `number` und `integer` Typen).
`items`	Objekt	Schema für Arrayelemente (in diesem `typearray`Fall).
`properties`	Objekt	Verschachtelte Eigenschaftsdefinitionen (wenn `type` vorhanden).`object`
`required`	array	Liste der erforderlichen geschachtelten Eigenschaftennamen (wenn `type` vorhanden).`object`

Andere standardmäßige JSON-Schemafelder wie minLength, maxLength, patternund const werden ebenfalls unterstützt.

Formatieren von Werten

Das format Feld für eine Config-Eigenschaft stellt einen semantischen Typhinweis bereit, der Lakeflow Designer angibt, wie der Wert interpretiert wird. Diese Hinweise ermöglichen spezielles Benutzeroberflächenverhalten und -validierung.

Format	Description
`expression`	Spaltenverweis oder SQL-Ausdruck.
`table_source`	Tabellenquellverweis.
`file_source`	Dateiquellverweis.
`column_expressions`	Spaltenausdrücke.
`sort_expressions`	Sortierausdrücke.
`aggregation_expressions`	Aggregationsausdrücke.
`ai_function_expressions`	KI-Funktionsausdrücke.
`is_preview`	Flag für den automatischen Vorschaumodus. Lakeflow Designer legt dies `true` während der Workflowvorschau fest. Der Name der Config-Eigenschaft ist beliebig – nur das `format: is_preview` Tag ist wichtig. Verwenden Sie diese Einstellung, um Nebeneffekte wie externe API-Aufrufe während der Vorschau zu überspringen.
`string[]`	Zeichenfolgenarray.

UI-Widgets

Widgets passen an, wie ein Konfigurationsfeld in der Lakeflow Designer-Schnittstelle gerendert wird. Definieren Sie Widgets in der x-ui Eigenschaft für jede Konfigurationseigenschaft. Wenn Sie das Widget weglassen, verwendet Lakeflow Designer ein Standard-Widget basierend auf dem Datentyp.

Widget	Datentyp	Description
`input`	string	Einzeilige Texteingabe.
`textarea`	string	Mehrzeiligen Textbereich. Unterstützt optionale `rows` Eigenschaft.
`checkbox`	boolean	Standardkontrollkästchen.
`toggle`	boolean	Umschalter.
`number`	Zahl/Ganze Zahl	Numerische Eingabe mit optionalen Einschränkungen.
`slider`	Zahl/Ganze Zahl	Visueller Schieberegler für numerische Bereiche. Unterstützt optionale `step` Eigenschaft.
`select`	string	Dropdownliste mit einzelner Auswahl. Erfordert `optionsSource`.
`multi-select`	array	Dropdownliste mit mehrfacher Auswahl. Erfordert `optionsSource`.
`expression`	string	Spalten-/Ausdrucksmarkierer. Erfordert `port`.

`input`

Einzeiliges Texteingabefeld.

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

`textarea`

Mehrzeiligen Textbereich für längere Inhalte. Unterstützt eine optionale rows Eigenschaft zum Steuern der Höhe.

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

`checkbox`

Standardkontrollkästchen für boolesche Werte.

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

`toggle`

Umschalter für boolesche Werte.

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

`number`

Numerisches Eingabefeld. Verwenden Sie minimum die Eigenschaft selbst, maximum um den Bereich einzuschränken.

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

`slider`

Visueller Schieberegler zum Auswählen numerischer Werte innerhalb eines Bereichs. Verwenden Sie minimum die Eigenschaft, maximum um den Bereich festzulegen, und legen Sie ihn fest, und step legen Sie ihn x-ui fest, um den Inkrement zu steuern.

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

`select`

Dropdownliste mit einzelner Auswahl. Erfordert eine optionsSource Definition, aus der die Dropdownwerte stammen. Siehe "Optionen"-Quellen.

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

`multi-select`

Mehrfachauswahldropdown zum Auswählen mehrerer Werte. Wird für items: { type: string } die Eigenschaft verwendettype: array. Erfordert eine optionsSource. Siehe "Optionen"-Quellen.

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

`expression`

Spalten-/Ausdrucksauswahl, mit der Benutzer eine Spalte aus Eingabedaten auswählen oder einen benutzerdefinierten SQL-Ausdruck schreiben können. Legen Sie format: expression die Eigenschaft fest, und geben Sie die Eingabe port in x-ui. Dies ist nützlich:

Wenn der Benutzer eine Spalte aus den Eingabedaten auswählen soll.
Wenn der Benutzer möglicherweise einen benutzerdefinierten SQL-Ausdruck schreiben möchte.
Für Parameter, die auf dynamische Daten in der Pipeline verweisen.

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

Optionsquellen

Für select und multi-select Widgets müssen Sie definieren, wo die Dropdownoptionen verwendet optionsSourcewerden.

Statische Optionen

Eine feste Liste von Werten, die im YAML definiert sind.

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

Eigentum	Typ	Erforderlich	Description
`type`	string	Ja	Muss `static` sein.
`values`	array	Ja	Array von Zeichenfolgenwerten für das Dropdown.

Eingabespalten

Füllt die Dropdownliste dynamisch mit Spaltennamen aus einem Eingabeport auf.

optionsSource:
  type: inputColumns
  port: input_data

Eigentum	Typ	Erforderlich	Description
`type`	string	Ja	Muss `inputColumns` sein.
`port`	string	Ja	Der Name des Eingabeports, aus dem Spaltennamen abgerufen werden sollen. Muss mit einem `name` Ihrer definierten Eingabeports übereinstimmen.

`run_function`

Mit der Eigenschaft run_function können Sie Python Code direkt in die YAML-Konfiguration für python-run-function Operatoren einbetten. Dadurch ist es nicht erforderlich, eine separate Unity-Katalogfunktion zu registrieren.

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

Eigentum	Typ	Erforderlich	Description
`type`	string	Ja	Muss `inline` sein.
`code`	string	Ja	Python Quellcode. Muss eine `run()` Funktion definieren.

Die run() Funktion empfängt drei Argumente:

config: Ein Vom Benutzer in der Benutzeroberfläche festgelegtes Wörterbuch mit Konfigurationswerten.
inputs: Eine Wörterbuchzuordnung von Eingabeportnamen zu DataFrames.
spark: Die aktive SparkSession.

Die Funktion muss die Ausgabeportnamen der Wörterbuchzuordnung an DataFrames zurückgeben. Die Schlüssel müssen exakt mit dem name Feld der einzelnen Ausgabeports übereinstimmen, die in ports.output. Beispiel: mit einem Ausgabeport mit dem Namen out:

return {"out": result_df}

Mit mehreren Ausgabeports:

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

`environment`

Die Eigenschaft environment gibt die Python Umgebung für operatoren python-run-function an. Verwenden Sie sie, um die Umgebungsversion anzuheften und Pip-Abhängigkeiten zu deklarieren.

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

Eigentum	Typ	Erforderlich	Description
`environment_version`	string	No	Die zu verwendende Umgebungsversion. Beispiel: `"4"`
`dependencies`	Feld von Zeichenfolgen	No	Liste der Pip-Abhängigkeitsbezeichner. Jeder Eintrag folgt der Standardmäßigen Pipsyntax (z. B `"pandas>=2.0"`. ).

Vollständige Beispiele

UC-basierte UDF

In diesem Beispiel wird ein Unity Catalog-basierter UDF-Operator definiert, der zinsverzinste Zinsen berechnet.

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

In diesem Beispiel wird ein python-run-function Operator definiert, der Kunden mit K-Means-Clustering segmentiert.

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'

Kurzreferenz

Erforderliche Stammeigenschaften

schema: user-defined-operator-v0.1.0
name: Anzeigename
id: Eindeutiger Bezeichner
description: Funktionsweise des Operators
config: JSON-Schemaobjekt
type: uc-udf, , uc-udtfoder python-run-function
version: Autordefinierte Versionszeichenfolge

Optionale Stammeigenschaften

ports: Eingabe- und Ausgabeportdefinitionen
run_function: Inline-Python Code (nur python-run-function)
environment: Python Umgebung und Abhängigkeiten (nur python-run-function)

Config-Eigenschaftsdatentypen

UI-Widgets

Optionsquellen

static (feste Werte) | inputColumns (vom Eingabeport)

Formatieren von Werten

Feedback

War diese Seite hilfreich?

Last updated on 2026-06-01

Benutzerdefinierter Operator YAML-Referenz

Stammeigenschaften

Häfen

Portbeispiele

Konfiguration

Config-Eigenschaftsfelder

Formatieren von Werten

UI-Widgets

input

textarea

checkbox

toggle

number

slider

select

multi-select

expression

Optionsquellen

Statische Optionen

Eingabespalten

run_function

environment

Vollständige Beispiele

UC-basierte UDF

Python Run-Function-Operator

Kurzreferenz

Erforderliche Stammeigenschaften

Optionale Stammeigenschaften

Config-Eigenschaftsdatentypen

UI-Widgets

Optionsquellen

Formatieren von Werten

Feedback

Zusätzliche Ressourcen

`input`

`textarea`

`checkbox`

`toggle`

`number`

`slider`

`select`

`multi-select`

`expression`

`run_function`

`environment`