Définir des dépendances

Ce document explique comment définir la relation entre les objets de votre workflow dans Dataform en déclarant des dépendances.

Vous pouvez définir une relation de dépendance entre les objets d'un workflow. Dans une relation de dépendance, l'exécution d'un objet dépendant dépend de l'exécution de l'objet de dépendance. Cela signifie que Dataform exécute la dépendance après le parent. Pour définir la relation, vous devez déclarer les dépendances dans le fichier de définition SQLX de l'objet dépendant.

Les déclarations de dépendances constituent un arbre de dépendances de votre workflow qui détermine l'ordre dans lequel Dataform exécute les actions de votre workflow.

Vous pouvez définir la relation de dépendance entre les actions de workflow suivantes :

Déclarations sur les sources de données

Déclarations de sources de données BigQuery qui vous permettent de référencer ces sources de données dans les définitions de tables Dataform et les opérations SQL. Vous pouvez définir une déclaration de source de données comme dépendance, mais pas comme dépendant.

Tables

Tables que vous créez dans Dataform en fonction des sources de données déclarées ou d'autres tables de votre workflow. Dataform est compatible avec les types de tables suivants : table, table incrémentielle, vue et vue matérialisée. Vous pouvez définir une table comme dépendance et comme table dépendante.

Opérations SQL personnalisées

Instructions SQL

que Dataform exécute dans BigQuery telles quelles, sans modification. Vous pouvez définir une opération SQL personnalisée définie dans un fichier type: operations comme dépendance et comme élément dépendant. Pour déclarer une opération SQL personnalisée comme dépendance dans la fonction ref, vous devez définir la propriété hasOutput sur true dans le fichier de définition SQLX de l'opération SQL personnalisée.

Assertions

Requêtes de test de la qualité des données que vous pouvez utiliser pour tester les données des tables. Dataform exécute des assertions chaque fois qu'il met à jour votre workflow. Il vous alerte en cas d'échec. Vous pouvez définir une assertion définie dans un fichier type: assertion comme dépendance et comme élément dépendant en déclarant des dépendances dans le bloc config.

Vous pouvez définir la relation de dépendance de différentes manières :

• Déclarez une dépendance en utilisant la fonction ref du cœur Dataform pour référencer la dépendance dans une instruction SELECT.
• Déclarez une liste de dépendances dans le bloc config d'un fichier de définition SQLX.

Avant de commencer

1. Créez et initialisez un espace de travail de développement dans votre dépôt.
2. Facultatif : Déclarez une source de données.
3. Créez au moins deux actions de workflow : tables, assertions, déclarations de sources de données ou opérations.

Rôles requis

Pour obtenir les autorisations nécessaires pour déclarer des dépendances pour les tables, les assertions, les déclarations de sources de données et les opérations SQL personnalisées, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Dataform (roles/dataform.editor) sur les espaces de travail. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Déclarer une dépendance en tant qu'argument de la fonction ref

Pour référencer et déclarer automatiquement une dépendance dans une instruction SELECT, ajoutez la dépendance en tant qu'argument de la fonction ref.

La fonction ref est une fonction Dataform Core intégrée qui vous permet de référencer et de dépendre automatiquement de n'importe quelle table, déclaration de source de données ou opération SQL personnalisée avec la propriété hasOutput définie sur true dans votre workflow.

Pour en savoir plus sur la fonction ref, consultez la documentation de référence sur les méthodes de contexte Dataform Core.

Pour en savoir plus sur l'utilisation de la fonction ref dans une définition de table, consultez À propos des définitions de table.

L'exemple de code suivant montre la déclaration de source de données source_data ajoutée en tant qu'argument de la fonction ref dans le fichier de définition incremental_table.sqlx SQLX d'une table incrémentielle :

// filename is incremental_table.sqlx

config { type: "incremental" }

SELECT * FROM ${ref("source_data")}

Dans l'exemple de code précédent, source_data est automatiquement déclaré comme dépendance de incremental_table.

L'exemple de code suivant montre le fichier SQLX de définition de table some_table ajouté en tant qu'argument de la fonction ref dans le fichier de définition SQLX custom_assertion.sqlx d'une assertion :

// filename is custom_assertion.sqlx

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("some_table")}
WHERE
  a is null
  or b is null
  or c is null

Dans l'exemple de code précédent, some_table est automatiquement déclaré comme dépendance de custom_assertion. Lors de l'exécution, Dataform exécute d'abord some_table, puis custom_assertion une fois que some_table est créé.

Déclarer des dépendances dans le bloc config

Pour déclarer des dépendances qui ne sont pas référencées dans la définition d'instruction SQL du dépendant, mais qui doivent être exécutées avant l'opération de table, d'assertion ou SQL personnalisée, procédez comme suit :

