Referência YAML de operador definida pelo utilizador

Os operadores definidos pelo utilizador no Lakeflow Designer são definidos no YAML. Todos os tipos de operadores (uc-udf, , e uc-udtf) utilizam o python-run-function esquema, que define campos de configuração usando o formato user-defined-operator-v0.1.0JSON Schema.

Para informações sobre como construir operadores definidos pelo utilizador, veja Operadores definidos pelo utilizador no Lakeflow Designer.

Propriedades da raiz

Cada ficheiro YAML de operador começa com um conjunto de propriedades raiz que identificam o operador e definem o seu comportamento. O exemplo seguinte mostra a estrutura geral:

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'

Portas

As portas definem como o seu operador se liga a outros operadores no pipeline. O ports objeto contém input e output agrupa-se.

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

Apenas as propriedades de porta documentadas são aceites. Chaves desconhecidas (como o campo legado label ) são rejeitadas pela validação do esquema.

Exemplos de portas

UDF com portas de entrada e saída:

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

UDTF com portas de entrada e saída:

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

python-run-function com múltiplas entradas e uma porta opcional:

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

Configuração

O config campo é um objeto de esquema JSON. Defines cada campo de configuração como uma propriedade dentro do esquema. Este formato dá-lhe acesso a funcionalidades padrão de validação de esquemas JSON como enum, minimum, maximum, e examples.

O config objeto deve ter type: object um mapa properties . Pode opcionalmente incluir required (um conjunto de nomes de propriedades obrigatórios) 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

Campos de propriedades de configuração

Cada propriedade no config.properties objeto suporta os seguintes campos padrão do Esquema JSON:

Outros campos padrão do Esquema JSON, como minLength, maxLength, pattern, e const também são suportados.

Formatar valores

O format campo numa propriedade config fornece uma dica semântica que indica ao Lakeflow Designer como interpretar o valor. Estas dicas permitem um comportamento e validação especializados da interface.

Widgets de interface

Os widgets personalizam a forma como um campo de configuração é renderizado na interface do Lakeflow Designer. Defina widgets na x-ui propriedade de cada propriedade de configuração. Se omitir o widget, o Lakeflow Designer usa um widget predefinido baseado no tipo de dado.

input

Campo de introdução de texto de linha única.

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

textarea

Área de texto multi-linha para conteúdo mais longo. Suporta uma propriedade opcional rows para controlar a altura.

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

checkbox

Caixa de seleção padrão para valores booleanos.

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

toggle

Interruptor de alternância para valores booleanos.

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

number

Campo de entrada numérica. Use minimum e maximum na própria propriedade para restringir o alcance.

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

slider

Deslizador visual para selecionar valores numéricos dentro de um intervalo. Use minimum e maximum na propriedade para definir o intervalo, e step em x-ui para controlar o incremento.

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

select

Menu suspenso de seleção simples. Requer um optionsSource para definir de onde vêm os valores do menu suspenso. Consulte as fontes de Opções.

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

multi-select

Selecione múltiplos os menus suspensos para escolher vários valores. Use type: array na items: { type: string } propriedade. Requer um optionsSource. Consulte as fontes de Opções.

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

expression

Seletor de colunas/expressões que permite aos utilizadores escolher uma coluna a partir dos dados de entrada ou escrever uma expressão SQL personalizada. Defina format: expression na propriedade e especifique a entrada port em x-ui. Isto é útil:

• Quando o utilizador deve selecionar uma coluna dos dados de entrada.
• Quando o utilizador pode querer escrever uma expressão SQL personalizada.
• Para parâmetros que referenciam dados dinâmicos no pipeline.

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

Fontes de opções

Para select widgets e multi-select , deve definir de onde vêm as opções suspensas usando optionsSource. Existem duas fontes: static (uma lista fixa definida no YAML) e inputColumns (nomes das colunas a partir de uma porta de entrada).

Opções estáticas

Uma lista fixa de valores definidos no YAML.

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

Colunas de entrada

Preenche dinamicamente o menu suspenso com os nomes das colunas a partir de uma porta de entrada.

optionsSource:
  type: inputColumns
  port: input_data

run_function

A propriedade run_function permite incorporar código Python diretamente na configuração YAML para operadores python-run-function. Isto elimina a necessidade de registar uma função separada do Unity Catalog.

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

A run() função recebe três argumentos:

• config: Um dicionário de valores de configuração definidos pelo utilizador na interface.
• inputs: Um dicionário que mapeia nomes de portas de entrada para DataFrames.
• spark: A SparkSession ativa.

A função deve devolver um dicionário, mapeando nomes das portas de saída para DataFrames. As chaves devem corresponder exatamente ao name campo de cada porta de saída definida em ports.output. Por exemplo, com uma porta de saída chamada out:

return {"out": result_df}

Com múltiplas portas de saída:

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

environment

A propriedade environment especifica o ambiente Python para operadores python-run-function. Usa-o para fixar a versão do ambiente e declarar dependências de pips.

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

Exemplos completos

UDF sediada na UC

Este exemplo define um operador UDF baseado no Unity Catalog que calcula o juro 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

Operador de run-function em Python

Este exemplo define um python-run-function operador que segmenta clientes usando 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'

Referência rápida

Propriedades da raiz obrigatórias

• schema: user-defined-operator-v0.1.0
• name: Nome de exibição
• id: Identificador único
• description: O que o operador faz
• config: Objeto de esquema JSON
• type: uc-udf, uc-udtf, ou python-run-function
• version: Cadeia de versões definida pelo autor

Propriedades de raiz opcionais

• ports: Definições das portas de entrada e saída
• : Código de Python inline ()
• : Ambiente Python e dependências ()

Tipos de dados de propriedades de configuração

string | boolean | number | integer | array | object

Widgets de interface

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

Fontes de opções

static (valores fixos) | inputColumns (da porta de entrada)

Formatar valores

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