Tables de test avec des assertions

Ce document explique comment utiliser Dataform Core pour créer Assertions de table Dataform et tester le code de votre 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 un ou d'autres règles spécifiées dans la requête. Si la requête renvoie des lignes, l'assertion est défaillant. Dataform exécute des assertions chaque fois qu'il met à jour votre workflow SQL et il vous alerte en cas d'échec d'une assertion.

Dataform crée automatiquement dans BigQuery des vues contenant les résultats des requêtes d'assertion compilées. En tant que configurés dans votre fichier de paramètres de workflow, Dataform crée ces vues dans un schéma d'assertions et inspectent les résultats des assertions.

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, de tables incrémentielles, de vues et de 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 page.

    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éfinissez une table.

Rôles requis

Pour obtenir les autorisations dont vous avez besoin pour créer des assertions, 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 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 tableau. Dataform exécute ces assertions après la création de la table. Après Dataform publie la table, 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 pour toutes les lignes du tableau. Cette condition est utilisée pour les colonnes qui ne peuvent jamais être nulles.

    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 garantit que toutes les lignes du tableau suivent la logique personnalisée définir. Chaque condition de ligne est une expression SQL personnalisée et chaque ligne du tableau est 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 le la même valeur.

    L'exemple de code suivant montre une assertion uniqueKey dans config. bloc 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 s'il y a plus d'une ligne dans la table avec les mêmes valeurs pour toutes les colonnes spécifiées.

    L'exemple de code suivant montre une assertion uniqueKeys dans config. bloc 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 une table. fichier SQLX de définition.
  2. Dans le bloc config du fichier de table, saisissez assertions: {}.
  3. Dans assertions: {}, ajoutez vos assertions.
  4. (Facultatif) Cliquez sur Format.

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é. A une requête SQL d'assertion manuelle ne doit renvoyer aucune ligne. Si la requête renvoie des lignes lorsqu'elle est exécutée, 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 Plus.
  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 la commande suivante:

    config {
  type: "assertion"
}

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

  8. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une assertion manuelle dans un fichier SQLX qui confirme 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

Définir des assertions en tant que 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 ne bloque pas Dataform de l'exécution de l'action B. Pour exécuter l'action B uniquement si les assertions de l'action A sont validées, vous devez définir les assertions de l'action A en tant que dépendances de l'action B.

Vous pouvez définir des assertions en tant que dépendances d'une propriété l'action de différentes manières:

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

Vous pouvez définir manuellement des assertions sélectionnées comme dépendances en les ajoutant sur 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 voulez que l'action B ne dépende que des assertions sélectionnées de l'action A, vous pouvez ajouter les assertions sélectionnées au bloc d'action config B.

Vous pouvez définir manuellement les assertions sélectionnées comme dépendances de toutes les actions à l'exception des déclarations de source de données.

Définir les assertions d'une action de dépendance sélectionnée en tant que dépendances

Vous pouvez définir le paramètre includeDependentAssertions pour qu'il définir toutes les assertions directes d'une action de workflow de dépendance sélectionnée comme les dépendances de l'action modifiée. Dataform ajoute ces assertions en tant que les dépendances lors de chaque compilation de l'action afin de s'assurer 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 seule 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éfinir les assertions de toutes les actions de dépendance en tant que dépendances

Vous pouvez définir 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 s’assurer 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 en tant que 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 Paramètres includeDependentAssertions dans un seul fichier, le paramètre includeDependentAssertions est prioritaire. Par exemple, si vous définissez dependOnDependencyAssertions sur true, mais aussi définir includeDependentAssertions sur false pour une dépendance sélectionnée Dataform n'ajoute pas d'assertions pour cette action aux dépendances.

L'exemple de code suivant montre les classes dependOnDependencyAssertions et Paramètres 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 en tant que dépendances

Pour exécuter une action de workflow uniquement lorsque les assertions sélectionnées sont validées, vous pouvez ajouter l'assertion sélectionnée à 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 le volet Fichiers de votre espace de travail de développement, 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 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 du workflow: table, view ou operations.
    • ACTION_DATASET_NAME: nom de l'ensemble de données dans lequel est définie. L'ensemble de données par défaut est défini dans le fichier des paramètres du workflow.
    • ACTION_NAME: nom de l'action pour 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 du 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 des 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 du 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 des 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 le uniqueKey que vous souhaitez ajouter en tant que dépendance. Par exemple, 0 ou 1. Si un seul tableau de clés est défini 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 du 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 des 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 le uniqueKeys que vous souhaitez ajouter en tant que dépendance, par exemple 0 ou 1. Si un seul tableau de clés est défini 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 du workflow: table, view ou operations.
    • MANUAL_ASSERTION_NAME est le nom de l'assertion manuelle.

  5. Pour ajouter une autre assertion en tant que dépendance à la table modifiée, répétez l'étape 4.

  6. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre des assertions ajoutées à la table A, défini 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 manualAssertion.sqlx, ajouté en tant que dépendance à une vue:

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

L'exemple de code suivant montre le fichier manual_assertion et le 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 en tant que dépendances

À n'exécuter une action de workflow que lorsque toutes les assertions directes d'une passe d'action de dépendance sélectionnée, Définissez le paramètre includeDependentAssertions sur true dans l'action modifiée. Dataform ajoute automatiquement les assertions directes de la dépendance sélectionnée sur les 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 en tant que dépendance, 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 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 du workflow: table, view ou operations.
    • DEPENDENCY_ACTION_NAME: nom de l'action de dépendance 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 du workflow: table, view ou operations.
    • DEPENDENCY_ACTION_NAME: nom de l'action de dépendance 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 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 assertions directes de tableB en tant que dépendances de tableC pendant la compilation.

Définir les assertions de toutes les actions de dépendance en tant que dépendances

À n'exécuter une action de workflow que lorsque toutes les assertions directes de toutes les actions de dépendance sont validées, Définissez le paramètre dependOnDependencyAssertions sur true dans l'action modifiée. Dataform ajoute automatiquement des assertions directes 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 Paramètres includeDependentAssertions dans un seul fichier, le paramètre includeDependentAssertions est prioritaire pour la dépendance pour laquelle il est défini.

Pour définir toutes les assertions d'une action de dépendance sélectionnée en tant que dépendance, 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 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: type d'action du workflow. Les valeurs accepté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 et sometableD, ainsi que toutes les assertions directes de 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 assertions directes de sometableA, sometableB, sometableC et sometableD en tant que dépendances de sometableE lors de la compilation.

Étape suivante