1. Dans votre espace de travail de développement, dans le volet Fichiers, développez le répertoire definitions/.
2. Sélectionnez le fichier SQLX de table, d'assertion ou d'opération SQL personnalisée que vous souhaitez modifier.

3. Dans le bloc config du fichier, saisissez l'extrait de code suivant :

   dependencies: [ "DEPENDENCY", ]
   

   Remplacez DEPENDENCY par la chaîne cible, par exemple le nom de fichier de l'action que vous souhaitez ajouter en tant que dépendance. Vous pouvez saisir plusieurs cibles, séparées par des virgules.

4. Facultatif : Cliquez sur Format.

L'exemple de code suivant montre la table some_table et l'assertion some_assertion ajoutées en tant que dépendances au bloc config d'un fichier de définition de table :

config { dependencies: [ "some_table", "some_assertion" ] }

Définir des assertions comme dépendances

Lorsque l'action de workflow B dépend de l'action de workflow A, qui comporte des assertions, l'échec des assertions de l'action A n'empêche pas Dataform d'exécuter l'action B. Pour exécuter l'action B uniquement si les assertions de l'action A sont réussies, vous devez définir les assertions de l'action A comme dépendances de l'action B.

Vous pouvez définir des assertions comme dépendances d'une action sélectionnée de différentes manières :

Définir les assertions sélectionnées comme dépendances

Vous pouvez définir manuellement certaines assertions comme dépendances en les ajoutant à la ligne dependencies: [ "" ] dans le bloc config de l'action modifiée.

Par exemple, si l'action B dépend de l'action A et que vous souhaitez que l'action B ne dépende que des assertions sélectionnées de l'action A, vous pouvez ajouter ces assertions sélectionnées au bloc config de l'action B.

Vous pouvez définir manuellement des assertions sélectionnées comme dépendances pour tous les types d'actions, à l'exception des déclarations de sources de données.

Définir les assertions d'une action de dépendance sélectionnée comme dépendances

Vous pouvez définir le paramètre includeDependentAssertions pour définir automatiquement toutes les assertions directes d'une action de workflow de dépendance sélectionnée comme dépendances de l'action modifiée. Dataform ajoute ces assertions en tant que dépendances lors de chaque compilation de l'action pour vérifier que les dépendances sont à jour si les assertions de l'action de dépendance changent.

Par exemple, si l'action C dépend des actions A et B, mais que vous ne souhaitez que l'action C dépende des assertions de l'action A, vous pouvez modifier l'action C et définir le paramètre includeDependentAssertions pour définir automatiquement toutes les assertions de l'action A comme dépendances de l'action C.

Vous pouvez définir le paramètre includeDependentAssertions pour les actions des types suivants :

• table
• view
• operations

Définissez les assertions de toutes les actions de dépendance comme dépendances.

Vous pouvez définir le paramètre dependOnDependencyAssertions pour définir automatiquement toutes les assertions directes de toutes les actions de dépendance de l'action modifiée comme dépendances supplémentaires de l'action modifiée. Dataform ajoute ces assertions en tant que dépendances lors de chaque compilation de l'action pour vérifier que les dépendances sont à jour si les assertions de l'action de dépendance changent.

Par exemple, si l'action C dépend des actions A et B, vous pouvez modifier l'action C et définir le paramètre dependOnDependencyAssertions pour définir automatiquement toutes les assertions des actions A et B comme dépendances de l'action C.

Vous pouvez définir le paramètre dependOnDependencyAssertions pour les actions des types suivants :

• table
• view
• operations

Lorsque vous définissez le paramètre dependOnDependencyAssertions et les paramètres includeDependentAssertions dans un même fichier, le paramètre includeDependentAssertions est prioritaire. Par exemple, si vous définissez dependOnDependencyAssertions sur true, mais que vous définissez également includeDependentAssertions sur false pour une action de dépendance sélectionnée, Dataform n'ajoutera pas les assertions de cette action aux dépendances.

L'exemple de code suivant montre les paramètres dependOnDependencyAssertions et includeDependentAssertions définis dans le même fichier de définition de table :

// filename is tableName.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "actionA", {name: "actionB", includeDependentAssertions: false} ]
}

SELECT * FROM ${ref("actionC")}

Dans l'exemple de code précédent, Dataform ajoute toutes les assertions directes de actionA et actionC aux dépendances de tableName lors de la compilation.

Définir les assertions sélectionnées comme dépendances

Pour exécuter une action de workflow uniquement lorsque les assertions sélectionnées sont réussies, vous pouvez ajouter l'assertion sélectionnée à la ligne dependencies: [ "" ] dans le bloc config de l'action modifiée.

