Réutiliser votre travail : variables, macros et UDF

~30 minutes · une variable, une macro, une transformation définie par l’utilisateur

Le premier workflow que l’on crée fixe généralement tout en dur : une région, un mois, un nom de table. Il fonctionne une fois. Ce tutoriel vous fait passer du statut d’utilisateur à celui d’utilisateur avancé : vous prenez ce pipeline ponctuel et vous le transformez en un actif que vous pouvez appliquer à n’importe quelle région, appeler de n’importe où et étendre avec votre propre code Python.

Trois outils font le travail, et ils s’empilent :

Outil	Ce qu’il supprime	À utiliser quand
Variable de workflow	Les valeurs codées en dur dispersées dans les étapes	La même valeur (un mois, une région, un seuil) apparaît dans plusieurs étapes
Macro	Les séquences d’étapes copiées-collées	Une séquence paramétrée s’exécute de nombreuses fois : par région, par mois, par ligne d’inducteur
User Defined Transform (UDF)	Le vide que les étapes standard ne peuvent pas combler	Aucune transformation standard (ni combinaison) ne fait ce dont vous avez besoin, et vous pouvez l’écrire en Python

Vous n’avez pas besoin des trois sur chaque workflow. Ajoutez chacun au moment où la difficulté qu’il supprime apparaît réellement.

Chaque outil couvre un périmètre plus large que le précédent. Ajoutez-les quand le besoin apparaît, pas avant.

Prérequis

• Un espace de travail PlaidCloud et un projet contenant un workflow que vous avez déjà créé, idéalement celui de Charger, transformer et publier des données.
• Une certaine aisance pour ajouter et exécuter des étapes de workflow. Si c’est nouveau pour vous, commencez par le guide des workflows.

Étape 1 : paramétrer avec une variable de workflow

Une variable est une valeur nommée que vos étapes lisent à la place d’un littéral. Modifiez-la à un seul endroit et toutes les étapes qui la référencent suivent. PlaidCloud gère les variables à deux niveaux : les variables de projet sont partagées par tous les workflows du projet ; les variables de workflow appartiennent à un seul workflow et constituent le moyen naturel de transmettre des informations entre ses étapes.

1. Dans la hiérarchie Workflows, cliquez sur l’icône variables pour ouvrir la table des variables.
2. Ajoutez une variable : donnez-lui un nom explicite comme target_region et définissez sa valeur actuelle (par exemple East).
3. Dans une étape qui fixe actuellement cette valeur en dur, référencez la variable au lieu de saisir le littéral.
4. Exécutez l’étape. Modifiez ensuite la valeur de la variable dans la table et exécutez de nouveau : la même étape traite maintenant un autre sous-ensemble, sans aucune modification de l’étape elle-même.

La table des variables permet aussi de consulter les valeurs actuelles, de les modifier et de supprimer les variables dont vous n’avez plus besoin.

Niveau projet ou niveau workflow. Placez une valeur au niveau du projet lorsque plusieurs workflows ont besoin du même paramètre, et au niveau du workflow lorsqu’elle est propre aux étapes d’un seul workflow. En cas de doute, commencez par le niveau le plus étroit, une variable de workflow, et ne la promouvez au projet que lorsqu’un deuxième workflow en a besoin.

Pour une vue d’ensemble de l’emplacement des variables et de leur gestion, consultez Gérer les variables de workflow.

Étape 2 : regrouper une séquence dans une macro

Une variable paramètre une valeur. Une macro paramètre toute une séquence d’étapes. C’est un workflow avancé (DAG) réutilisable, doté d’un contrat d’entrée/sortie déclaré (par exemple « traiter un mois de ventes pour une région »), que vous appelez depuis un autre workflow une fois par mois, par région, ou les deux. Chaque appel s’exécute dans son propre schéma de travail isolé : la même macro peut donc s’exécuter de nombreuses fois simultanément sans que les exécutions entrent en collision.

Les macros sont réservées aux workflows avancés. Convertissez d’abord le workflow en workflow avancé. Les étapes d’une macro doivent être compatibles avec les macros : les transformations de table, les importations, les exportations, les étapes de variables limitées à l’exécution et les appels de macro imbriqués sont acceptés ; les importations de dimensions et les étapes qui mettent à jour des dimensions sont rejetées, car les dimensions constituent un état global du projet.

Transformer un workflow en macro

1. Ouvrez le projet puis, dans l’onglet Workflows, sélectionnez le workflow que vous voulez réutiliser.
2. Dans le panneau Détails du workflow, vérifiez que Type de workflow est défini sur Avancé ; utilisez d’abord Convertir en avancé s’il est Standard.
3. Dans la section Macro, cliquez sur Convertir en macro… et confirmez. Un éditeur de ports apparaît.
4. Cliquez sur Ajouter un port pour chaque entrée ou sortie que la macro accepte ou produit. Pour chaque port, définissez :
   • Nom : l’identifiant auquel l’appelant se lie (par exemple month, region_sales).
   • Direction : Entrée (fournie par l’appelant) ou Sortie (produite par la macro).
   • Genre : Table, Scalaire (une valeur unique de type chaîne, entier, flottant, booléen ou date) ou Dimension.
   • Obligatoire : décochez cette option si la macro peut s’exécuter sans que ce port soit lié.
   • Mémo : une courte note affichée aux auteurs dans le formulaire de liaison côté appelant.
