Aller au contenu principal

Référence YAML de l'opérateur défini par l'utilisateur

Les opérateurs définis par l’utilisateur dans Lakeflow Designer sont définis en YAML. Tous les types d'opérateurs (uc-udf, uc-udtf et python-run-function) utilisent le schéma user-defined-operator-v0.1.0, qui définit les champs de configuration en utilisant le format de schéma JSON.

Pour plus d'informations sur la façon de créer des opérateurs définis par l'utilisateur, consultez Opérateurs définis par l'utilisateur dans Lakeflow Designer.

Propriétés racine

Chaque fichier YAML d'opérateur commence par un ensemble de propriétés racine qui identifient l'opérateur et définissent son comportement. L'exemple suivant montre la structure générale :

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'

Propriété

Type

Obligatoire

Description

schema

chaîne

Oui

Identifiant de schéma. Doit être user-defined-operator-v0.1.0.

type

chaîne

Oui

Type d'opérateur : uc-udf, uc-udtf, ou python-run-function.

name

chaîne

Oui

Nom d'affichage de l'opérateur. Gardez-le court pour l'adapter à l'Interface utilisateur de Lakeflow Designer. Longueur minimale de 1 caractère.

id

chaîne

Oui

Identifiant unique pour le type d'opérateur. Longueur minimale de 1 caractère. Envisagez d'utiliser des espaces de noms (tels que finance. ou ml.) pour catégoriser les opérateurs.

description

chaîne

Oui

Description détaillée de ce que fait l'opérateur. Affiché aux utilisateurs dans l'interface utilisateur. Utilisez la syntaxe YAML multiligne (>) pour des descriptions plus longues.

config

objet

Oui

Objet de schéma JSON qui définit les champs de configuration. Consultez Configuration.

ports

objet

Non

Définitions des ports d'entrée et de sortie. Voir Ports.

version

chaîne

Oui

Chaîne de version (par exemple, "1.0.0"). Utilisez ceci pour suivre vos propres versions d'opérateurs.

run_function

objet

Non

Code Python intégré pour python-run-function opérateurs. Voir run_function.

environment

objet

Non

Configuration de l’environnement Python, y compris les dépendances. Consultez environment.

Propriété

Type

Obligatoire

Description

schema

chaîne

Oui

Identifiant de schéma. Doit être user-defined-operator-v0.1.0.

type

chaîne

Oui

Type d'opérateur : uc-udf, uc-udtf, ou python-run-function.

name

chaîne

Oui

Nom d'affichage de l'opérateur. Gardez-le court pour l'adapter à l'Interface utilisateur de Lakeflow Designer. Longueur minimale de 1 caractère.

id

chaîne

Oui

Identifiant unique pour le type d'opérateur. Longueur minimale de 1 caractère. Envisagez d'utiliser des espaces de noms (tels que finance. ou ml.) pour catégoriser les opérateurs.

description

chaîne

Oui

Description détaillée de ce que fait l'opérateur. Affiché aux utilisateurs dans l'interface utilisateur. Utilisez la syntaxe YAML multiligne (>) pour des descriptions plus longues.

config

objet

Oui

Objet de schéma JSON qui définit les champs de configuration. Consultez Configuration.

ports

objet

Non

Définitions des ports d'entrée et de sortie. Voir Ports.

version

chaîne

Oui

Chaîne de version (par exemple, "1.0.0"). Utilisez ceci pour suivre vos propres versions d'opérateurs.

run_function

objet

Non

Code Python intégré pour python-run-function opérateurs. Voir run_function.

environment

objet

Non

Configuration de l’environnement Python, y compris les dépendances. Consultez environment.

Ports

Les ports définissent la manière dont votre opérateur se connecte à d’autres opérateurs dans le pipeline. L’objet ports contient les tableaux input et output.

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

Propriété

Type

Obligatoire

Description

name

chaîne

Oui

Identifiant unique pour le port. Utilisé dans les connexions et les références de configuration.

title

chaîne

Non

Libellé lisible par l'utilisateur affiché dans l'interface utilisateur.

mime

chaîne

Non

Type MIME pour les données du port. Par exemple, application/vnd.databricks.dataframe.

allowMultiple

booléen

Non

Si true, le port accepte plusieurs connexions entrantes. Par défaut, false, où le port accepte une seule connexion et le raccordement d'une nouvelle source remplace celle existante.

required

