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 :
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 |
|---|---|---|---|
| chaîne | Oui | Identifiant de schéma. Doit être |
| chaîne | Oui | Type d'opérateur : |
| 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. |
| 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 |
| 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 ( |
| objet | Oui | Objet de schéma JSON qui définit les champs de configuration. Consultez Configuration. |
| objet | Non | Définitions des ports d'entrée et de sortie. Voir Ports. |
| chaîne | Oui | Chaîne de version (par exemple, |
| objet | Non | Code Python intégré pour |
| objet | Non | Configuration de l’environnement Python, y compris les dépendances. Consultez |
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.
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 |
|---|---|---|---|
| chaîne | Oui | Identifiant unique pour le port. Utilisé dans les connexions et les références de configuration. |
| chaîne | Non | Libellé lisible par l'utilisateur affiché dans l'interface utilisateur. |
| chaîne | Non | Type MIME pour les données du port. Par exemple, |
| booléen | Non | Si |
| booléen | Non | Si |
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 :
ports:
input:
- name: in
title: Input Data
output:
- name: out
title: Output
UDTF avec ports d'entrée et de sortie :
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 :
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.
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 |
|---|---|---|
| chaîne | Type de données : |
| chaîne | Libellé lisible par l'utilisateur affiché dans l'interface utilisateur. |
| chaîne | Texte d'aide affiché aux utilisateurs. |
| tout | Valeur par default pour le champ. |
| tableau | Exemples de valeurs pour le champ. |
| tableau | Liste fixe de valeurs autorisées. |
| chaîne | Indication de type sémantique. Voir Formater les valeurs. |
| Nombre | Valeur minimale autorisée (pour les types |
| Nombre | Valeur maximale autorisée (pour les types |
| objet | Schéma pour les éléments de tableau (lorsque |
| objet | Définitions de propriétés imbriquées (lorsque |
| tableau | Liste des noms de propriétés imbriquées requises (lorsque |
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 |
|---|---|
| Référence de colonne ou expression SQL. |
| Référence de la table source. |
| Référence de la source du fichier. |
| Expressions de colonne. |
| Expressions de tri. |
| Expressions d'agrégation. |
| Expressions de fonctions IA. |
| Indicateur de mode aperçu automatique. Lakeflow Designer définit ceci à |
| 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 |
|---|---|---|
| chaîne | Saisie de texte sur une seule ligne. |
| chaîne | Zone de texte multiligne. Prend en charge la propriété facultative |
| booléen | Case à cocher standard. |
| booléen | Interrupteur à bascule. |
| nombre/entier | Entrée numérique avec contraintes facultatives. |
| nombre/entier | Curseur visuel pour les plages numériques. Prend en charge la propriété facultative |
| chaîne | Menu déroulant à sélection unique. Requiert |
| tableau | Liste déroulante à sélection multiple. Requiert |
| chaîne | Sélecteur de colonne/d’expression. Requiert |
input
Champ de saisie de texte à une seule ligne.
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.
message_body:
type: string
title: Message Body
x-ui:
widget: textarea
rows: 4
checkbox
Case à cocher standard pour les valeurs booléennes.
send_notification:
type: boolean
title: Send Notification
default: false
x-ui:
widget: checkbox
toggle
Bouton bascule pour les valeurs booléennes.
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.
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.
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.
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.
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.
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.
optionsSource:
type: static
values: ['option1', 'option2', 'option3']
Propriété | Type | Obligatoire | Description |
|---|---|---|---|
| chaîne | Oui | Doit être |
| 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.
optionsSource:
type: inputColumns
port: input_data
Propriété | Type | Obligatoire | Description |
|---|---|---|---|
| chaîne | Oui | Doit être |
| chaîne | Oui | Nom du port d'entrée pour obtenir les noms de colonne. Doit correspondre au |
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.
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 |
|---|---|---|---|
| chaîne | Oui | Doit être |
| chaîne | Oui | Code source Python. Il faut définir une fonction |
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:
return {"out": result_df}
Avec plusieurs ports de sortie :
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.
environment:
environment_version: '4'
dependencies:
- 'scikit-learn>=1.3'
- 'pandas>=2.0'
Propriété | Type | Obligatoire | Description |
|---|---|---|---|
| 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, |
| tableau de chaînes | Non | Liste des spécificateurs de dépendance pip. Chaque entrée suit la syntaxe pip standard (par exemple, |
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.
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.
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.0name: Nom d’affichageid: Identifiant uniquedescription: Ce que fait l'opérateur.config: objet de schéma JSONtype:uc-udf,uc-udtf, oupython-run-functionversion: Chaîne de version définie par l'auteur
Propriétés racine facultatives
ports: Définitions des ports d'entrée et de sortierun_function: Code Python en ligne (python-run-functionuniquement)environment: environnement Python et dépendances (python-run-functionuniquement)
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[]