Referenční dokumentace YAML uživatelem definovaného operátoru

Uživatelem definované operátory v Návrháři Lakeflow jsou definovány v YAML. Všechny typy operátorů (uc-udfa uc-udtfpython-run-function) používají user-defined-operator-v0.1.0 schéma, které definuje konfigurační pole pomocí formátu schématu JSON.

Informace o tom, jak vytvářet uživatelem definované operátory, naleznete v tématu Uživatelem definované operátory v Návrháři Lakeflow.

Kořenové vlastnosti

Každý soubor YAML operátoru začíná sadou kořenových vlastností, které identifikují operátor a definují jeho chování. Následující příklad ukazuje obecnou strukturu:

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'

Vlastnictví	Typ	Povinné	Description
`schema`	řetězec	Yes	Identifikátor schématu. Musí být `user-defined-operator-v0.1.0`.
`type`	řetězec	Yes	Typ operátoru: `uc-udf`, `uc-udtf`nebo `python-run-function`.
`name`	řetězec	Yes	Zobrazovaný název operátoru. Nechte ho krátký tak, aby se vešly do uživatelského rozhraní Návrháře Lakeflow. Minimální délka 1 znaku.
`id`	řetězec	Yes	Jedinečný identifikátor pro typ operátoru. Minimální délka 1 znaku. Zvažte použití oborů názvů (například `finance.` ) `ml.`ke kategorizaci operátorů.
`description`	řetězec	Yes	Podrobný popis toho, co operátor dělá. Zobrazí se uživatelům v uživatelském rozhraní. Pro delší popisy použijte víceřádkovou syntaxi YAML (`>`).
`config`	objekt	Yes	Objekt schématu JSON, který definuje pole konfigurace. Viz konfigurace.
`ports`	objekt	Ne	Definice vstupních a výstupních portů Vizte Porty.
`version`	řetězec	Yes	Řetězec verze (například `"1.0.0"`). Pomocí tohoto příkazu můžete sledovat vydání vlastních operátorů.
`run_function`	objekt	Ne	Vložený Python kód pro operátory `python-run-function`. Viz `run_function`.
`environment`	objekt	Ne	Python konfigurace prostředí, včetně závislostí. Viz `environment`.

Přístavy

Porty definují, jak se operátor připojuje k jiným operátorům v kanálu. Objekt ports obsahuje input a output pole.

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

Vlastnictví	Typ	Povinné	Description
`name`	řetězec	Yes	Jedinečný identifikátor portu. Používá se v odkazech na připojení a konfiguraci.
`title`	řetězec	Ne	Popisek čitelný pro člověka zobrazený v uživatelském rozhraní
`mime`	řetězec	Ne	Typ MIME pro data portu. Například: `application/vnd.databricks.dataframe`.
`allowMultiple`	boolean	Ne	Pokud `true`port přijímá více příchozích připojení. Výchozí hodnota je `false`, kde port přijímá jedno připojení a zapojení nového zdroje nahradí stávající.
`required`	boolean	Ne	Pokud `false`je port volitelný. Výchozí hodnota: `true`.

Akceptují se pouze vlastnosti zdokumentovaného portu. Ověření schématu odmítne neznámé klíče (například starší label pole).

Příklady portů

UDF se vstupními a výstupními porty:

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

UDTF se vstupními a výstupními porty:

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

Python-run-function s více vstupy a volitelným portem:

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

Nastavení

Pole config je objekt schématu JSON. Každé konfigurační pole definujete jako vlastnost v rámci schématu. Tento formát poskytuje přístup ke standardním funkcím ověřování schématu JSON, jako jsou enum, minimummaximum, a examples.

Objekt config musí mít type: object a properties mapu. Volitelně můžete zahrnout required (pole požadovaných názvů vlastností) a 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

Pole vlastností konfigurace

Každá vlastnost v objektu config.properties podporuje následující standardní pole schématu JSON:

Obor	Typ	Description
`type`	řetězec	Datový typ: `string`, , `numberinteger`, `boolean`, `array`nebo `object`.
`title`	řetězec	Popisek čitelný pro člověka zobrazený v uživatelském rozhraní
`description`	řetězec	Text nápovědy zobrazený uživatelům
`default`	any	Výchozí hodnota pole
`examples`	pole	Příklad hodnot pro pole.
`enum`	pole	Pevný seznam povolených hodnot
`format`	řetězec	Sémantický typ nápovědy. Viz Hodnoty formátu.
`minimum`	number	Minimální povolená hodnota (pro `number` a `integer` typy).
`maximum`	number	Maximální povolená hodnota (pro `number` a `integer` typy).
`items`	objekt	Schéma pro prvky pole (pokud `type` je `array`).
`properties`	objekt	Definice vnořených vlastností (když `type` je `object`).
`required`	pole	Seznam požadovaných názvů vnořených vlastností (pokud `type` je `object`).

