Créer une macro

Une macro est un workflow avancé (DAG) réutilisable, doté d’un contrat d’entrée/sortie déclaré. Vous appelez une macro depuis un autre workflow avec une étape Macro Run ou Macro Concurrent. Chaque appel s’exécute dans son propre schéma de travail isolé : la même macro peut donc être appelée simultanément par plusieurs workflows parents, ou pour plusieurs lignes d’inducteur, sans que les exécutions n’entrent en collision.

Utilisez une macro lorsque vous avez une transformation de données répétable et paramétrée (par exemple « traiter un mois de données de ventes pour une région ») que vous souhaitez appeler depuis un workflow pilote une fois par mois, par région, ou les deux. L’appelant lie des tables et des variables aux ports d’entrée déclarés de la macro. Une fois l’exécution terminée, les tables de sortie déclarées sont recopiées vers des destinations côté appelant.

Étapes

Ouvrez le projet qui contient le workflow que vous voulez transformer en macro.
Passez à l’onglet Workflows et sélectionnez la ligne du workflow.
Dans le panneau Détails du workflow à droite, vérifiez que le Type de workflow est Avancé. S’il est standard, utilisez d’abord l’action Convertir en avancé.
Dans la section Macro du panneau Détails du workflow, cliquez sur Convertir en macro… et confirmez dans la boîte de dialogue. Le workflow passe en mode macro et un éditeur de ports apparaît.
Cliquez sur Ajouter un port pour déclarer chaque entrée ou sortie que la macro accepte ou produit. Pour chaque port :
- Nom : un identifiant court que l’appelant utilise pour se lier à ce port (par exemple month, region_sales).
- Direction : Entrée (l’appelant fournit cette valeur ou cette table) ou Sortie (la macro produit cet élément et l’appelant le récupère).
- Genre : Table pour une table de données, Scalaire pour une valeur unique (chaîne / entier / décimal / booléen / date) ou Dimension pour une référence à une dimension hiérarchique.
- Obligatoire : décochez cette option si la macro peut s’exécuter sans que ce port soit lié.
- Mémo : une courte note décrivant ce que représente ce port, affichée aux auteurs dans le formulaire de liaison côté appelant.
Cliquez sur Enregistrer les ports.

Le workflow est désormais une macro. Les auteurs qui ajoutent une étape Macro Run dans un autre workflow voient vos ports déclarés et s’y lient par leur nom.

Chaque port est un emplacement nommé et typé du contrat de la macro. Les appelants se lient aux ports par leur nom : les entrées sont copiées vers la macro, les sorties sont recopiées vers l’appelant.

Appeler une macro

Dans le workflow appelant :

Ajoutez une étape Macro : exécuter.
Dans Macro à exécuter, sélectionnez le projet et le workflow de la macro.
Liaisons d’entrée : pour chaque port d’entrée déclaré par la macro, ajoutez une liaison :
- Les ports Table prennent une table source côté appelant. Vous pouvez sélectionner un sous-ensemble de colonnes et ajouter un filtre (une clause WHERE qui référence les variables d’entrée scalaires de la macro) afin que seule la portion nécessaire soit matérialisée dans le schéma d’exécution de la macro.
- Les ports Scalaire / Dimension prennent une valeur (souvent une variable de workflow de l’appelant). Elle est définie AVANT la copie des tables en entrée, de sorte que le filtre de la table d’entrée puisse y faire référence.
Liaisons de sortie : pour chaque port de sortie produit par la macro, désignez une table de destination côté appelant (créée à la volée si elle n’existe pas encore).
Enregistrez l’étape.

Lorsque le workflow parent s’exécute et atteint l’étape Macro Run, l’exécuteur procède ainsi :