booléen

Non

Si false, le port est facultatif. Default: true.

Propriété

Type

Obligatoire

Description

name

chaîne

Oui

Identifiant unique pour le port. Utilisé dans les connexions et les références de configuration.

title

chaîne

Non

Libellé lisible par l'utilisateur affiché dans l'interface utilisateur.

mime

chaîne

Non

Type MIME pour les données du port. Par exemple, application/vnd.databricks.dataframe.

allowMultiple

booléen

Non

Si true, le port accepte plusieurs connexions entrantes. Par défaut, false, où le port accepte une seule connexion et le raccordement d'une nouvelle source remplace celle existante.

required

booléen

Non

Si false, le port est facultatif. Default: true.

Seules les propriétés de port documentées sont acceptées. Les clés inconnues (telles que le champ hérité label) sont rejetées par la validation du schéma.

Exemples de ports

UDF avec des ports d'entrée et de sortie :

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

UDTF avec ports d'entrée et de sortie :

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

fonction d'exécution Python avec plusieurs entrées et un port facultatif :

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

Configuration

Le champ config est un objet de schéma JSON. Vous définissez chaque champ de configuration comme une propriété au sein du schéma. Ce format vous donne accès aux fonctionnalités de validation de schéma JSON standard comme enum, minimum, maximum et examples.

L'objet config doit avoir type: object et un mappage properties. Vous pouvez éventuellement inclure required (un tableau de noms de propriétés requis) et 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

Champs de propriété de configuration

Chaque propriété de l’objet config.properties prend en charge les champs de schéma JSON standard suivants :

Champ

Type

Description

type

chaîne

Type de données : string, number, integer, boolean, array, ou object.

title

chaîne

Libellé lisible par l'utilisateur affiché dans l'interface utilisateur.

description

chaîne

Texte d'aide affiché aux utilisateurs.

default

tout

Valeur par default pour le champ.

examples

tableau

Exemples de valeurs pour le champ.

enum

tableau

Liste fixe de valeurs autorisées.

format

chaîne

Indication de type sémantique. Voir Formater les valeurs.

minimum

Nombre

Valeur minimale autorisée (pour les types number et integer).

maximum

Nombre

Valeur maximale autorisée (pour les types number et integer).

items

objet

Schéma pour les éléments de tableau (lorsque type est array).

properties

objet

Définitions de propriétés imbriquées (lorsque type est object).

required

tableau

Liste des noms de propriétés imbriquées requises (lorsque type est object).

Champ

Type

Description

type

chaîne

Type de données : string, number, integer, boolean, array, ou object.

title

chaîne

Libellé lisible par l'utilisateur affiché dans l'interface utilisateur.

description

chaîne

Texte d'aide affiché aux utilisateurs.

default

tout

Valeur par default pour le champ.

examples

tableau

Exemples de valeurs pour le champ.

enum

tableau

Liste fixe de valeurs autorisées.

format

chaîne

Indication de type sémantique. Voir Formater les valeurs.

minimum

Nombre

Valeur minimale autorisée (pour les types number et integer).

maximum

Nombre

Valeur maximale autorisée (pour les types number et integer).

items

objet

Schéma pour les éléments de tableau (lorsque type est array).

properties

objet

Définitions de propriétés imbriquées (lorsque type est object).

required

tableau

Liste des noms de propriétés imbriquées requises (lorsque type est object).

D'autres champs JSON Schema standard tels que minLength, maxLength, pattern et const sont également pris en charge.

Formater les valeurs

Le champ format d'une propriété de configuration fournit une indication de type sémantique qui indique à Lakeflow Designer comment interpréter la valeur. Ces indications activent un comportement d'interface utilisateur et une validation spécialisés.

Format

Description

expression

Référence de colonne ou expression SQL.

table_source

Référence de la table source.

file_source

Référence de la source du fichier.

column_expressions

Expressions de colonne.

sort_expressions

Expressions de tri.

aggregation_expressions

Expressions d'agrégation.

ai_function_expressions

Expressions de fonctions IA.

is_preview

Indicateur de mode aperçu automatique. Lakeflow Designer définit ceci à true pendant l'aperçu du workflow. Le nom de la propriété de configuration est arbitraire ; seule la balise format: is_preview compte. Utilisez ceci pour ignorer les effets secondaires comme les appels d'API externes pendant l'aperçu.

string[]

Tableau de chaînes.

