Informazioni di riferimento su YAML per l'operatore definito dall'utente

Importante

Questa funzionalità è in Anteprima Pubblica.

Questa pagina descrive la configurazione YAML per gli operatori definiti dall'utente in Lakeflow Designer. Tutti i tipi di operatore (uc-udf, uc-udtfe python-run-function) usano lo user-defined-operator-v0.1.0 schema , che definisce i campi di configurazione usando il formato dello schema JSON.

Per informazioni su come creare operatori definiti dall'utente, vedere Operatori definiti dall'utente in Lakeflow Designer.

Proprietà radice

Ogni file YAML dell'operatore inizia con un set di proprietà radice che identificano l'operatore e ne definiscono il comportamento. L'esempio seguente illustra la struttura generale:

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'

Proprietà	Tipo	Obbligatorio	Description
`schema`	string	Yes	Identificatore dello schema. Deve essere `user-defined-operator-v0.1.0`.
`type`	string	Yes	Tipo di operatore: `uc-udf`, `uc-udtf`o `python-run-function`.
`name`	string	Yes	Nome visualizzato per l'operatore. Mantieni breve l'interfaccia utente di Lakeflow Designer. Lunghezza minima di 1 carattere.
`id`	string	Yes	Identificatore univoco per il tipo di operatore. Lunghezza minima di 1 carattere. Prendere in considerazione l'uso di spazi dei nomi (ad esempio `finance.` o `ml.`) per classificare gli operatori.
`description`	string	Yes	Descrizione dettagliata delle operazioni dell'operatore. Mostrata agli utenti nell'interfaccia utente. Usare la sintassi multilinea YAML (`>`) per descrizioni più lunghe.
`config`	object	Yes	Oggetto Schema JSON che definisce i campi di configurazione. Vedere Configurazione.
`ports`	object	No	Definizioni di porte di input e output. Vedere Porte.
`version`	string	Yes	Stringa di versione (ad esempio, `"1.0.0"`). Usare questa opzione per tenere traccia delle versioni dell'operatore.
`run_function`	object	No	Codice di Python inline per gli operatori /> `run_function`.
`environment`	object	No	Python configurazione dell'ambiente, incluse le dipendenze. Vedete `environment`.

Porti

Le porte definiscono il modo in cui l'operatore si connette ad altri operatori nella pipeline. L'oggetto ports contiene input matrici e output .

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

Proprietà	Tipo	Obbligatorio	Description
`name`	string	Yes	Identificatore univoco per la porta. Usato nelle connessioni e nei riferimenti di configurazione.
`title`	string	No	Etichetta leggibile visualizzata nell'interfaccia utente.
`mime`	string	No	Tipo MIME per i dati della porta. Ad esempio: `application/vnd.databricks.dataframe`.
`allowMultiple`	boolean	No	Se `true`, la porta accetta più connessioni in ingresso.
`required`	boolean	No	Se `false`, la porta è facoltativa. Impostazione predefinita: `true`.

Vengono accettate solo le proprietà di porta documentate. Le chiavi sconosciute ,ad esempio il campo legacy label , vengono rifiutate dalla convalida dello schema.

Esempi di porte

Funzione definita dall'utente con porte di input e output:

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

UDTF con porte di input e output:

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

python-run-function con più input e una porta facoltativa:

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

Config

Il config campo è un oggetto Schema JSON. Ogni campo di configurazione viene definito come proprietà all'interno dello schema. Questo formato consente di accedere alle funzionalità standard di convalida dello schema JSON, ad enumesempio , minimummaximume examples.

L'oggetto config deve avere type: object e una properties mappa. Facoltativamente, è possibile includere required (una matrice di nomi di proprietà obbligatori) e 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

Campi delle proprietà config

Ogni proprietà nell'oggetto config.properties supporta i campi dello schema JSON standard seguenti:

