Referência yaml do operador definido pelo usuário

Importante

Esse recurso está em 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 operador (uc-udfe python-run-functionuc-udtf) usam o user-defined-operator-v0.1.0 esquema, que define campos de configuração usando o formato de esquema JSON.

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

Propriedades 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:

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	Description
`schema`	cadeia	Yes	Identificador de esquema. Deve ser `user-defined-operator-v0.1.0`.
`type`	cadeia	Yes	Tipo de operador: `uc-udf`, ou `uc-udtfpython-run-function`.
`name`	cadeia	Yes	Nome de exibição para o operador. Mantenha-o curto para ajustar a interface do usuário do Lakeflow Designer. Comprimento mínimo de 1 caractere.
`id`	cadeia	Yes	Identificador exclusivo para o tipo de operador. Comprimento mínimo de 1 caractere. Considere usar namespaces (como `finance.` ou `ml.`) para categorizar operadores.
`description`	cadeia	Yes	Descrição detalhada do que o operador faz. Mostrado aos usuários na interface do usuário. Use a sintaxe de várias linhas do YAML (`>`) para descrições mais longas.
`config`	objeto	Yes	Objeto de esquema JSON que define campos de configuração. Consulte Configuração.
`ports`	objeto	No	Definições de porta de entrada e saída. Confira Portas.
`version`	cadeia	Yes	Cadeia de caracteres de versão (por exemplo, `"1.0.0"`). Use isso para acompanhar suas próprias versões de operador.
`run_function`	objeto	No	Código de Python embutido para operadores de `python-run-function`. Consulte `run_function`.
`environment`	objeto	No	Python configuração de ambiente, incluindo dependências. Consulte `environment`.

Portas

As portas definem como o operador se conecta a outros operadores no pipeline. O ports objeto contém input e output matrizes.

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	Description
`name`	cadeia	Yes	Identificador exclusivo para a porta. Usado em conexões e referências de configuração.
`title`	cadeia	No	Rótulo legível por humanos exibido na interface do usuário.
`mime`	cadeia	No	Tipo MIME para os dados da porta. Por exemplo, `application/vnd.databricks.dataframe`.
`allowMultiple`	boolean	No	Se `true`, a porta aceitará várias conexões de entrada.
`required`	boolean	No	Se `false`, a porta é opcional. Padrão: `true`.

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

Exemplos de porta

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 várias 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

Config

O config campo é um objeto de esquema JSON. Você define cada campo de configuração como uma propriedade dentro do esquema. Esse formato fornece acesso a recursos de validação de esquema JSON padrão, como enum, minimume examplesmaximum.