Pour définir une assertion sélectionnée comme dépendance d'une action de workflow sélectionnée, procédez comme suit :

1. Dans votre espace de travail de développement, dans le volet Fichiers, développez definitions/.
2. Sélectionnez un fichier SQLX d'action de workflow.
3. Dans le bloc config du fichier d'action, saisissez dependencies: [ "" ].

4. Dans dependencies: [ "" ], saisissez le nom de l'assertion d'action ou le nom de fichier de l'assertion manuelle que vous souhaitez définir comme dépendance dans l'un des formats suivants :

   nonNull

   config {
     type: "ACTION_TYPE",
     dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_nonNull"]
   }
   

   Remplacez les éléments suivants :

   • ACTION_TYPE : type d'action de workflow : table, view ou operations.
   • ACTION_DATASET_NAME : nom de l'ensemble de données dans lequel l'action est définie. L'ensemble de données par défaut est défini dans le fichier de paramètres du workflow.
   • ACTION_NAME : nom de l'action dans laquelle l'assertion est définie.

   rowConditions

   config {
     type: "ACTION_TYPE",
     dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_rowConditions"]
   }
   

   Remplacez les éléments suivants :

   • ACTION_TYPE : type d'action de workflow : table, view ou operations.
   • DATASET_NAME : nom de l'ensemble de données dans lequel l'action est définie. L'ensemble de données par défaut est défini dans le fichier de paramètres du workflow.
   • ACTION_NAME : nom de l'action dans laquelle l'assertion est définie.

   uniqueKey

   config {
     type: "ACTION_TYPE",
     dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKey_INDEX"]
   }
   

   Remplacez les éléments suivants :

   • ACTION_TYPE : type d'action de workflow : table, view ou operations.
   • DATASET_NAME : nom de l'ensemble de données dans lequel la table est définie. L'ensemble de données par défaut est défini dans le fichier de paramètres du workflow.
   • ACTION_NAME : nom de la table dans laquelle l'assertion est définie.
   • INDEX : index du tableau de clés défini dans l'assertion uniqueKey que vous souhaitez ajouter en tant que dépendance (par exemple, 0 ou 1). Si une seule série de clés est définie dans l'assertion, l'index est 0.

   uniqueKeys

   config {
     type: "ACTION_TYPE",
     dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKeys_INDEX"]
   }
   

   Remplacez les éléments suivants :

   • ACTION_TYPE : type d'action de workflow : table, view ou operations.
   • DATASET_NAME : nom de l'ensemble de données dans lequel la table est définie. L'ensemble de données par défaut est défini dans le fichier de paramètres du workflow.
   • ACTION_NAME : nom de la table dans laquelle l'assertion est définie.
   • INDEX : index du tableau de clés défini dans l'assertion uniqueKeys que vous souhaitez ajouter en tant que dépendance (par exemple, 0 ou 1). Si une seule série de clés est définie dans l'assertion, l'index est 0.

   assertion manuelle

   config {
     type: "ACTION_TYPE",
     dependencies: [ "MANUAL_ASSERTION_NAME"]
   }
   

   Remplacez les éléments suivants :

   • ACTION_TYPE : type d'action de workflow : table, view ou operations.
   • MANUAL_ASSERTION_NAME : nom de l'assertion manuelle.

5. Pour ajouter une autre assertion en tant que dépendance au tableau modifié, répétez l'étape 4.

6. Facultatif : Cliquez sur Format.

L'exemple de code suivant montre les assertions ajoutées à la table A, qui est définie dans l'ensemble de données dataform :

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
  }
}

L'exemple de code suivant montre les assertions de la table A ajoutées en tant que dépendances à la table B :

config {
  type: "table",
  dependencies: [ "dataform_A_assertions_uniqueKey_0",  "dataform_A_assertions_nonNull"]
}

L'exemple de code suivant montre une assertion manuelle définie dans le fichier manualAssertion.sqlx et ajoutée en tant que dépendance à une vue :

config {
  type: "view",
  dependencies: [ "manualAssertion"]
}

L'exemple de code suivant montre le fichier manual_assertion et les assertions de la table sometable ajoutées en tant que dépendances à une table :

config {
  type: "table",
  dependencies: [ "manual_assertion",  "dataform_sometable_assertions_nonNull" ,  "dataform_sometable_assertions_rowConditions"]
}

SELECT * FROM ${ref("referenced_table")} LEFT JOIN ...

Définir les assertions d'une action sélectionnée comme dépendances