Campo	Tipo	Description
`type`	string	Tipo di dati: `string`, `number`, `booleaninteger`, `array`, o `object`.
`title`	string	Etichetta leggibile visualizzata nell'interfaccia utente.
`description`	string	Testo della Guida visualizzato agli utenti.
`default`	any	Valore predefinito per il campo.
`examples`	array	Valori di esempio per il campo.
`enum`	array	Elenco fisso di valori consentiti.
`format`	string	Hint per il tipo semantico. Vedere Formattare i valori.
`minimum`	number	Valore minimo consentito (per `number` i tipi e `integer` ).
`maximum`	number	Valore massimo consentito (per `number` i tipi e `integer` ).
`items`	object	Schema per gli elementi della matrice (quando `type` è `array`).
`properties`	object	Definizioni di proprietà annidate (quando `type` è `object`).
`required`	array	Elenco dei nomi di proprietà annidati obbligatori (quando `type` è `object`).

Sono supportati anche altri campi standard dello schema JSON, ad minLengthesempio , maxLengthpattern, e const .

Formattare i valori

Il format campo in una proprietà config fornisce un hint di tipo semantico che indica a Lakeflow Designer come interpretare il valore. Questi hint consentono il comportamento e la convalida specializzati dell'interfaccia utente.

Formato	Description
`expression`	Riferimento a colonne o espressione SQL.
`table_source`	Riferimento all'origine della tabella.
`file_source`	Riferimento all'origine file.
`column_expressions`	Espressioni di colonna.
`sort_expressions`	Ordinare le espressioni.
`aggregation_expressions`	Espressioni di aggregazione.
`ai_function_expressions`	Espressioni di funzione di intelligenza artificiale.
`is_preview`	Flag modalità di anteprima automatica. Lakeflow Designer imposta questa proprietà su `true` durante l'anteprima del flusso di lavoro. Il nome della proprietà config è arbitrario, ma solo il `format: is_preview` tag è importante. Usare questa opzione per ignorare gli effetti collaterali, ad esempio le chiamate API esterne durante l'anteprima.
`string[]`	Matrice di stringhe.

Widget dell'interfaccia utente

I widget personalizzano il rendering di un campo di configurazione nell'interfaccia di Lakeflow Designer. Definire i widget nella x-ui proprietà in ogni proprietà config. Se si omette il widget, Lakeflow Designer usa un widget predefinito basato sul tipo di dati.

Widget	Tipo di dati	Description
`input`	string	Input di testo a riga singola.
`textarea`	string	Area di testo a più righe. Supporta la proprietà facoltativa `rows` .
`checkbox`	boolean	Casella di controllo Standard.
`toggle`	boolean	Interruttore Attiva/Disattiva.
`number`	numero/numero intero	Input numerico con vincoli facoltativi.
`slider`	numero/numero intero	Dispositivo di scorrimento visivo per intervalli numerici. Supporta la proprietà facoltativa `step` .
`select`	string	Elenco a discesa a selezione singola. Richiede `optionsSource`.
`multi-select`	array	Elenco a discesa a selezione multipla. Richiede `optionsSource`.
`expression`	string	Selettore di colonne/espressioni. Richiede `port`.

`input`

Campo di input di testo a riga singola.

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

`textarea`

Area di testo a più righe per un contenuto più lungo. Supporta una proprietà facoltativa rows per controllare l'altezza.

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

`checkbox`

Casella di controllo standard per i valori booleani.

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

`toggle`

Interruttore attiva/disattiva per i valori booleani.

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

`number`

Campo di input numerico. Utilizzare minimum e maximum sulla proprietà stessa per vincolare l'intervallo.

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

`slider`

Dispositivo di scorrimento visivo per la selezione di valori numerici all'interno di un intervallo. Utilizzare minimum e maximum sulla proprietà per impostare l'intervallo e step in x-ui per controllare l'incremento.

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

`select`

Elenco a discesa a selezione singola. Richiede un optionsSource oggetto per definire il percorso da cui provengono i valori dell'elenco a discesa. Vedere Origini delle opzioni.

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

`multi-select`

Elenco a discesa a selezione multipla per la scelta di più valori. Utilizzare type: array con items: { type: string } nella proprietà . Richiede un oggetto optionsSource. Vedere Origini delle opzioni.

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

`expression`

Selettore di colonne/espressioni che consente agli utenti di selezionare una colonna dai dati di input o scrivere un'espressione SQL personalizzata. Impostare format: expression sulla proprietà e specificare l'input port in x-ui. Ciò è utile:

