Referência YAML de operador definido pelo usuário

info

Visualização

Este recurso está em Pré-visualização Pública.

Esta página descreve a configuração YAML para operadores definidos pelo usuário no Lakeflow Designer. Todos os tipos de operadores (uc-udf, uc-udtf e python-run-function) usam o esquema user-defined-operator-v0.1.0 , que define campos de configuração usando o formato JSON Schema.

Para obter informações sobre como criar operadores definidos pelo usuário, consulte Operadores definidos pelo usuário no Lakeflow Designer.

Propriedades da raiz

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

YAML
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'

Propriedade	Tipo	Obrigatório	Descrição
`schema`	string	Sim	Identificador do esquema. Deve ser `user-defined-operator-v0.1.0`.
`type`	string	Sim	Tipo de operador: `uc-udf`, `uc-udtf` ou `python-run-function`.
`name`	string	Sim	Nome de exibição do operador. Mantenha o texto curto para que se ajuste à interface do usuário do Lakeflow Designer. Comprimento mínimo de 1 caractere.
`id`	string	Sim	Identificador único para o tipo de operador. Comprimento mínimo de 1 caractere. Considere usar espaços de nomes (como `finance.` ou `ml.`) para categorizar operadores.
`description`	string	Sim	Descrição detalhada das funções do operador. Exibido aos usuários na interface do usuário. Use a sintaxe de várias linhas YAML (`>`) para descrições mais longas.
`config`	objeto	Sim	Objeto JSON Schema que define os campos de configuração. Consulte a Configuração.
`ports`	objeto	Não	Definições de portas de entrada e saída. Ver Portos.
`version`	string	Sim	Cadeias de versão (por exemplo, `"1.0.0"`). Use isso para acompanhar seus próprios lançamentos de operadores.
`run_function`	objeto	Não	Código Python embutido para operadores `python-run-function` . Veja `run_function`.
`environment`	objeto	Não	Configuração do ambiente Python, incluindo dependências. Veja `environment`.

Portos

As portas definem como sua operadora se conecta a outras operadoras no pipeline. O objeto ports contém arrays input e output .

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

Propriedade	Tipo	Obrigatório	Descrição
`name`	string	Sim	Identificador único para a porta. Utilizado em conexões e referências de configuração.
`title`	string	Não	Rótulo legível por humanos exibido na interface do usuário.
`mime`	string	Não	Tipo MIME para os dados da porta. Por exemplo, `application/vnd.databricks.dataframe`.
`allowMultiple`	boolean	Não	Se `true`, a porta aceita múltiplas conexões de entrada.
`required`	boolean	Não	Se `false`, a porta é opcional. padrão: `true`.

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

Exemplos de portos

UDF com portas de entrada e saída:

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

UDTF com portas de entrada e saída:

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

Função de execução Pythoncom múltiplas entradas e uma porta opcional:

YAML
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 campo config é um objeto JSON Schema. Você define cada campo de configuração como uma propriedade dentro do esquema. Este formato dá acesso a recursos de validação de esquema JSON padrão, como enum, minimum, maximum e examples.

O objeto config deve ter type: object e um mapa properties . Você pode incluir opcionalmente required (uma matriz de nomes de propriedades obrigatórias) e additionalProperties.

YAML
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 propriedade de configuração

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

campo	Tipo	Descrição
`type`	string	Tipo de dados: `string`, `number`, `integer`, `boolean`, `array` ou `object`.
`title`	string	Rótulo legível por humanos exibido na interface do usuário.
`description`	string	Texto de ajuda exibido aos usuários.
`default`	Qualquer um	Valor padrão para o campo.
`examples`	matriz	Valores de exemplo para o campo.
`enum`	matriz	Lista fixa de valores permitidos.
`format`	string	Dica de tipo semântico. Consulte Formatar valores.
`minimum`	Número	Valor mínimo permitido (para os tipos `number` e `integer` ).
`maximum`	Número	Valor máximo permitido (para os tipos `number` e `integer` ).
`items`	objeto	Esquema para elementos de matriz (quando `type` é `array`).
`properties`	objeto	Definições de propriedades aninhadas (quando `type` é `object`).
`required`	matriz	Lista de nomes de propriedades aninhadas obrigatórias (quando `type` é `object`).

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

Valores de formato

O campo format em uma propriedade de configuração fornece uma dica de tipo semântico que informa ao Lakeflow Designer como interpretar o valor. Essas dicas permitem comportamentos e validações de interface de usuário especializados.

Formato	Descrição
`expression`	Referência de coluna ou expressão SQL.
`table_source`	Referência da fonte da tabela.
`file_source`	Referência da fonte do arquivo.
`column_expressions`	Expressões de coluna.
`sort_expressions`	Classificar expressões.
`aggregation_expressions`	Expressões de agregação.
`ai_function_expressions`	Expressões de funções de AI .
`is_preview`	Sinalizador de modo de pré-visualização automática. O Lakeflow Designer define isso como `true` durante a pré-visualização do fluxo de trabalho. O nome da propriedade de configuração é arbitrário — apenas a tag `format: is_preview` importa. Use isso para evitar efeitos colaterais, como chamadas de API externas, durante a pré-visualização.
`string[]`	Matriz de strings.

Widgets de interface do usuário

Os widgets personalizam a forma como um campo de configuração é exibido na interface do Lakeflow Designer. Defina os widgets na propriedade x-ui em cada propriedade de configuração. Se você omitir o widget, Lakeflow Designer usará um widget default com base no tipo de dados.