O config objeto deve ter type: object e um properties mapa. Opcionalmente, você pode incluir required (uma matriz de nomes de propriedade necessá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 propriedade Config

Cada propriedade no objeto dá suporte aos config.properties seguintes campos de esquema JSON padrão:

Campo	Tipo	Description
`type`	cadeia	Tipo de dados: `string`, , `number`, `integer`, `boolean`, `array`ou `object`.
`title`	cadeia	Rótulo legível por humanos exibido na interface do usuário.
`description`	cadeia	Texto de ajuda mostrado aos usuários.
`default`	qualquer	Valor padrão para o campo.
`examples`	matriz	Valores de exemplo para o campo.
`enum`	matriz	Lista fixa de valores permitidos.
`format`	cadeia	Dica de tipo semântico. Consulte valores de formato.
`minimum`	number	Valor mínimo permitido (para `number` e `integer` tipos).
`maximum`	number	Valor máximo permitido (para `number` e `integer` tipos).
`items`	objeto	Esquema para elementos de matriz (quando `type` é `array`).
`properties`	objeto	Definições de propriedade aninhada (quando `type` é `object`).
`required`	matriz	Lista de nomes de propriedade aninhados necessários (quando `type` é `object`).

Outros campos de esquema JSON padrão, como minLength, maxLengthe patternconst também têm suporte.

Valores de formato

O format campo 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 o comportamento e a validação especializados da interface do usuário.

Formato	Description
`expression`	Referência de coluna ou expressão SQL.
`table_source`	Referência de origem da tabela.
`file_source`	Referência de origem 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ção de IA.
`is_preview`	Sinalizador de modo de visualização automática. O Lakeflow Designer define isso durante a `true` visualização do fluxo de trabalho. O nome da propriedade de configuração é arbitrário – somente a `format: is_preview` marca é importante. Use isso para ignorar efeitos colaterais, como chamadas de API externas durante a visualização.
`string[]`	Matriz de cadeia de caracteres.

Widgets de interface do usuário

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

Widget	Tipo de dados	Description
`input`	cadeia	Entrada de texto de linha única.
`textarea`	cadeia	Área de texto de várias linhas. Dá suporte à propriedade opcional `rows` .
`checkbox`	boolean	Caixa de seleção padrão.
`toggle`	boolean	Alternância 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. Dá suporte à propriedade opcional `step` .
`select`	cadeia	Lista suspensa de seleção única. Requer `optionsSource`.
`multi-select`	matriz	Menu suspenso com várias seleções. Requer `optionsSource`.
`expression`	cadeia	Seletor de coluna/expressão. Requer `port`.

`input`

Campo de entrada de texto de linha única.

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

`textarea`

Área de texto de várias linhas para conteúdo mais longo. Dá suporte a 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 boolianos.

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

`toggle`

Alterne o botão para valores boolianos.

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

`number`

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

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 em um intervalo. Use minimum e maximum na propriedade para definir o intervalo e stepx-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`

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

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

`multi-select`

Lista suspensa de várias seleções para escolher vários valores. Use type: array com items: { type: string } na propriedade. Requer um optionsSource. Consulte as fontes 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 coluna/expressão que permite que os usuários escolham uma coluna de dados de entrada ou escrevam 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 pode querer escrever uma expressão SQL personalizada.
Para parâmetros que fazem referência a 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 e multi-select widgets, você deve definir de onde as opções suspensas vêm usando optionsSource.

Opções estáticas

Uma lista fixa de valores definidos no YAML.

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

Propriedade	Tipo	Obrigatório	Description
`type`	cadeia	Yes	Deve ser `static`.
`values`	matriz	Yes	Matriz de valores de cadeia de caracteres para a lista suspensa.

Colunas de entrada

Preenche dinamicamente a lista suspensa com nomes de coluna de uma porta de entrada.

optionsSource:
  type: inputColumns
  port: input_data

Propriedade	Tipo	Obrigatório	Description
`type`	cadeia	Yes	Deve ser `inputColumns`.
`port`	cadeia	Yes	Nome da porta de entrada da qual obter nomes de coluna. Deve corresponder à `name` de uma de suas portas de entrada definidas.

`run_function`

A propriedade run_function permite inserir Python código diretamente na configuração yaml para operadores python-run-function. Isso elimina a necessidade de registrar uma função separada do Catálogo do Unity.

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	Description
`type`	cadeia	Yes	Deve ser `inline`.
`code`	cadeia	Yes	Python código-fonte. Deve definir uma `run()` função.

A run() função 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 mapeando nomes de porta de entrada para DataFrames.
spark: o SparkSession ativo.

A função deve retornar nomes de porta de saída de mapeamento de dicionário 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 várias portas de saída:

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

`environment`

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

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

Propriedade	Tipo	Obrigatório	Description
`environment_version`	cadeia	No	A versão do ambiente a ser usada. Por exemplo, `"4"`.
`dependencies`	Matriz de cadeias de caracteres	No	Lista de especificadores de dependência pip. Cada entrada segue a sintaxe pip padrão (por exemplo, `"pandas>=2.0"`).

Exemplos completos

UDF baseado em UC

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

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ção 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 raiz necessárias

schema: user-defined-operator-v0.1.0
name: nome de exibição
id: identificador exclusivo
description: o que o operador faz
config: objeto JSON Schema
type: uc-udf, uc-udtfou python-run-function
version: cadeia de caracteres de versão definida pelo autor

Propriedades raiz opcionais

ports: definições de porta de entrada e saída
run_function: código de Python embutido (somente python-run-function)
environment: Python ambiente e dependências (somente python-run-function)

Tipos de dados da propriedade Config

Widgets de interface do usuário

Fontes de opções

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

Valores de formato

Comentários

Esta página foi útil?

Last updated on 2026-06-01

Referência yaml do operador definido pelo usuário

Propriedades raiz

Portas

Exemplos de porta

Config

Campos de propriedade Config

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ção Python

Referência rápida

Propriedades raiz necessárias

Propriedades raiz opcionais

Tipos de dados da propriedade Config

Widgets de interface do usuário

Fontes de opções

Valores de formato

Comentários

Recursos adicionais

`input`

`textarea`

`checkbox`

`toggle`

`number`

`slider`

`select`

`multi-select`

`expression`

`run_function`

`environment`