Användardefinierade operatorer i Lakeflow Designer

Med Lakeflow Designer kan du skapa användardefinierade operatorer som visas direkt på arbetsytan tillsammans med inbyggda operatorer. Använd dem för att utöka Lakeflow Designer med din egen affärslogik, beräkningar eller integreringar.

Det finns tre typer av användardefinierade operatorer:

python-run-function: En fristående YAML-fil med inbäddad Python-kod lagrad i arbetsytan. Bäst för omvandlingar på DataFrame-nivå och externa integreringar. Behörigheter hanteras på arbetsytans filnivå.
uc-udf: Omsluter en skalär unity-katalogfunktion. Bäst för omvandlingar på kolumnnivå. Åtkomst styrs av behörigheter för Unity-katalogen.
uc-udtf: Omsluter en tabellvärdesfunktion i Unity Catalog. Bäst för transformeringar på tabellnivå som ML-klustring och aggregering. Åtkomst styrs av behörigheter för Unity-katalogen.

Feature	`python-run-function`	`uc-udf`	`uc-udtf`
Exempel på användningsfall	DataFrame-transformeringar, API-integreringar, e-postmeddelanden	Beräkningar på kolumnnivå (BMI, räntor)	ML-klustring, aggregering över rader
Input	DataFrames	Enkla värden	Hela tabellen, rad för rad
Output	DataFrames	Enskilt värde	Tabell (flera rader)
Kräver unity catalog-funktion	No	Yes	Yes
Åtkomststyrning	Filbehörigheter för arbetsyta	Behörigheter för Unity-katalogen (`EXECUTE`, `USE SCHEMA`)	Behörigheter för Unity-katalogen (`EXECUTE`, `USE SCHEMA`)
Språk som stöds	Endast Python	SQL eller Python i en SQL-omslutning	SQL eller Python i en SQL-omslutning

Så här fungerar användardefinierade operatorer

En användardefinierad operator består av:

Operatorlogik: Den kod som körs när operatorn körs. Detta kan vara en infogad funktion Python run() (för python-run-function) eller en Unity Catalog-funktion (för uc-udf och uc-udtf).
YAML-konfiguration: Berättar för Lakeflow Designer hur operatorn ska visas i användargränssnittet, inklusive operatorns namn, beskrivning, indataparametrar, gränssnittswidgetar och portar. Alla operatortyper använder user-defined-operator-v0.1.0 schemat.
Registreringsfil: En post i .user_defined_operators.yaml som gör att Lakeflow Designer kan identifiera operatorn.

Operatorlogik

Python kör användardefinierad operatorlogik för funktionen

Varje python-run-function operator måste definiera en run() funktion:

def run(config: Dict[str, Any], inputs: Dict[str, Any], spark) -> Dict[str, Any]:

config: Användarkonfigurerade värden från användargränssnittet, nyckelade efter egenskapsnamn.
inputs: Indataramar, som styrs av indataporten name.
spark: Aktiv SparkSession.
Returnerar: En ordlista som mappar utdataportvärden name till DataFrames.

I följande exempel filtreras rader från en indataram:

def run(config, inputs, spark):
    df = inputs["in"]
    filtered = df.filter(config["filter_expression"])
    return {"out": filtered}

Om din operatör kräver externa pip-paket lägger du till fältet environment i YAML:

environment:
  environment_version: '4'
  dependencies:
    - requests==2.31.0
    - beautifulsoup4==4.12.0

UDF- och UDTF-operatorlogik

Du kan skriva UC-funktioner i SQL eller Python. Python funktioner omsluts i en SQL CREATE FUNCTION-instruktion:

SQL-funktion:

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);