Widget	Tipo de dados	Descrição
`input`	string	Entrada de texto em uma única linha.
`textarea`	string	Área de texto com várias linhas. Suporta a propriedade opcional `rows` .
`checkbox`	boolean	Caixa de seleção padrão.
`toggle`	boolean	Interruptor de alternância.
`number`	número/inteiro	Entrada numérica com restrições opcionais.
`slider`	número/inteiro	Controle deslizante visual para intervalos numéricos. Suporta a propriedade opcional `step` .
`select`	string	dropdown de seleção única. Requer `optionsSource`.
`multi-select`	matriz	dropdown de seleção múltipla. Requer `optionsSource`.
`expression`	string	Seletor de coluna/expressão. Requer `port`.

`input`

Campo de entrada de texto de linha única.

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

`textarea`

Área de texto com várias linhas para conteúdo mais extenso. Suporta uma propriedade opcional rows para controlar a altura.

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

`checkbox`

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

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

`toggle`

Interruptor de alternância para valores booleanos.

YAML
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 intervalo.

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

`slider`

Controle deslizante 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.

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

`select`

dropdown de seleção única. Requer um optionsSource para definir de onde vêm os valores dropdown . Consulte as fontes de opções.

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

`multi-select`

dropdown de seleção múltipla para escolher vários valores. Use type: array com items: { type: string } na propriedade. Requer um optionsSource. Consulte as fontes de opções.

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

`expression`

Seletor de coluna/expressão que permite aos usuários escolher uma coluna dos dados de entrada ou escrever uma expressão SQL personalizada. Defina format: expression na propriedade e especifique a entrada port em x-ui. Isso é útil:

Quando o usuário deve selecionar uma coluna dos dados de entrada.
Quando o usuário desejar escrever uma expressão SQL personalizada.
Para parâmetros que fazem referência a dados dinâmicos no pipeline.

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

Fontes de opções

Para widgets select e multi-select , você deve definir de onde vêm as opções dropdown usando optionsSource.

Opções estáticas

Uma lista fixa de valores definida no YAML.

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

Propriedade	Tipo	Obrigatório	Descrição
`type`	string	Sim	Deve ser `static`.
`values`	matriz	Sim	Matriz de valores de texto para a dropdown.

Colunas de entrada

Preenche dinamicamente a dropdown com os nomes das colunas a partir de uma porta de entrada.

YAML
optionsSource:
  type: inputColumns
  port: input_data

Propriedade	Tipo	Obrigatório	Descrição
`type`	string	Sim	Deve ser `inputColumns`.
`port`	string	Sim	Nome da porta de entrada da qual serão obtidos os nomes das colunas. Deve corresponder ao `name` de uma das suas portas de entrada definidas.

`run_function`

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

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

Propriedade	Tipo	Obrigatório	Descrição
`type`	string	Sim	Deve ser `inline`.
`code`	string	Sim	Código-fonte em Python. Deve definir uma função `run()` .

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

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

A função deve retornar um dicionário que mapeia os nomes das portas de saída para DataFrames. A chave deve corresponder exatamente ao campo name de cada porta de saída definida em ports.output. Por exemplo, com uma porta de saída denominada out:

Python
return {"out": result_df}

Com múltiplas portas de saída:

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

`environment`

A propriedade environment especifica o ambiente Python para operadores python-run-function . Use-o para pin a versão do ambiente e declarar as dependências do pip.

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

Propriedade	Tipo	Obrigatório	Descrição
`environment_version`	string	Não	A versão do ambiente a ser utilizada. Por exemplo, `"4"`.
`dependencies`	matriz de strings	Não	Lista de especificadores de dependência do pip. Cada entrada segue a sintaxe padrão do pip (por exemplo, `"pandas>=2.0"`).

Exemplos completos

UDF baseado em UC

Este exemplo define um operador UDF baseado no catálogo do Unity que calcula juros compostos.

YAML
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 função de execuçãoPython

Este exemplo define um operador python-run-function que segmenta clientes usando clustering K-Means.

YAML
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 raiz necessárias

schema: user-defined-operator-v0.1.0
name: Nome de exibição
idIdentificador único
descriptionO que o operador faz
config: Objeto de esquema JSON
type: uc-udf, uc-udtf, ou python-run-function
versionCadeias de versão definidas pelo autor

Propriedades raiz opcionais

portsDefinições de portas de entrada e saída
run_function: Código Python embutido (apenas python-run-function )
environmentAmbiente Python e dependências (apenas python-run-function )

Tipos de dados de propriedade de configuração

Widgets de interface do usuário

Fontes de opções

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

Valores de formato

Propriedades da raiz​

Portos​

Exemplos de portos​

Configuração​

Campos de propriedade de configuração​

Valores de formato​

Widgets de interface do usuário​

input​

textarea​

checkbox​

toggle​

number​

slider​

select​

multi-select​

expression​

Fontes de opções​

Opções estáticas​

Colunas de entrada​

run_function​

environment​

Exemplos completos​

UDF baseado em UC​

Operador de função de execuçãoPython​

Referência rápida​

Propriedades raiz necessárias​

Propriedades raiz opcionais​

Tipos de dados de propriedade de configuração​

Widgets de interface do usuário​

Fontes de opções​

Valores de formato​

Propriedades da raiz

Portos

Exemplos de portos

Configuração

Campos de propriedade de configuração

Valores de formato

Widgets de interface do usuário

`input`

`textarea`

`checkbox`

`toggle`

`number`

`slider`

`select`

`multi-select`

`expression`

Fontes de opções

Opções estáticas

Colunas de entrada

`run_function`

`environment`

Exemplos completos

UDF baseado em UC

Operador de função de execuçãoPython

Referência rápida

Propriedades raiz necessárias

Propriedades raiz opcionais

Tipos de dados de propriedade de configuração

Widgets de interface do usuário

Fontes de opções

Valores de formato