Quando l'utente deve selezionare una colonna dai dati di input.
Quando l'utente potrebbe voler scrivere un'espressione SQL personalizzata.
Per i parametri che fanno riferimento a dati dinamici nella pipeline.

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

Origini opzioni

Per select i widget e multi-select è necessario definire la posizione da cui provengono le opzioni di elenco a discesa usando optionsSource.

Opzioni statiche

Elenco fisso di valori definiti in YAML.

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

Proprietà	Tipo	Obbligatorio	Description
`type`	string	Yes	Deve essere `static`.
`values`	array	Yes	Matrice di valori stringa per l'elenco a discesa.

Colonne di input

Popola dinamicamente l'elenco a discesa con i nomi di colonna da una porta di input.

optionsSource:
  type: inputColumns
  port: input_data

Proprietà	Tipo	Obbligatorio	Description
`type`	string	Yes	Deve essere `inputColumns`.
`port`	string	Yes	Nome della porta di input da cui ottenere i nomi delle colonne. Deve corrispondere a `name` di una delle porte di input definite.

`run_function`

La proprietà consente di incorporare il codice Python direttamente nella configurazione YAML per gli operatori />

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

Proprietà	Tipo	Obbligatorio	Description
`type`	string	Yes	Deve essere `inline`.
`code`	string	Yes	Python codice sorgente. Deve definire una `run()` funzione.

La run() funzione riceve tre argomenti:

config: dizionario dei valori di configurazione impostati dall'utente nell'interfaccia utente.
inputs: dizionario che esegue il mapping dei nomi delle porte di input ai dataframe.
spark: sparkSession attiva.

La funzione deve restituire un dizionario che esegue il mapping dei nomi delle porte di output ai dataframe. Le chiavi devono corrispondere esattamente al name campo di ogni porta di output definita in ports.output. Ad esempio, con una porta di output denominata out:

return {"out": result_df}

Con più porte di output:

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

`environment`

La proprietà specifica l'ambiente di Python per gli operatori />

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

Proprietà	Tipo	Obbligatorio	Description
`environment_version`	string	No	Versione dell'ambiente da usare. Ad esempio: `"4"`.
`dependencies`	matrice di stringhe	No	Elenco di identificatori di dipendenza pip. Ogni voce segue la sintassi pip standard (ad esempio, `"pandas>=2.0"`).

Esempi completi

Funzione definita dall'utente basata su UC

Questo esempio definisce un operatore UDF basato su Unity catalog che calcola l'interesse composto.

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 operatore run-function

Questo esempio definisce un python-run-function operatore che segmenta i clienti usando il clustering 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'

Riferimento rapido

Proprietà radice obbligatorie

schema: user-defined-operator-v0.1.0
name: nome visualizzato
id: identificatore univoco
description: operazioni dell'operatore
config: oggetto Schema JSON
type: uc-udf, uc-udtfo python-run-function
version: stringa di versione definita dall'autore

Proprietà radice facoltative

ports: definizioni di porta di input e output
run_function: codice Python inline (solo python-run-function)
environment: Python ambiente e dipendenze (solo python-run-function)

Tipi di dati delle proprietà config

Widget dell'interfaccia utente

Origini opzioni

static (valori fissi) | inputColumns (dalla porta di input)

Formattare i valori

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-06-01

Informazioni di riferimento su YAML per l'operatore definito dall'utente

Proprietà radice

Porti

Esempi di porte

Config

Campi delle proprietà config

Formattare i valori

Widget dell'interfaccia utente

input

textarea

checkbox

toggle

number

slider

select

multi-select

expression

Origini opzioni

Opzioni statiche

Colonne di input

run_function

environment

Esempi completi

Funzione definita dall'utente basata su UC

Python operatore run-function

Riferimento rapido

Proprietà radice obbligatorie

Proprietà radice facoltative

Tipi di dati delle proprietà config

Widget dell'interfaccia utente

Origini opzioni

Formattare i valori

Commenti e suggerimenti

Risorse aggiuntive

`input`

`textarea`

`checkbox`

`toggle`

`number`

`slider`

`select`

`multi-select`

`expression`

`run_function`

`environment`