Pour exécuter une action de workflow uniquement lorsque toutes les assertions directes d'une action de dépendance sélectionnée sont réussies, définissez le paramètre includeDependentAssertions sur true dans l'action modifiée. Dataform ajoute automatiquement les assertions directes de l'action de dépendance sélectionnée aux dépendances lors de la compilation. La valeur par défaut est false.

Pour définir toutes les assertions d'une action de dépendance sélectionnée comme dépendances, procédez comme suit :

1. Dans votre espace de travail de développement, dans le volet Fichiers, développez definitions/.
2. Sélectionnez un fichier SQLX d'action de workflow.

3. Dans le fichier, définissez le paramètre includeDependentAssertions sur true de l'une des manières suivantes :

   Dans le bloc config

   config {
   type: "ACTION_TYPE",
   dependencies: [{name: "dEPENDENCY_ACTION_NAME", includeDependentAssertions: true}]
   }
   

   Remplacez les éléments suivants :

   • ACTION_TYPE : type d'action de workflow : table, view ou operations.
   • DEPENDENCY_ACTION_NAME : nom de l'action de dépendance avec les assertions que vous souhaitez définir comme dépendances de l'action modifiée.

   Dans l'instruction SELECT

     config { type: "ACTION_TYPE" }
   
     SELECT * FROM ${ref({name: "DEPENDENCY_ACTION_NAME", includeDependentAssertions: true})}
   

   Remplacez les éléments suivants :

   • ACTION_TYPE : type d'action de workflow : table, view ou operations.
   • DEPENDENCY_ACTION_NAME : nom de l'action de dépendance avec les assertions que vous souhaitez définir comme dépendances de l'action modifiée.

4. Facultatif : Cliquez sur Format.

L'exemple de code suivant montre tableC, qui dépend de viewA, tableB et de toutes les assertions de tableB :

// filename is tableC.sqlx

config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}

SELECT * FROM ...

Dans l'exemple de code précédent, Dataform ajoute automatiquement toutes les assertions directes de tableB en tant que dépendances de tableC lors de la compilation.

Définir les assertions de toutes les actions de dépendance comme dépendances

Pour exécuter une action de workflow uniquement lorsque toutes les assertions directes de toutes les actions de dépendance sont réussies, définissez le paramètre dependOnDependencyAssertions sur true dans l'action modifiée. Dataform ajoute automatiquement les assertions directes des actions de dépendance en tant que dépendances lors de la compilation. La valeur par défaut est false.

Lorsque vous définissez le paramètre dependOnDependencyAssertions et les paramètres includeDependentAssertions dans un même fichier, le paramètre includeDependentAssertions est prioritaire pour l'action de dépendance pour laquelle il est défini.

Pour définir toutes les assertions d'une action de dépendance sélectionnée comme dépendances, procédez comme suit :

1. Dans votre espace de travail de développement, dans le volet Fichiers, développez definitions/.
2. Sélectionnez un fichier SQLX d'action de workflow.

3. Dans le fichier, définissez le paramètre dependOnDependencyAssertions sur true au format suivant :

   config {
   type: "ACTION_TYPE",
   dependOnDependencyAssertions: true,
   dependencies: [ "dependency1", "dependency2" ]
   }
   

   Remplacez ACTION_TYPE par le type d'action de workflow. Les valeurs autorisées incluent table, view et operations.

4. Facultatif : Cliquez sur Format.

L'exemple de code suivant montre sometableE, qui dépend de sometableA, sometabletableB, sometableC, sometableD et de toutes les assertions directes des tables de dépendances :

// filename is sometableE.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "sometableA", "sometableB" ]
}

SELECT * FROM ${ref("sometableC")}
SELECT * FROM ${ref("sometableD")}

Dans l'exemple de code précédent, Dataform ajoute automatiquement toutes les assertions directes de sometableA, sometableB, sometableC et sometableD en tant que dépendances de sometableE lors de la compilation.

Référencer une table avec un nom de table remplacé

• Pour faire référence à une table dont le nom a été remplacé, saisissez le nom de table remplacé défini dans name: "" dans la fonction ref.

L'exemple de code suivant fait référence à une table dont le nom a été remplacé par overridden_name :

  SELECT * FROM ${ref("overridden_name")}

Pour en savoir plus sur le remplacement des noms de table, consultez Remplacer les paramètres de table.

Étapes suivantes

• Pour savoir comment définir des assertions comme dépendances, consultez Tester la qualité des données.
• Pour savoir comment déclarer une source de données, consultez Déclarer une source de données.
• Pour savoir comment définir des opérations SQL personnalisées, consultez Créer des opérations.
• Pour savoir comment réutiliser du code dans votre workflow avec des inclusions, consultez Réutiliser du code dans un même dépôt avec des inclusions.