> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/analytics/fr/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md). # Référence YAML du workflow Le format YAML du workflow capture les graphes de nœuds, les paramètres et les arêtes de Transformation Builder pour l'export, l'import et le partage entre environnements Cette page documente le format YAML que Transformation Builder utilise pour enregistrer et charger\ les configurations de workflow. Le YAML est la représentation interne du Builder d’une\ conception de workflow : il capture le graphe de nœuds, les paramètres et les arêtes afin qu’un workflow puisse être exporté,\ stocké, partagé ou réimporté dans le Builder. Lorsque vous planifiez un workflow, le Builder compile le graphe de nœuds en une seule requête SQL\ et l’enregistre comme fonction de base de données planifiée. Cette requête SQL et sa tâche pg\_cron sont\ ce qui s’exécute sur votre base de données. Le YAML n’intervient pas à l’exécution. Si vous souhaitez créer\ ou exécuter des transformations indépendamment du Builder, écrivez et planifiez directement le SQL\ sur votre base de données sans utiliser ce format. Le format comporte deux versions. **Version 2** est le format actuel que Transformation Builder produit à l’export. Il organise les nœuds sous forme de tableau plat dans l’ordre topologique (`cte_nodes`) avec un `edges` séparé pour les connexions. **Version 1** est un ancien format qui utilise une clé `nodes` avec des références intégrées `depends_on` pour les connexions. Transformation Builder peut importer les deux versions, mais exporte toujours la version 2. {% columns %} {% column %} #### **Exportation** Produit un fichier YAML au format version 2. Vous pouvez déclencher une exportation depuis le **Exportation** bouton dans la barre d’outils de Transformation Builder, ou via l’API. Le fichier exporté peut être stocké dans un dépôt, partagé avec des collègues, ou réimporté\ dans Transformation Builder dans un autre environnement. {% endcolumn %} {% column %} #### **Importer** Accepte à la fois la version 2 (le format actuel) et la version 1 (un format antérieur avec `depends_on`des connexions basées sur). Utilisez la **Importer** fonction dans le Builder et sélectionnez un `.yaml` ou `.yml` fichier. {% endcolumn %} {% endcolumns %} ## Comment l’export est formé Le générateur d’exportation construit le fichier YAML en quatre étapes : 1. **Tri topologique des nœuds.** Le graphe des nœuds et des arêtes est trié de sorte que les nœuds sources viennent en premier, suivis des nœuds de transformation dans l’ordre des dépendances, puis enfin du nœud de sortie. Si le graphe contient un cycle, un ordre de repli (selon la position dans la liste des nœuds) est utilisé. 2. **Liste des sources par nœud.** Pour chaque nœud, le générateur collecte une liste ordonnée des identifiants des nœuds prédécesseurs à partir des arêtes pour lesquelles `target` est égal à l’ID du nœud actuel. Par exemple, un nœud SQL Transform avec deux entrées aura une `sources` liste contenant exactement deux IDs dans le bon ordre. 3. **Tableau cte\_nodes.** Chaque nœud est écrit comme un enregistrement dans le `cte_nodes` tableau, dans l’ordre topologique. Voir [la structure cte\_nodes](#cte_nodes-structure) ci-dessous pour le détail des champs. 4. **Assemblage YAML de niveau supérieur.** Le générateur combine le `cte_nodes` tableau avec la liste des arêtes, les métadonnées du workflow et les champs facultatifs (viewport, schedule) dans le document final. ### Clés de niveau supérieur La racine d’un fichier YAML de version 2 contient les clés suivantes : | Clé | Présence | Description | | ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `version` | Toujours | Numéro de version du format. Toujours `2` pour les exportations actuelles. | | `nom` | Toujours | Nom du workflow. | | `description` | Toujours | Description du workflow. Peut être une chaîne vide. | | `cte_nodes` | Toujours | Tableau d’enregistrements de nœud dans l’ordre topologique. Voir [la structure cte\_nodes](#cte_nodes-structure). | | `edges` | Toujours | Tableau d’objets d’arête. Voir [structure des arêtes](#edges-structure). | | `output_nœud_id` | Lorsqu’un Nœud de sortie existe | L’ID du Nœud de sortie dans le workflow. | | `zone d’affichage` | Lorsqu'il est défini dans le flux de travail | Position du canevas et niveau de zoom : `{ x, y, zoom }`. Utilisé pour restaurer la disposition visuelle lors de l'importation. | | `planning` | Lorsque la planification est activée | Planification d'exécution : `{ cron, timezone }`. Le cron par défaut est `0 0 * * *`, le fuseau horaire par défaut est `UTC`. | ### la structure cte\_nodes Chaque entrée dans le `cte_nodes` tableau représente un Nœud dans le graphe du workflow. | Champ | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `identifiant` | Identifiant unique du Nœud (chaîne). | | `type` | Type de Nœud. Un des suivants : `télématique`, `entreprise`, `filtre`, `rééchantillonnage`, `sql`, `arithmétique`, `personnalisé`, `sortie`. | | `libellé` | Nom affiché sur le canevas. Utilise l'identifiant du Nœud par défaut s'il n'est pas défini. | | `description` | Description du Nœud. Peut être une chaîne vide. | | `position` | Coordonnées du canevas sous forme de `{ x, y }`. | | `sources` | Liste ordonnée des identifiants des Nœuds prédécesseurs, dérivée des arêtes du graphe. Vide pour les Nœuds sources. | | `paramètres` | Paramètres de configuration du Nœud. Les champs spécifiques dépendent du type de Nœud. Voir la [Constructeur de transformations](/docs/analytics/fr/iot-query/schema-overview/transformation-layer/transformation-builder.md) de la documentation pour les détails des paramètres par type de Nœud. | | `largeur`, `hauteur` | Facultatif. Dimensions de la toile pour le Nœud, incluses uniquement lorsqu’elles sont explicitement définies. | **Nettoyage des paramètres.** Le `available_tables` et `available_columns` les champs sont supprimés de `paramètres` pendant l’exportation. Ces champs sont renseignés à l’exécution lorsque le Builder se connecte à la base de données et ne doivent pas être stockés dans YAML. **Type SQL avec plusieurs sources.** Lorsqu’un Nœud de type `sql` a deux sources ou plus, l’exportation ajoute un `spécification de jointure` champ à l'enregistrement. Il s'agit d'un tableau avec un élément contenant la configuration de jointure : ```yaml spécification_de_jointure : - type: "left" # type de jointure (en minuscules) : gauche, interne, droite, complète sur_condition : "a_node_telematics_1.device_id = a_node_business_1.device_id" ``` Le `type` la valeur est prise du Nœud `type de jointure` paramètre (converti en minuscules), et `à_condition` est tiré de `condition_de_jointure`. Pour les nœuds SQL avec deux sources, les informations de jointure apparaissent dans les deux `paramètres` et `spécification de jointure`. ### structure des arêtes Le `edges` Le tableau définit les connexions entre les nœuds du graphe du workflow. ```yaml bords : - source : "Nœud-telematics-1" cible: "node-sql-1" - source : « Nœud-business-1 » cible: "node-sql-1" ``` Chaque arête est un Traceur avec deux champs : | Champ | Description | | -------- | ------------------------------------------ | | `source` | L’ID du Nœud où l’arête prend son origine. | | `target` | L’ID du Nœud où l’arête se termine. | Les ID d’arête de l’interface Builder ne sont pas conservés dans l’export. À l’importation, de nouveaux ID d’arête sont générés automatiquement. ## Importer ### Détection de version Builder détermine la version du format YAML à l’aide de la logique suivante : * Si la racine contient `version: 2` ou la clé `cte_nodes`, le fichier est traité comme **version 2**. * Sinon, **version 1** est attendu. ### Importation de la version 2 Le Builder parcourt le `cte_nodes` tableau dans l'ordre. Pour chaque enregistrement : * Le `identifiant` et `type` sont lus. Le type est converti en minuscules. Les nœuds de type `python` sont ignorés sans générer d'erreur. * Les paramètres sont lus à partir du `paramètres` clé (ou `configuration` comme solution de secours). Pour `sql`nœuds de type -, si un `spécification de jointure` champ est présent dans l'enregistrement, il est attribué à la configuration de jointure du nœud. * Le `edges` le tableau est analysé en paires source-cible, et de nouveaux ID d'arête sont générés. * Le `zone d’affichage` et `planning` les champs sont conservés s'ils sont présents dans le YAML. ### Importation de la version 1 (compatibilité ascendante) Les fichiers de la version 1 utilisent un `nodes` clé (tableau ou dictionnaire) et éventuellement un `edges` tableau ou `depends_on` champs dans chaque Nœud. Le Builder traite les fichiers de la version 1 comme suit : * Les types de Nœuds pris en charge sont les mêmes que pour la version 2 : `télématique`, `entreprise`, `filtre`, `rééchantillonnage`, `sql`, `arithmétique`, `personnalisé`, `sortie`. * Les connexions entre les Nœuds peuvent être définies de deux manières : un tableau de niveau supérieur `edges` tableau, ou une `depends_on` liste dans chaque Nœud. * Le `entrées` et `sorties` les champs de chaque Nœud sont normalisés en objets avec `{ name, type }` structure. * Si les arêtes incluent `sourceHandle` ou `targetHandle` des identifiants de port, l'importation ajuste les ports du Nœud en conséquence pour un affichage correct dans l'interface Builder. ## Modèle de structure YAML Le modèle suivant montre la structure complète d'un fichier YAML de version 2 avec annotations : {% code expandable="true" %} ```yaml version: 2 name: "workflow_name" description: "Description du workflow" cte_Nœuds: - id: "Nœud-id-1" type: télématique # télématique | métier | filtre | rééchantillonnage | # sql | arithmétique | personnalisé | sortie label: "Nom d'affichage du Nœud" description: "" position: { x: 100, y: 100 } sources: [] # vide pour les Nœuds source params: table_name: "Suivi_data_core" colonne_de_temps: "device_time" colonnes : [device_id, device_time, speed] condition_de_filtre: "" fenêtre_de_temps_minutes: "" - id : « Nœud-id-2 » type : sql label: "Transformation SQL" description: "" position: { x: 400, y: 160 } sources : ["node-id-1", "node-id-3"] # IDs de prédécesseurs ordonnés params: join_type : GAUCHE join_condition : "a_node_id_1.device_id = a_node_id_3.device_id" select_columns : ["a_nœud_id_1.*", "a_nœud_id_3.sensor_label"] join_spec: # ajouté pour les nœuds SQL avec 2+ sources - type : "gauche" sur_condition : "a_node_id_1.device_id = a_node_id_3.device_id" # champs facultatifs par Nœud : # largeur : 250 # hauteur : 400 bords : - source : « Nœud-id-1 » cible : "node-id-2" - source: "Nœud-id-3" cible : "node-id-2" # champs de niveau supérieur facultatifs : output_node_id: "node-output-1" # s’il existe un Nœud Output viewport: { x: 0, y: 0, zoom: 1 } # position du canevas à l’importation schedule: { cron: "0 0 * * *", timezone: "UTC" } # si l'Ordonnancement est activé ``` {% endcode %} ### Exemple L’exemple suivant montre un workflow complet de version 2 qui lit les Données du capteur issues de la télématique, les joint aux descriptions des capteurs du schéma métier, applique une transformation arithmétique pour convertir le type d’une colonne et écrit les résultats dans une table de sortie. {% code expandable="true" %} ```yaml version: 2 nom : enriched_vehicle_metrics description : "Métriques enrichies du véhicule issues de la télématique et de la description du capteur" cte_Nœuds: - id: nœud-telematics-1 type : télématique étiquette : "Données brutes : Télématique" description: "" position: { x: 100, y: 100 } sources : [] params: nom_table : entrées colonne_temps : heure_appareil colonnes : [identifiant_appareil, heure_appareil, valeur] condition_de_filtre: "" fenêtre_de_temps_minutes: "" - id : nœud-business-1 type : entreprise étiquette : "Données brutes : Entreprise" description: "" position : { x : 100, y : 220 } sources : [] params: nom_table : description_capteur colonne_clé : id_capteur colonnes : [id_capteur, id_appareil, étiquette_capteur] - id : Nœud-sql-1 type : sql label: "Transformation SQL" description: "" position: { x: 400, y: 160 } sources : [Nœud-telematics-1, Nœud-business-1] params: join_type : GAUCHE condition_jointure : "a_Nœud_telematics_1.id_appareil = a_Nœud_business_1.id_appareil" colonnes_sélectionnées : ["a_Nœud_telematics_1.*", "a_Nœud_business_1.étiquette_capteur"] spécification_de_jointure : - type : "gauche" sur_condition : "a_node_telematics_1.device_id = a_node_business_1.device_id" - id : Nœud-arithmetic-1 type : arithmétique étiquette : "Arithmétique" description: "" position: { x: 700, y: 160 } sources : [nœud-sql-1] params: expressions : - colonne : valeur expression : "value::numeric" alias_d'expression : valeur_num - id: sortie-du-nœud-1 type : sortie label: "Sortie" description: "" position: { x: 1000, y: 160 } sources: [Nœud-arithmetic-1] params: nom_de_table: enriched_vehicle_metrics colonne_temps : heure_appareil clé_primaire: [device_id, device_time] mode_d'écriture: ajout bords : - { source: Nœud-telematics-1, cible: Nœud-sql-1 } - { source: Nœud-business-1, cible: Nœud-sql-1 } - { source: Nœud-sql-1, cible: Nœud-arithmetic-1 } - { source: Nœud-arithmetic-1, cible: Nœud-output-1 } id_du_nœud_de_sortie: Nœud-output-1 zone d'affichage: { x: 0, y: 0, zoom: 1 } planification : { cron: "0 0 * * *", fuseau horaire : "UTC" } ``` {% endcode %} Ce flux de travail effectue les étapes suivantes : 1. **nœud-telematics-1** lit `device_id`, `device_time`, et `valeur` les colonnes de la `entrées` table dans le `raw_telematics_data` schéma. 2. **nœud-business-1** lit `sensor_id`, `device_id`, et `sensor_label` de la `sensor_description` table dans le `raw_business_data` schéma. 3. **nœud-sql-1** joint les deux sources sur `device_id` à l’aide d’un `Jointure gauche`, en sélectionnant toutes les colonnes télématiques plus la `sensor_label` de la source métier. 4. **nœud-arithmetic-1** ajoute une colonne calculée `value_num` en convertissant le texte `valeur` de colonne en type numérique. 5. **nœud-output-1** configure l’écriture du résultat dans la `enriched_vehicle_metrics` table avec `ajout` mode, en utilisant `device_id` et `device_time` comme clé primaire. {% hint style="info" %} L’exportation n’inclut pas `available_tables` ou `available_columns` dans `paramètres`. Ces champs sont renseignés dynamiquement lorsque le Builder se connecte à la base de données. Pour les nœuds SQL avec deux sources, les informations de jointure apparaissent dans les deux `paramètres` et `spécification de jointure`. {% endhint %} ## Étapes suivantes * [**Constructeur de transformations**](/docs/analytics/fr/iot-query/schema-overview/transformation-layer/transformation-builder.md): Découvrez comment concevoir des workflows à l’aide de l’interface visuelle. * [**Modèles**](/docs/analytics/fr/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md): Configurations de workflow prédéfinies que vous pouvez importer et adapter dans Transformation Builder. * [**Couche de transformation**](/docs/analytics/fr/iot-query/schema-overview/transformation-layer.md): Comprenez comment les données traitées sont organisées en schémas et comment les interroger. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://navixy.com/docs/analytics/fr/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.