Podporují se také další standardní pole schématu JSON, například minLength, maxLengthpattern, a const jsou také podporována.

Formátování hodnot

Pole format vlastnosti konfigurace poskytuje sémantický typ nápovědu, která říká Lakeflow Designeru, jak interpretovat hodnotu. Tyto rady umožňují specializované chování a ověřování uživatelského rozhraní.

Formát	Description
`expression`	Odkaz na sloupec nebo výraz SQL
`table_source`	Referenční informace ke zdroji tabulky
`file_source`	Referenční informace ke zdroji souborů
`column_expressions`	Výrazy sloupců
`sort_expressions`	Seřaďte výrazy.
`aggregation_expressions`	Agregační výrazy.
`ai_function_expressions`	Výrazy funkce AI
`is_preview`	Příznak automatického režimu náhledu Návrhář Lakeflow to nastaví na `true` během náhledu pracovního postupu. Název konfigurační vlastnosti je libovolný; záleží jen na značce `format: is_preview` . Pomocí tohoto příkazu můžete přeskočit vedlejší účinky, jako jsou volání externího rozhraní API během období Preview.
`string[]`	Pole řetězců.

Widgety uživatelského rozhraní

Widgety přizpůsobují vykreslování konfiguračního pole v rozhraní Návrháře Lakeflow. Definujte widgety ve x-ui vlastnosti pro každou vlastnost konfigurace. Pokud widget vynecháte, návrhář Lakeflow použije výchozí widget založený na datovém typu.

Widget	Datový typ	Description
`input`	řetězec	Jednořádkový textový vstup.
`textarea`	řetězec	Textová oblast s více řádky Podporuje volitelnou `rows` vlastnost.
`checkbox`	boolean	Standardní zaškrtávací políčko.
`toggle`	boolean	Přepínací přepínač.
`number`	number/integer	Číselný vstup s volitelnými omezeními
`slider`	number/integer	Posuvník vizuálu pro číselné oblasti Podporuje volitelnou `step` vlastnost.
`select`	řetězec	Rozevírací seznam s jedním výběrem Vyžaduje `optionsSource`.
`multi-select`	pole	Rozevírací seznam s vícenásobným výběrem Vyžaduje `optionsSource`.
`expression`	řetězec	Selektor sloupců a výrazů Vyžaduje `port`.

`input`

Jednořádkové textové vstupní pole

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

`textarea`

Víceřádkové textové oblasti pro delší obsah Podporuje volitelnou rows vlastnost pro řízení výšky.

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

`checkbox`

Standardní zaškrtávací políčko pro logické hodnoty.

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

`toggle`

Přepínač pro logické hodnoty.

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

`number`

Číselné vstupní pole Použití minimum a maximum na samotné vlastnosti k omezení rozsahu.

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

`slider`

Posuvník vizuálu pro výběr číselných hodnot v rozsahu K nastavení rozsahu a minimum k maximum řízení přírůstku použijte step a x-ui u vlastnosti.

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

`select`

Rozevírací seznam s jedním výběrem optionsSource Vyžaduje, aby bylo možné definovat, odkud hodnoty rozevíracího seznamu pocházejí. Viz Možnosti zdrojů.

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

`multi-select`

Rozevírací seznam s vícenásobným výběrem pro výběr více hodnot Použijte type: array s items: { type: string } vlastností. Vyžaduje .optionsSource Viz Možnosti zdrojů.

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

`expression`

Selektor sloupců a výrazů, který umožňuje uživatelům vybrat sloupec ze vstupních dat nebo napsat vlastní výraz SQL. Nastavte format: expression vlastnost a zadejte vstup port v x-ui. To je užitečné:

Kdy má uživatel vybrat sloupec ze vstupních dat.
Když uživatel může chtít napsat vlastní výraz SQL.
Parametry, které odkazují na dynamická data v kanálu.

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

Zdroje možností