5. Cliquez sur Enregistrer les ports.

L’appeler depuis un autre workflow

1. Dans le workflow appelant, ajoutez une étape Macro : exécuter.
2. Dans Macro à exécuter, sélectionnez le projet et le workflow de la macro.
3. Input Port Bindings : liez chaque port d’entrée. Les ports scalaires et de dimension prennent souvent une variable de workflow côté appelant (celle de l’étape 1) ; les ports de table prennent une table source, avec éventuellement une projection de colonnes et un filtre.
4. Output Port Bindings : faites pointer chaque port de sortie vers une table de destination côté appelant.
5. Enregistrez l’étape et exécutez le workflow.

Pour exécuter la macro une fois par ligne d’une table d’inducteurs (une région par ligne, par exemple), utilisez plutôt une étape Macro : exécution parallèle et limitez le nombre d’exécutions simultanées avec Exécutions simultanées. Chaque ligne obtient son propre schéma de travail et sa propre destination.

Le pas-à-pas complet, champ par champ, y compris le cycle de vie de l’isolation des exécutions, figure dans Créer une macro.

Étape 3 : ajouter une logique sur mesure avec une User Defined Transform

Les transformations standard couvrent presque tout et sont constamment optimisées pour les performances : utilisez-les en premier. Mais lorsqu’aucune étape standard (seule ou combinée) ne fait ce dont vous avez besoin, une User Defined Transform (UDF) vous permet de passer en Python standard, avec l’API PlaidCloud complète et des paquets comme Pandas, NumPy et SciPy à disposition.

Vous pouvez écrire une UDF de deux façons : l’écrire et la maintenir directement dans PlaidCloud, ou pointer vers un fichier d’un dépôt Git connecté (qui prend en compte les modifications automatiquement à l’exécution suivante et gère les branches et les étiquettes pour le contrôle des versions).

Écrire la fonction

1. Ouvrez le workflow, sélectionnez l’onglet Défini par l’utilisateur et cliquez sur Ajouter une fonction définie par l’utilisateur.

2. Donnez un ID à l’UDF, puis cliquez sur l’icône Edit function logic pour ouvrir l’éditeur.

3. Écrivez votre logique. Une UDF minimale se connecte, lit une source, transforme avec Pandas et enregistre une cible :

   from plaidcloud.utilities.connect import PlaidConnection
   from plaidcloud.utilities import frame_manager as fm
   
   conn = PlaidConnection()
   
   # Read a table configured as a source on the step
   source = conn.udf.source_by_name('sales_clean')
   df = conn.get_data(source)
   
   # Custom logic the standard steps don't cover
   df['margin_band'] = df['margin'].apply(
       lambda m: 'high' if m > 0.4 else 'low'
   )
   
   # Write to a table configured as a target on the step.
   # Sources are read by their configured name; fm.save writes to a table PATH (leading slash).
   fm.save(df, name='/output/sales_scored', append=False)

L’ajouter au workflow

1. Dans l’onglet Analyze Steps, ajoutez une étape User Defined Transform là où vous en avez besoin, exactement comme une transformation standard.
2. Dans la configuration de l’étape, choisissez le type : Analyze UDF (une fonction stockée) ou Dépôt de code source externe (Git, puis choisissez Connection, Branch et Chemin du fichier).
3. Définissez les tables sources et cibles que l’UDF utilise. Vous pouvez accéder directement aux tables dans le code, mais les déclarer ici enregistre les dépendances et les rend disponibles via conn.udf.source_by_name(...) / target_by_name(...).
4. Vous pouvez aussi ajouter des valeurs propres à l’étape sous Autres variables, lisibles avec conn.udf.variable_by_name(...).

Déclarez vos tables dans la configuration, pas seulement dans le code. Une UDF qui lit directement une table s’exécute quand même, mais PlaidCloud ne saura pas que cette table est une dépendance : la traçabilité et l’ordonnancement des exécutions ne peuvent donc pas en tenir compte. Lister les sources et les cibles dans la configuration de l’étape garde le graphe de dépendances fidèle.

Les variables de projet et de workflow de l’étape 1 sont également accessibles dans l’UDF, via conn.analyze.workflow.variable_values(...) et conn.analyze.project.variable_values(...) : le même paramètre pilote ainsi vos étapes standard et votre code sur mesure. Des exemples complets d’API figurent dans la référence de l’étape User Defined Transform.

C’est le passage d’utilisateur à utilisateur avancé. Vous avez transformé un pipeline ponctuel en actifs réutilisables : une valeur que vous pouvez rediriger avec une variable, une séquence entière que vous pouvez appeler n’importe où sous forme de macro, et du Python sur mesure qui atteint ce que les étapes standard ne peuvent pas atteindre.

Pour aller plus loin

• Gérer les variables de workflow : niveau projet ou workflow, et table des variables.
• Créer une macro : ports, isolation des exécutions et pilotage d’une macro par ligne.
• Référence de l’étape User Defined Transform : toute la surface d’API pour le Python sur mesure.
• Guide des workflows : conditions, boucles et tout ce que propose la couche d’orchestration.
• Transformer des données avec SQL : le tutoriel jumeau, pour quand la réponse est une requête et non du code.