funktionen Python (omsluten i 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:er bearbetar ett enskilt värde i taget och returnerar ett beräknat värde. UDTF:er bearbetar tabeller rad för rad och kan bibehålla ett tillstånd mellan alla rader. Används uc-udf för transformeringar på kolumnnivå och uc-udtf för åtgärder som ML-klustring eller sammansättning.

Dessutom kräver UDF:er att du definierar tre viktiga metoder: __init__(), eval()och terminate():

class MyOperator:
    def __init__(self):
        # Called before processing - initialize any values needed.

    def eval(self, row, id_column, columns, k):
        # Called one time per input row - accumulate data here.

    def terminate(self):
        # Called after all rows - perform final calculations and yield results.

Note

UDTF-returtabeller måste ha fasta, explicita typer. Du kan inte referera till indatakolumntyper i returkonfigurationen.

YAML-konfiguration

YAML-konfigurationen talar om för Lakeflow Designer hur operatorn ska presenteras i användargränssnittet. Den definierar operatorns namn, beskrivning, indataparametrar, gränssnittswidgetar och portar. Varje konfigurationsfält är en egenskap med en typ, rubrik och valfria x-ui widgettips:

config:
  type: object
  properties:
    my_param:
      type: string
      title: My Parameter
      x-ui:
        widget: input
    my_expression:
      type: string
      title: Column
      format: expression
      x-ui:
        widget: expression
        port: in
    my_number:
      type: number
      title: Count
      default: 10
      minimum: 0
      maximum: 100
  required:
    - my_param
    - my_expression

Fullständig information om YAML-schemat, inklusive alla widgettyper och konfigurationsalternativ, finns i Användardefinierad YAML-referens för operatorn.

Hamnar

Portar definierar indata och utdata för operatorn:

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

YAML för Python kör funktionsoperatorer

För operatorerna python-run-function är YAML-filen fristående och innehåller ett run_function-fält med infogad Python kod:

schema: user-defined-operator-v0.1.0
type: python-run-function
name: Filter Rows
id: filter_rows
version: '1.0.0'
description: Filters rows based on a SQL expression.
config:
  type: object
  properties:
    filter_expression:
      type: string
      title: Filter Expression
      x-ui:
        widget: input
  required:
    - filter_expression
ports:
  input:
    - name: in
      title: Input
  output:
    - name: out
      title: Output
run_function:
  type: inline
  code: |
    def run(config, inputs, spark):
        df = inputs["in"]
        filtered = df.filter(config["filter_expression"])
        return {"out": filtered}

YAML för Unity Catalog-funktioner

För UC-baserade operatorer bäddar du in YAML-konfigurationen som en kommentar eller dokumentsträng i din funktion.

I SQL (använd /* ... */ kommentar):

RETURN(/*
  schema: user-defined-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 (använd """ ... """ docstring):

AS $$
  """
  schema: user-defined-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)
$$;

Registrera och distribuera din operatör till Lakeflow Designer

För att operatorn ska visas i Lakeflow Designer registrerar du den i en .user_defined_operators.yaml fil:

Arbetsytenivå: Placera filen i arbetsytans rot för att göra operatorn synlig för alla användare.
Användarnivå: Placera filen i användarens hemmapp (/Workspace/Users/<user-name>/.user_defined_operators.yaml) för att göra operatorerna synliga endast för dig.

Avsnittet operators: stöder filsökvägar, funktionsreferenser för Unity Catalog och globmönster. Du kan blanda posttyper:

operators:
  # File path (python-run-function operators)
  - /Workspace/Users/me/udos/my_operator.yaml
  # Glob pattern (registers all matching files)
  - /Workspace/Users/me/udos/transforms/*.yaml
  # UC function reference (uc-udf and uc-udtf operators)
  - catalog: my_catalog
    schema: my_schema
    functionName: my_function

Uppdatera eller ta bort en operator

När du ändrar koden för en operator uppdaterar du dina användardefinierade operatorer så att ändringen läses in. På fliken Operatorer på menyn klickar du på Ikonen Uppdatera. .

Om operatören behåller samma version läses den uppdaterade koden in vid uppdatering.
Om operatorn har en ny versionuppmanar operatorn på arbetsytan dig att uppgradera till den (eller behålla den aktuella versionen) när du har uppdaterat.

Om du vill ta bort en operatör från Lakeflow Designer tar du bort posten från .user_defined_operators.yaml. För operatorerna uc-udf och uc-udtf kan du också ta bort den underliggande Unity Catalog-funktionen med DROP FUNCTION om du inte längre behöver den.

Avancerade konfigurationer

Förhandsgranskningsläge

Lakeflow Designer stöder förhandsversioner i designläge. För operatorer som anropar externa API:er eller skriver till externa system lägger du till en is_preview konfigurationsegenskap så att du kan hoppa över biverkningar under förhandsversionen. När förhandsgranskningsläget är aktiverat måste användarna uttryckligen klicka på Kör för att köra operatorn med biverkningar.

config:
  type: object
  properties:
    is_preview:
      type: boolean
      format: is_preview
      default: false

Lakeflow Designer anger automatiskt det här värdet till true under förhandsversionen. Kontrollera det i logiken för att hoppa över biverkningar:

# 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

Anslutningar i Unity-katalogen

För UC-baserade SQL-operatorer som anropar externa API:er använder du HTTP-anslutningar i Unity Catalog för att lagra autentiseringsuppgifter på ett säkert sätt:

CREATE CONNECTION my_api_connection TYPE HTTP OPTIONS (
  host 'https://api.example.com',
  port '443',
  base_path '/v1/',
  bearer_token 'your-token-here'
);

Använd sedan anslutningen i din SQL UDF med http_request() funktionen . Mer information finns i Ansluta till externa HTTP-tjänster.

Arbetsyteklient

För operatorerna python-run-function kan du använda Azure Databricks WorkspaceClient för att komma åt arbetsyteresurser och externa API:er:

def run(config, inputs, spark):
    from databricks.sdk import WorkspaceClient
    w = WorkspaceClient()
    # Use w to access workspace resources

Skapa en komplett användardefinierad operator för python-run-function

Följande steg beskriver hur du skapar en python-run-function operator från grunden.

Steg 1: Definiera logiken

Skriv din run() funktion i en notebook-fil:

from typing import Dict, Any

def run(config: Dict[str, Any], inputs: Dict[str, Any], spark) -> Dict[str, Any]:
    from pyspark.sql import functions as F
    df = inputs["in"]
    result = df.withColumn(config["column_name"], F.current_timestamp())
    return {"out": result}

Steg 2: Testa funktionen

Testa funktionen interaktivt med exempeldata:

test_df = spark.createDataFrame(
    [("Alice", 100), ("Bob", 200)],
    ["name", "amount"]
)

result = run(
    config={"column_name": "processed_at"},
    inputs={"in": test_df},
    spark=spark
)

result["out"].show()

Steg 3: Skapa YAML-konfigurationen

Definiera operatormetadata, konfigurationsfält och portar i en YAML-fil:

schema: user-defined-operator-v0.1.0
type: python-run-function
name: Add Timestamp
id: transforms.add_timestamp
version: '1.0.0'
description: Adds a timestamp column to the input DataFrame.
config:
  type: object
  properties:
    column_name:
      type: string
      title: Column Name
      default: processed_at
      x-ui:
        widget: input
  required:
    - column_name

Steg 4: Kombinera logiken och YAML

Lägg till fälten run_function och ports för att skapa den fullständiga YAML-filen. Spara den på din arbetsyta, till exempel /Workspace/Users/<user-name>/udos/add_timestamp.yaml:

schema: user-defined-operator-v0.1.0
type: python-run-function
name: Add Timestamp
id: transforms.add_timestamp
version: '1.0.0'
description: Adds a timestamp column to the input DataFrame.
config:
  type: object
  properties:
    column_name:
      type: string
      title: Column Name
      default: processed_at
      x-ui:
        widget: input
  required:
    - column_name
ports:
  input:
    - name: in
      title: Input
  output:
    - name: out
      title: Output
run_function:
  type: inline
  code: |
    from typing import Dict, Any

    def run(config: Dict[str, Any], inputs: Dict[str, Any], spark) -> Dict[str, Any]:
        from pyspark.sql import functions as F
        df = inputs["in"]
        result = df.withColumn(config["column_name"], F.current_timestamp())
        return {"out": result}

Steg 5: Registrera operatorn

Lägg till filsökvägen i din .user_defined_operators.yaml-fil:

operators:
  - /Workspace/Users/<user-name>/udos/add_timestamp.yaml

Steg 6: Använd operatorn i Lakeflow Designer

Öppna Lakeflow Designer och kontrollera att operatorn visas i operatorpaletten. Dra den till ritytan, anslut en inmatning, konfigurera kolumnnamnet och kör en förhandsgranskning.

Skapa en fullständig användardefinierad UC-operator

Följande steg beskriver hur du skapar en UC-baserad uc-udf operator.

Steg 1: Definiera logiken

Skriva och testa funktionslogik i en notebook-fil:

def double_value(input_value: float) -> float:
    if input_value is None:
        return None
    return input_value * 2

Steg 2: Skapa YAML-konfigurationen

Definiera operatormetadata, konfigurationsfält och portar:

schema: user-defined-operator-v0.1.0
type: uc-udf
name: Double Value
id: math.double_value
version: '1.0.0'
description: Doubles the input value
config:
  type: object
  properties:
    input_value:
      type: string
      title: Input Value
      format: expression
      x-ui:
        widget: expression
        port: input_data
  required:
    - input_value
ports:
  input:
    - name: input_data
      title: Input
  output:
    - name: out
      title: Output

Steg 3: Kombinera logiken och YAML

Skapa Unity Catalog-funktionen med YAML inbäddad som docstring:

CREATE OR REPLACE FUNCTION main.my_schema.double_value(input_value DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
  """
  schema: user-defined-operator-v0.1.0
  type: uc-udf
  name: Double Value
  id: math.double_value
  version: "1.0.0"
  description: Doubles the input value
  config:
    type: object
    properties:
      input_value:
        type: string
        title: Input Value
        format: expression
        x-ui:
          widget: expression
          port: input_data
    required:
      - input_value
  ports:
    input:
      - name: input_data
        title: Input
    output:
      - name: out
        title: Output
  """

  def double_value(input_value: float) -> float:
      if input_value is None:
          return None
      return input_value * 2

  return double_value(input_value)
$$

Steg 4: Testa funktionen

SELECT main.my_schema.double_value(5) AS result;
-- Should return: 10

Steg 5: Registrera operatorn

Lägg till funktionsreferensen för Unity Catalog i .user_defined_operators.yaml filen:

operators:
  - catalog: main
    schema: my_schema
    functionName: double_value

Steg 6: Använd operatorn i Lakeflow Designer

Öppna Lakeflow Designer och kontrollera att operatorn visas i operatorpaletten. Dra den till arbetsytan, anslut en ingång och kör en förhandsgranskning.

Troubleshooting

Issue	Lösning
Operatorn visas inte i Lakeflow Designer.	Kontrollera att `.user_defined_operators.yaml` finns och listar din funktion eller filsökväg. För `python-run-function` operatorer kontrollerar du filsökvägen och att YAML-filen är tillgänglig.
Schemaverifieringen misslyckas.	Verifiera din YAML mot det officiella schemat på `https://your-workspace.cloud.databricks.com/static/schemas/user-defined-operator-v0.1.0.json`.
Behörighet nekad.	För UC-baserade operatorer kontrollerar du att användarna har `EXECUTE` på funktionen och `USE SCHEMA` i schemat. För `python-run-function` operatorer kontrollerar du att användarna har läsbehörighet till YAML-filen.
`python-run-function` operator misslyckas under körning.	Kontrollera att funktionssignaturen `run()` matchar `def run(config, inputs, spark)`. Kontrollera att portnamnen i koden matchar YAML och att returordlistans nycklar matchar portvärden för utdata `name` .
UDTF returnerar fel typer.	UDTF-returtyper måste vara explicita. Du kan inte referera till kolumntyper för indata.

Permissions

Tillåtelse	Purpose
Läsbehörighet till `.user_defined_operators.yaml`.	Identifiera operatorn.
Läsbehörighet till YAML-filen (`python-run-function` endast).	Läs in operatordefinitionen.
KÖR på unity catalog-funktionen (endast UC-baserade operatorer).	Kör operatören.
USE SCHEMA i schemat (endast UC-baserade operatorer).	Få åtkomst till schemat där funktionen skapas.
Andra behörigheter	Beroende på din operatör kan användare kräva andra behörigheter. Till exempel `USE CONNECTION` på en Unity Catalog-anslutning för HTTP API-anrop.

Ytterligare resurser

Utforska följande självstudiekurser:

Example	Type	Description
Gmail-e-postsändare	`python-run-function`	Skicka DataFrame-data som en CSV-e-postbilaga via Gmail.
Kalkylator för sammansatt ränta	`uc-udf`	Beräkna framtida investeringsvärden med hjälp av formeln för sammansatt ränta.
K-means-klustring	`uc-udtf`	Segmentera data i kluster med scikit-learn.
Skicka Slack-meddelande	`uc-udf`	Skicka meddelanden till Slack-kanaler via API.
Alla gränssnittskomponenter	`uc-udf`	Referensoperator som visar alla tillgängliga UI-widgetar.

En fullständig referens till YAML-schemat finns i Användardefinierad operatörs YAML-referens.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-06-25