Valider les tables avec des assertions

Ce document vous explique comment utiliser Dataform Core pour créer des assertions de table Dataform et valider votre code de workflow.

À propos des assertions

Une assertion est une requête de test de qualité des données qui recherche les lignes qui ne respectent pas une ou plusieurs des règles spécifiées dans la requête. Si la requête renvoie des lignes, l'assertion échoue. Dataform exécute des assertions chaque fois qu'il met à jour votre workflow SQL et vous alerte en cas d'échec d'assertion.

Dataform crée automatiquement dans BigQuery des vues contenant les résultats des requêtes d'assertion compilées. Comme configuré dans votre fichier dataform.json, Dataform crée ces vues dans un schéma d'assertions dans lequel vous pouvez inspecter les résultats d'assertion.

Par exemple, pour le schéma dataform_assertions par défaut, Dataform crée une vue dans BigQuery au format suivant : dataform_assertions.assertion_name.

Vous pouvez créer des assertions pour tous les types de tables Dataform: tables, tables incrémentielles, vues et vues matérialisées.

Vous pouvez créer des assertions de différentes manières:

Avant de commencer

  1. Dans la console Google Cloud, accédez à la page Dataform.

    Accéder à la page Dataform

  2. Sélectionnez ou créez un dépôt.

  3. Sélectionnez ou créez un espace de travail de développement.

  4. Définir une table

Rôles requis

Pour obtenir les autorisations nécessaires afin de créer des assertions, demandez à votre administrateur de vous attribuer le rôle IAM Éditeur de formulaire de données (roles/dataform.editor) sur les espaces de travail. Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

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

Créer des assertions intégrées

Vous pouvez ajouter des assertions Dataform intégrées au bloc config d'une table. Dataform exécute ces assertions après la création de la table. Une fois la table publiée par Dataform, vous pouvez inspecter l'assertion.

Vous pouvez créer les assertions suivantes dans le bloc config d'une table:

  • nonNull

    Cette condition affirme que les colonnes spécifiées ne sont pas nulles dans toutes les lignes de la table. Cette condition est utilisée pour les colonnes qui ne peuvent jamais avoir une valeur nulle.

    L'exemple de code suivant montre une assertion nonNull dans le bloc config d'une table:

config {
  type: "table",
  assertions: {
    nonNull: ["user_id", "customer_id", "email"]
  }
}
SELECT ...

  • rowConditions

    Cette condition suppose que toutes les lignes de la table suivent la logique personnalisée que vous définissez. Chaque condition de ligne est une expression SQL personnalisée, et chaque ligne du tableau est évaluée par rapport à chaque condition de ligne. L'assertion échoue si une ligne de la table ne respecte pas une condition de ligne.

    L'exemple de code suivant montre une assertion rowConditions personnalisée dans le bloc config d'une table incrémentielle:

config {
  type: "incremental",
  assertions: {
    rowConditions: [
      'signup_date is null or signup_date > "2022-08-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...

  • uniqueKey

    Cette condition affirme que, dans une colonne spécifiée, aucune ligne de table n'a la même valeur.

    L'exemple de code suivant montre une assertion uniqueKey dans le bloc config d'une vue:

config {
  type: "view",
  assertions: {
    uniqueKey: ["user_id"]
  }
}
SELECT ...

  • uniqueKeys

    Cette condition affirme que, dans les colonnes spécifiées, aucune ligne de table n'a la même valeur. L'assertion échoue si la table comporte plusieurs lignes avec les mêmes valeurs pour toutes les colonnes spécifiées.

    L'exemple de code suivant montre une assertion uniqueKeys dans le bloc config d'une table:

config {
  type: "table",
  assertions: {
    uniqueKeys: [["user_id"], ["signup_date", "customer_id"]]
  }
}
SELECT ...

Ajouter des assertions au bloc config

Pour ajouter des assertions au bloc de configuration d'une table, procédez comme suit:

  1. Dans le volet Fichiers de votre espace de travail de développement, sélectionnez un fichier SQLX de définition de table.
  2. Dans le bloc config du fichier de table, saisissez assertions: {}.
  3. Dans assertions: {}, ajoutez vos assertions.

L'exemple de code suivant montre les conditions ajoutées dans le bloc config:

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
    rowConditions: [
      'signup_date is null or signup_date > "2019-01-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...

Créer des assertions manuelles avec SQLX

Les assertions manuelles sont des requêtes SQL que vous écrivez dans un fichier SQLX dédié. Une requête SQL d'assertion manuelle ne doit renvoyer aucune ligne. Si la requête renvoie des lignes lors de l'exécution, l'assertion échoue.

Pour ajouter des assertions manuelles dans un nouveau fichier SQLX, procédez comme suit:

  1. Dans le volet Fichiers, à côté de definitions/, cliquez sur le menu .
  2. Cliquez sur Créer un fichier.

  3. Dans le champ Ajouter un chemin d'accès au fichier, saisissez le nom du fichier suivi de .sqlx. Exemple : definitions/custom_assertion.sqlx.

    Les noms de fichiers ne peuvent contenir que des chiffres, des lettres, des traits d'union et des traits de soulignement.

  4. Cliquez sur Créer un fichier.

  5. Dans le volet Fichiers, cliquez sur le nouveau fichier.

  6. Dans le fichier, saisissez:

    config {
  type: "assertion"
}

  7. Sous le bloc config, écrivez votre ou vos requêtes SQL.

L'exemple de code suivant montre une assertion manuelle dans un fichier SQLX, qui affirme que les champs a, b et c ne sont jamais NULL dans sometable:

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("sometable")}
WHERE
  a IS NULL
  OR b IS NULL
  OR c IS NULL

Ajouter des assertions en tant que dépendances

Lorsque la table B dépend de la table A qui contient des assertions, l'échec des assertions de table A n'empêche pas Dataform de créer la table B. Pour exécuter la table B uniquement si les assertions de la table A sont transmises, ajoutez-les en tant que dépendances de dependencies: [ "" ] dans le bloc config de la table B.

L'exemple de code suivant montre les assertions ajoutées à la table A:

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: [ "A_uniqueKey",  "A_nonNull"]
}

Pour exécuter une table uniquement lorsque certaines assertions manuelles sont transmises, vous pouvez ajouter le fichier SQLX d'assertion manuelle à dependencies: [ "" ] dans le bloc config.

L'exemple de code suivant montre une assertion manuelle ajoutée en tant que dépendance à une vue:

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

Pour ajouter un fichier d'assertion ou une table avec des assertions dans son bloc config en tant que dépendance de table, procédez comme suit:

  1. Dans le volet Fichiers de votre espace de travail de développement, développez definitions/.
  2. Sélectionnez un fichier SQLX de table.
  3. Dans le bloc config du fichier de table, saisissez dependencies: [ "" ].
  4. Dans dependencies: [ "" ], saisissez le nom de l'assertion de table ou du nom de fichier de l'assertion manuelle que vous souhaitez définir en tant que dépendance de table. Vous trouverez les noms des assertions dans le panneau METADATA.
  5. Pour ajouter une autre assertion en tant que dépendance au tableau modifié, répétez l'étape 4.

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

config {
  type: "table",
  dependencies: [ "manual_assertion",  "sometable_nonNull" ,  "sometable_rowConditions"]
}

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

Étapes suivantes