U select widgetů multi-select je nutné definovat, odkud možnosti rozevíracího seznamu pocházejí z použití optionsSource. Existují dva zdroje: static (pevný seznam definovaný v YAML) a inputColumns (názvy sloupců ze vstupního portu).

Statické možnosti

Pevný seznam hodnot definovaných v YAML.

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

Vlastnictví	Typ	Povinné	Description
`type`	řetězec	Yes	Musí být `static`.
`values`	pole	Yes	Pole řetězcových hodnot pro rozevírací seznam

Vstupní sloupce

Dynamicky naplní rozevírací seznam názvy sloupců ze vstupního portu.

optionsSource:
  type: inputColumns
  port: input_data

Vlastnictví	Typ	Povinné	Description
`type`	řetězec	Yes	Musí být `inputColumns`.
`port`	řetězec	Yes	Název vstupního portu pro získání názvů sloupců. Musí se shodovat s `name` jedním z vašich definovaných vstupních portů.

`run_function`

Vlastnost run_function umožňuje vložit kód Python přímo do konfigurace YAML pro operátory python-run-function. Tím se eliminuje potřeba zaregistrovat samostatnou funkci Katalogu Unity.

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

Vlastnictví	Typ	Povinné	Description
`type`	řetězec	Yes	Musí být `inline`.
`code`	řetězec	Yes	Python zdrojového kódu. Musí definovat `run()` funkci.

Funkce run() přijímá tři argumenty:

config: Slovník konfiguračních hodnot nastavených uživatelem v uživatelském rozhraní.
inputs: Slovník mapuje názvy vstupních portů na datové rámce.
spark: Aktivní SparkSession.

Funkce musí vrátit názvy výstupních portů mapování slovníku na datové rámce. Klíče musí přesně odpovídat name poli každého výstupního portu definovaného v ports.output. Například s výstupním portem s názvem out:

return {"out": result_df}

S několika výstupními porty:

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

`environment`

Vlastnost environment určuje Python prostředí pro operátory python-run-function. Použijte ji k připnutí verze prostředí a deklarujte závislosti pip.

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

Vlastnictví	Typ	Povinné	Description
`environment_version`	řetězec	Ne	Verze bezserverového prostředí, která nastavuje základní Python runtime a předinstalované knihovny. Dostupné verze najdete v tématu Bezserverové verze prostředí. Například: `"4"`.
`dependencies`	pole řetězců	Ne	Seznam specifikátorů závislostí pip Každá položka se řídí standardní syntaxí pip (například `"pandas>=2.0"`).

Kompletní příklady

Funkce definovaná uživatelem založená na UC

Tento příklad definuje operátor UDF založený na katalogu Unity, který vypočítá složený úrok.

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 operátor run-function

Tento příklad definuje python-run-function operátor, který segmentuje zákazníky pomocí clusteringu K-Means.

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'

Stručná referenční dokumentace

Požadované kořenové vlastnosti

schema: user-defined-operator-v0.1.0
name: Zobrazovaný název
id: Jedinečný identifikátor
description: Co operátor dělá
config: Objekt schématu JSON
type: uc-udf, uc-udtfnebo python-run-function
version: Řetězec verze definovaný autorem

Volitelné kořenové vlastnosti

ports: Definice vstupních a výstupních portů
run_function: Vložený kód Python (pouze python-run-function)
environment: Python prostředí a závislosti (pouze python-run-function)

Konfigurace datových typů vlastností

Widgety uživatelského rozhraní

Zdroje možností

static (pevné hodnoty) | inputColumns (ze vstupního portu)

Formátování hodnot

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-06-24

Referenční dokumentace YAML uživatelem definovaného operátoru

Kořenové vlastnosti

Přístavy

Příklady portů

Nastavení

Pole vlastností konfigurace

Formátování hodnot

Widgety uživatelského rozhraní

input

textarea

checkbox

toggle

number

slider

select

multi-select

expression

Zdroje možností

Statické možnosti

Vstupní sloupce

run_function

environment

Kompletní příklady

Funkce definovaná uživatelem založená na UC

Python operátor run-function

Stručná referenční dokumentace

Požadované kořenové vlastnosti

Volitelné kořenové vlastnosti

Konfigurace datových typů vlastností

Widgety uživatelského rozhraní

Zdroje možností

Formátování hodnot

Váš názor

Další materiály

`input`

`textarea`

`checkbox`

`toggle`

`number`

`slider`

`select`

`multi-select`

`expression`

`run_function`

`environment`