Format

Description

expression

Référence de colonne ou expression SQL.

table_source

Référence de la table source.

file_source

Référence de la source du fichier.

column_expressions

Expressions de colonne.

sort_expressions

Expressions de tri.

aggregation_expressions

Expressions d'agrégation.

ai_function_expressions

Expressions de fonctions IA.

is_preview

Indicateur de mode aperçu automatique. Lakeflow Designer définit ceci à true pendant l'aperçu du workflow. Le nom de la propriété de configuration est arbitraire ; seule la balise format: is_preview compte. Utilisez ceci pour ignorer les effets secondaires comme les appels d'API externes pendant l'aperçu.

string[]

Tableau de chaînes.

Widgets d'interface utilisateur

Les widgets personnalisent la manière dont un champ de configuration s'affiche dans l'interface de Lakeflow Designer. Définissez des widgets dans la propriété x-ui de chaque propriété de configuration. Si vous omettez le widget, Lakeflow Designer utilise un widget default basé sur le type de données.

Widget

Type de données

Description

input

chaîne

Saisie de texte sur une seule ligne.

textarea

chaîne

Zone de texte multiligne. Prend en charge la propriété facultative rows.

checkbox

booléen

Case à cocher standard.

toggle

booléen

Interrupteur à bascule.

number

nombre/entier

Entrée numérique avec contraintes facultatives.

slider

nombre/entier

Curseur visuel pour les plages numériques. Prend en charge la propriété facultative step.

select

chaîne

Menu déroulant à sélection unique. Requiert optionsSource.

multi-select

tableau

Liste déroulante à sélection multiple. Requiert optionsSource.

expression

chaîne

Sélecteur de colonne/d’expression. Requiert port.

Widget

Type de données

Description

input

chaîne

Saisie de texte sur une seule ligne.

textarea

chaîne

Zone de texte multiligne. Prend en charge la propriété facultative rows.

checkbox

booléen

Case à cocher standard.

toggle

booléen

Interrupteur à bascule.

number

nombre/entier

Entrée numérique avec contraintes facultatives.

slider

nombre/entier

Curseur visuel pour les plages numériques. Prend en charge la propriété facultative step.

select

chaîne

Menu déroulant à sélection unique. Requiert optionsSource.

multi-select

tableau

Liste déroulante à sélection multiple. Requiert optionsSource.

expression

chaîne

Sélecteur de colonne/d’expression. Requiert port.

input

Champ de saisie de texte à une seule ligne.

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

textarea

Zone de texte multiligne pour un contenu plus long. Prend en charge une propriété rows facultative pour contrôler la hauteur.

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

checkbox

Case à cocher standard pour les valeurs booléennes.

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

toggle

Bouton bascule pour les valeurs booléennes.

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

number

Champ de saisie numérique. Utilisez minimum et maximum sur la propriété elle-même pour contraindre la plage.

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

slider

Curseur visuel pour sélectionner des valeurs numériques dans une plage. Utilisez minimum et maximum sur la propriété pour définir la plage, et step dans x-ui pour contrôler l'incrément.

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

select

Menu déroulant à sélection unique. Nécessite un optionsSource pour définir l'origine des valeurs du menu déroulant. Consultez Options sources.

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

multi-select

Liste déroulante à sélection multiple pour choisir plusieurs valeurs. Utilisez type: array avec items: { type: string } sur la propriété. Nécessite optionsSource. Voir Options sources.

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

expression

Sélecteur de colonne/d'expression permettant aux utilisateurs de choisir une colonne parmi les données d'entrée ou d'écrire une expression SQL personnalisée. Définissez format: expression sur la propriété et spécifiez l'entrée port dans x-ui. Ceci est utile :

  • Lorsque l'utilisateur doit sélectionner une colonne à partir des données d'entrée.
  • Lorsque l'utilisateur pourrait vouloir écrire une expression SQL personnalisée.
  • Pour les paramètres qui font référence à des données dynamiques dans le pipeline.
YAML
amount:
type: string
title: Amount
format: expression
x-ui:
widget: expression
port: input_data

Options sources

Pour les widgets select et multi-select, vous devez définir l'origine des options de la liste déroulante à l'aide de optionsSource. Il existe deux sources : static (une liste fixe définie dans le YAML) et inputColumns (noms de colonnes d'un port d'entrée).

Options statiques

Une liste fixe de valeurs définie dans le YAML.

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