Il génère un nouveau run_id pour cet appel de la macro.
Il crée un schéma de travail propre à l’exécution (macrorun_<run_id>) dans le catalogue du projet.
Il copie les tables d’entrée liées dans le schéma de travail (projection des colonnes et filtre appliqués lors de la copie, de sorte que le filtre soit poussé vers la source).
Il définit les variables d’entrée scalaires et de dimension liées dans la surcouche de variables de la macro, limitée à l’exécution.
Il exécute les étapes de la macro dans le même processus. Chaque étape SQL de la macro lit et écrit dans le schéma de travail plutôt que dans le schéma du projet.
Il recopie les tables de sortie déclarées vers les destinations de l’appelant.
Il supprime le schéma de travail (toujours, même si une étape de la macro a échoué).

Chaque appel reçoit un nouveau run_id et son propre schéma de travail. Les étapes lisent et écrivent uniquement dans ce schéma, qui est supprimé à la fin de l’exécution, qu’elle se termine par un succès, une erreur ou un arrêt.

Comme chaque appel dispose de son propre schéma de travail, deux appels simultanés à la même macro (depuis une boucle, une diffusion en parallèle ou des workflows indépendants) n’entrent jamais en collision sur les noms de tables intermédiaires.

Exécuter une macro par ligne d’inducteur

Utilisez Macro : exécution parallèle lorsqu’une table de l’appelant doit piloter de nombreux appels indépendants de la macro.

Ajoutez une étape Macro : exécution parallèle.
Dans Inducteur, sélectionnez la table d’inducteurs côté appelant et définissez Exécutions simultanées sur le nombre maximal d’appels enfants de la macro à exécuter en même temps.
Dans Sélection des données de la table, mappez les colonnes de la table d’inducteurs dont chaque appel enfant a besoin.
Dans Filtre d’inducteur, vous pouvez restreindre les lignes d’inducteur à traiter.
Dans Macro, sélectionnez le workflow de la macro.
Dans Liaisons d’entrée, liez les valeurs des colonnes d’inducteur aux variables scalaires ou de dimension de la macro, et liez les tables côté appelant aux ports de table de la macro.
Dans Liaisons de sortie, mappez les ports de sortie de la macro vers les tables de destination côté appelant.

Chaque ligne d’inducteur sélectionnée reçoit son propre run_id et son propre schéma de travail. L’arrêt de l’étape parente arrête tous les appels enfants actifs et supprime leurs schémas d’exécution.

Un appel par ligne d’inducteur, chacun dans son propre schéma de travail : les tables intermédiaires n’entrent donc jamais en collision. Exécutions simultanées plafonne le nombre d’appels exécutés en même temps, et chaque ligne écrit sa propre table results_{region}.

Rétrograder une macro

Vous pouvez retirer l’indicateur de macro à tout moment en cliquant sur Rétrograder en avancé… dans le panneau Détails du workflow. Le workflow redevient un simple workflow avancé, et toutes les étapes Macro Run côté appelant qui le référencent échouent à l’exécution avec une erreur « not a macro ». Les ports déclarés restent enregistrés, ce qui permet de les retrouver si vous reconvertissez le workflow plus tard.

Limitations (v1)

Les macros peuvent contenir des transformations de tables, des importations et des exportations, car les lectures et écritures de tables sont isolées dans le schéma de travail de l’appel. Les importations de dimensions et les étapes qui mettent à jour des dimensions ne sont pas autorisées, car les dimensions constituent un état global au projet. Les autres étapes à effets de bord hors tables, comme les opérations sur les documents et les appels d’agent, ne sont pas compatibles avec les macros en v1.
Les macros doivent se trouver dans le même projet que l’appelant. Les macros inter-projets ne sont pas encore prises en charge.
Une étape Macro Run ne peut pas être appelée depuis une étape Run Workflow, Workflow Loop ou Run Workflow conditionnelle : ces étapes s’exécutent sans isolation et briseraient le contrat de schéma propre à chaque exécution. Utilisez plutôt une étape Macro Run dans l’appelant.

Étapes suivantes

Référence de l’étape Macro Run : la référence champ par champ de l’étape appelante.
Référence de l’étape Macro Concurrent : exécutez un appel de macro par ligne de la table d’inducteurs.
Étape Run Workflow : pour les sous-workflows qui n’ont pas besoin d’une isolation par appel.