Référence YAML des workflows

Référence pour le format YAML d'export/import des workflows, incluant les champs des nœuds, les arêtes et les différences de version.

Cette page documente le format YAML que Transformation Builder utilise pour exporter et importer des flux de travail. Utilisez cette référence lorsque vous devez partager des flux de travail entre environnements, les stocker dans un système de contrôle de version ou les intégrer à des systèmes d'exécution externes.

Le format existe en deux versions. Version 2 est le format actuel que Transformation Builder produit à l'exportation. Il organise les nœuds sous la forme d'un tableau plat en ordre topologique (cte_nodes) avec un edges tableau séparé pour les connexions. Version 1 est un format plus ancien qui utilise une nodes clé avec des références depends_on inline pour les connexions. Transformation Builder peut importer les deux versions, mais exporte toujours la version 2.

Exporter

Produit un fichier YAML au format version 2. Vous pouvez déclencher une exportation depuis le Exporter 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 transmis à un runtime externe pour exécution.

Importer

Accepte à la fois la version 2 (le format actuel) et la version 1 (un format antérieur avec des connexions basées sur depends_on). Utilisez la Importer fonction dans le Builder et sélectionnez un .yaml ou .yml fichier.

Comment l'exportation est formée

Le générateur d'export 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 source viennent en premier, suivis des nœuds de transformation dans l'ordre des dépendances, et enfin le nœud Output. Si le graphe contient un cycle, un ordre de secours (par 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 d'identifiants de nœuds prédécesseurs à partir des arêtes où target égale l'ID du nœud courant. 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, en ordre topologique. Voir structure cte_nodes ci-dessous pour les détails 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 flux de travail et des champs optionnels (viewport, schedule) dans le document final.

Clés de niveau supérieur

La racine d'un fichier YAML 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.
name	Toujours	Nom du flux de travail.
description	Toujours	Description du flux de travail. Peut être une chaîne vide.
cte_nodes	Toujours	Tableau d'enregistrements de nœuds en ordre topologique. Voir structure cte_nodes.
edges	Toujours	Tableau d'objets d'arête. Voir structure edges.
output_node_id	Lorsqu'un nœud Output existe	L'ID du nœud Output dans le flux de travail.
viewport	Lorsqu'il est défini dans le flux de travail	Position du canevas et niveau de zoom : { x, y, zoom }. Utilisé pour restaurer la mise en page visuelle à l'importation.
schedule	Lorsque la planification est activée	Plan d'exécution : { cron, timezone }. Le cron par défaut est 0 0 * * *, le fuseau horaire par défaut est UTC.

structure cte_nodes

Chaque entrée dans le cte_nodes tableau représente un nœud dans le graphe du flux de travail.

Champ	Description
id	Identifiant unique du nœud (chaîne).
type	Type de nœud. L'un des : telematics, business, filter, resample, sql, arithmetic, custom, output.
label	Nom affiché sur le canevas. Se rabat sur l'ID du nœud si non défini.
description	Description du nœud. Peut être une chaîne vide.
position	Coordonnées du canevas sous la forme { x, y }.
sources	Liste ordonnée des IDs de nœuds prédécesseurs, dérivée des arêtes du graphe. Vide pour les nœuds source.
params	Paramètres de configuration du nœud. Les champs spécifiques dépendent du type de nœud. Voir la Transformation Builder documentation pour les détails des paramètres par type de nœud.
width, height	Optionnel. Dimensions sur le canevas pour le nœud, inclus uniquement lorsqu'elles sont explicitement définies.

Nettoyage des Params. Le available_tables et available_columns champs sont supprimés de params lors de l'export. Ces champs sont remplis à l'exécution lorsque le Builder se connecte à la base de données et ne doivent pas être stockés dans le YAML.

Type SQL avec plusieurs sources. Lorsqu'un nœud de type sql a deux sources ou plus, l'export ajoute un join_spec champ à l'enregistrement. Il s'agit d'un tableau avec un élément contenant la configuration du joint :

join_spec :
  - type: "left"       # type de jointure (minuscules) : left, inner, right, full
    on_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id"

Le type la valeur est prise depuis le paramètre join_type du nœud (converti en minuscules), et on_condition est prise depuis join_condition. Pour les nœuds SQL avec deux sources, l'information de jointure apparaît dans les deux params et join_spec.

structure edges

Le edges le tableau définit les connexions entre les nœuds du graphe du flux de travail.

edges :
  - source: "node-telematics-1"
    target: "node-sql-1"
  - source: "node-business-1"
    target: "node-sql-1"

Chaque arête est un objet avec deux champs :

Champ	Description
source	L'ID du nœud d'où l'arête prend origine.
target	L'ID du nœud où l'arête se termine.

Les IDs d'arête depuis l'interface du Builder ne sont pas préservés dans l'export. À l'importation, de nouveaux IDs d'arêtes sont générés automatiquement.

Importer

Détection de version

Le Builder détermine la version du format YAML en utilisant 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 attendue.

Importation version 2

Le Builder itère sur le cte_nodes tableau dans l'ordre. Pour chaque enregistrement :

• Le id et type sont lus. Le type est converti en minuscules. Les nœuds de type python sont ignorés sans provoquer d'erreur.

• Les paramètres sont lus depuis la clé params (ou config en tant que repli). Pour les nœuds de type sql-type, si un champ join_spec est présent dans l'enregistrement, il est assigné à la configuration de joint du nœud.

• Le edges le tableau est analysé en paires source-cible, et de nouveaux IDs d'arêtes sont générés.

• Le viewport et schedule les champs sont préservés s'ils sont présents dans le YAML.

Importation version 1 (compatibilité ascendante)

Les fichiers de version 1 utilisent une clé nodes (tableau ou dictionnaire) et éventuellement un tableau edges ou des champs depends_on à l'intérieur de chaque nœud.

Le Builder traite les fichiers de version 1 comme suit :

• Les types de nœuds pris en charge sont les mêmes que pour la version 2 : telematics, business, filter, resample, sql, arithmetic, custom, output.

• Les connexions entre nœuds peuvent être définies de deux manières : un edges tableau de niveau supérieur, ou une depends_on liste à l'intérieur de chaque nœud.

• Le inputs et outputs les champs sur chaque nœud sont normalisés en objets avec { name, type } structure.

• Si les arêtes incluent des identifiants de port sourceHandle ou targetHandle , l'import ajuste les ports des nœuds en conséquence pour un affichage correct dans l'interface du Builder.

Modèle de structure YAML

Le modèle suivant montre la structure complète d'un fichier YAML version 2 avec annotations :

version: 2
name: "workflow_name"
description: "Workflow description"

cte_nodes :
  - id: "node-id-1"
    type: telematics    # telematics | business | filter | resample |
                        # sql | arithmetic | custom | output
    label: "Node display name"
    description: ""
    position: { x: 100, y: 100 }
    sources: []         # vide pour les nœuds source
    params :
      table_name: "tracking_data_core"
      time_column: "device_time"
      columns: [device_id, device_time, speed]
      filter_condition: ""
      time_window_minutes: ""

  - id: "node-id-2"
    type: sql
    label: "SQL Transform"
    description: ""
    position: { x: 400, y: 160 }
    sources: ["node-id-1", "node-id-3"]   # IDs des prédécesseurs ordonnés
    params :
      join_type: LEFT
      join_condition: "a_node_id_1.device_id = a_node_id_3.device_id"
      select_columns: ["a_node_id_1.*", "a_node_id_3.sensor_label"]
    join_spec:                             # ajouté pour les nœuds sql avec 2+ sources
      - type: "left"
        on_condition: "a_node_id_1.device_id = a_node_id_3.device_id"

    # champs optionnels par nœud :
    # width: 250
    # height: 400

edges :
  - source: "node-id-1"
    target: "node-id-2"
  - source: "node-id-3"
    target: "node-id-2"

# champs optionnels de niveau supérieur :
output_node_id: "node-output-1"           # si un nœud Output existe
viewport: { x: 0, y: 0, zoom: 1 }        # position du canevas à l'import
schedule: { cron: "0 0 * * *", timezone: "UTC" }  # si la planification est activée

Exemple

L'exemple suivant montre un flux de travail complet en version 2 qui lit des données de capteurs télématiques, les joint avec des descriptions de capteurs provenant du schéma business, applique une transformation arithmétique pour convertir le type d'une colonne, et écrit les résultats dans une table de sortie.

version: 2
name: enriched_vehicle_metrics
description: "Métriques véhicules enrichies à partir des télématiques et de la description des capteurs"

cte_nodes :
  - id: node-telematics-1
    type: telematics
    label: "Données brutes : Telematics"
    description: ""
    position: { x: 100, y: 100 }
    sources: []
    params :
      table_name: inputs
      time_column: device_time
      columns: [device_id, device_time, value]
      filter_condition: ""
      time_window_minutes: ""

  - id: node-business-1
    type: business
    label: "Données brutes : Business"
    description: ""
    position: { x: 100, y: 220 }
    sources: []
    params :
      table_name: sensor_description
      key_column: sensor_id
      columns: [sensor_id, device_id, sensor_label]

  - id: node-sql-1
    type: sql
    label: "SQL Transform"
    description: ""
    position: { x: 400, y: 160 }
    sources: [node-telematics-1, node-business-1]
    params :
      join_type: LEFT
      join_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id"
      select_columns: ["a_node_telematics_1.*", "a_node_business_1.sensor_label"]
    join_spec :
      - type: "left"
        on_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id"

  - id: node-arithmetic-1
    type: arithmetic
    label: "Arithmetic"
    description: ""
    position: { x: 700, y: 160 }
    sources: [node-sql-1]
    params :
      expressions :
        - column: value
          expression: "value::numeric"
          expression_alias: value_num

  - id: node-output-1
    type: output
    label: "Output"
    description: ""
    position: { x: 1000, y: 160 }
    sources: [node-arithmetic-1]
    params :
      table_name: enriched_vehicle_metrics
      time_column: device_time
      primary_key: [device_id, device_time]
      write_mode: append

edges :
  - { source: node-telematics-1, target: node-sql-1 }
  - { source: node-business-1, target: node-sql-1 }
  - { source: node-sql-1, target: node-arithmetic-1 }
  - { source: node-arithmetic-1, target: node-output-1 }

output_node_id: node-output-1
viewport: { x: 0, y: 0, zoom: 1 }
schedule: { cron: "0 0 * * *", timezone: "UTC" }

Ce flux de travail exécute les étapes suivantes :

1. node-telematics-1 lit device_id, device_time, et value colonnes depuis la inputs table dans le raw_telematics_data schéma.

2. node-business-1 lit sensor_id, device_id, et sensor_label depuis le sensor_description table dans le raw_business_data schéma.

3. node-sql-1 joint les deux sources sur device_id en utilisant un LEFT JOIN, en sélectionnant toutes les colonnes télématiques plus le sensor_label depuis la source business.

4. node-arithmetic-1 ajoute une colonne calculée value_num en castant la colonne texte value en un type numérique.

5. node-output-1 configure le résultat pour qu'il soit écrit dans la table enriched_vehicle_metrics avec le append mode, en utilisant device_id et device_time comme clé primaire.

L'export n'inclut pas available_tables ou available_columns dans params. Ces champs sont remplis dynamiquement lorsque le Builder se connecte à la base de données. Pour les nœuds SQL ayant deux sources, les informations de jointure apparaissent dans les deux params et join_spec.

Étapes suivantes

• Transformation Builder : Apprenez à concevoir des flux de travail en utilisant l'interface visuelle.

• Couche Transformation : Comprenez comment les données traitées sont organisées en schémas et comment les interroger.