Propriété

Type

Obligatoire

Description

type

chaîne

Oui

Doit être static.

values

tableau

Oui

Tableau de chaînes de valeurs pour la liste déroulante.

Propriété

Type

Obligatoire

Description

type

chaîne

Oui

Doit être static.

values

tableau

Oui

Tableau de chaînes de valeurs pour la liste déroulante.

Colonnes d'entrée

Remplit dynamiquement la liste déroulante avec les noms de colonne d’un port d’entrée.

YAML
optionsSource:
type: inputColumns
port: input_data

Propriété

Type

Obligatoire

Description

type

chaîne

Oui

Doit être inputColumns.

port

chaîne

Oui

Nom du port d'entrée pour obtenir les noms de colonne. Doit correspondre au name de l'un de vos ports d'entrée définis.

Propriété

Type

Obligatoire

Description

type

chaîne

Oui

Doit être inputColumns.

port

chaîne

Oui

Nom du port d'entrée pour obtenir les noms de colonne. Doit correspondre au name de l'un de vos ports d'entrée définis.

run_function

La propriété run_function vous permet d'intégrer du code Python directement dans la configuration YAML pour les opérateurs python-run-function. Cela élimine la nécessité d'enregistrer une fonction Unity Catalog distincte.

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

Propriété

Type

Obligatoire

Description

type

chaîne

Oui

Doit être inline.

code

chaîne

Oui

Code source Python. Il faut définir une fonction run().

Propriété

Type

Obligatoire

Description

type

chaîne

Oui

Doit être inline.

code

chaîne

Oui

Code source Python. Il faut définir une fonction run().

La fonction run() reçoit trois arguments :

  • config : un dictionnaire de valeurs de configuration définies par l'utilisateur dans l'interface utilisateur.
  • inputs : Un dictionnaire qui associe les noms des ports d'entrée aux DataFrames.
  • spark : La SparkSession active.

La fonction doit renvoyer un dictionnaire mappant les noms de ports de sortie aux DataFrames. Les clés doivent correspondre exactement au champ name de chaque port de sortie défini dans ports.output. Par exemple, avec un port de sortie nommé out:

Python
return {"out": result_df}

Avec plusieurs ports de sortie :

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

environment

La propriété environment spécifie l'environnement Python pour les opérateurs python-run-function. Utilisez-le pour pin la version de l'environnement et déclarer les dépendances pip.

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

Propriété

Type

Obligatoire

Description

environment_version

chaîne

Non

La version de l'environnement serverless, qui définit l'exécution Python de base et les bibliothèques préinstallées. Pour les versions disponibles, voir Versions de l'environnement Serverless. Par exemple, "4".

dependencies

tableau de chaînes

Non

Liste des spécificateurs de dépendance pip. Chaque entrée suit la syntaxe pip standard (par exemple, "pandas>=2.0").

Propriété

Type

Obligatoire

Description

environment_version

chaîne

Non

La version de l'environnement serverless, qui définit l'exécution Python de base et les bibliothèques préinstallées. Pour les versions disponibles, voir Versions de l'environnement Serverless. Par exemple, "4".

dependencies

tableau de chaînes

Non

Liste des spécificateurs de dépendance pip. Chaque entrée suit la syntaxe pip standard (par exemple, "pandas>=2.0").

Exemples complets

UDF basée sur UC

Cet exemple définit un opérateur UDF basé sur Unity Catalog qui calcule les intérêts composés.

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

Opérateur de fonction d'exécution Python

Cet exemple définit un opérateur python-run-function qui segmente les clients à l'aide du 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'

Référence rapide

Propriétés racine requises

  • schema: user-defined-operator-v0.1.0
  • name: Nom d’affichage
  • id: Identifiant unique
  • description: Ce que fait l'opérateur.
  • config: objet de schéma JSON
  • type: uc-udf, uc-udtf, ou python-run-function
  • version: Chaîne de version définie par l'auteur

Propriétés racine facultatives

  • ports: Définitions des ports d'entrée et de sortie
  • run_function: Code Python en ligne (python-run-function uniquement)
  • environment: environnement Python et dépendances (python-run-function uniquement)

Types de données des propriétés de Config

string | boolean | number | integer | array | object

Widgets d'interface utilisateur

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

Options sources

static (valeurs fixes) | inputColumns (du port d'entrée)

Formater les valeurs

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