À 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 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'une assertion.
Dataform crée automatiquement dans BigQuery des vues contenant les résultats des requêtes d'assertion compilées. Comme configurée dans votre fichier de paramètres de workflow, Dataform crée ces vues dans un schéma d'assertions dans lequel vous pouvez inspecter 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, tables incrémentielles, vues et vues matérialisées.
Vous pouvez créer des assertions de différentes manières:
Ajoutez des assertions intégrées au bloc de configuration d'une table.
Vous pouvez ajouter des assertions intégrées au bloc
config
d'une table et spécifier leurs conditions.Ajoutez les assertions manuelles dans un fichier SQLX distinct.
Vous écrivez manuellement les assertions personnalisées dans un fichier SQLX distinct pour les cas d'utilisation avancés ou pour les ensembles de données non créés par Dataform.
Avant de commencer
Dans la console Google Cloud, accédez à la page Dataform page.
Sélectionnez ou créez un dépôt.
Sélectionnez ou créez un espace de travail de développement.
Rôles requis
Pour obtenir les autorisations nécessaires 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 table. Dataform exécute ces assertions après la création de la table. Une fois que Dataform a publié 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 sur toutes les lignes de la table. 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 blocconfig
d'une table:
config {
type: "table",
assertions: {
nonNull: ["user_id", "customer_id", "email"]
}
}
SELECT ...
rowConditions
Cette condition garantit 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 de la table 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 blocconfig
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 blocconfig
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 plusieurs lignes de la table présentent les mêmes valeurs pour toutes les colonnes spécifiées.
L'exemple de code suivant montre une assertion
uniqueKeys
dans le blocconfig
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:
- Dans votre espace de travail de développement, dans le volet Fichiers, sélectionnez un fichier SQLX de définition de table.
- Dans le bloc
config
du fichier de table, saisissezassertions: {}
. - Dans
assertions: {}
, ajoutez vos assertions. - (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é. 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:
- Dans le volet Fichiers, à côté de
definitions/
, cliquez sur le menuPlus.
- Cliquez sur Créer un fichier.
Dans le champ Add a file path (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.
Cliquez sur Créer un fichier.
Dans le volet Fichiers, cliquez sur le nouveau fichier.
Dans le fichier, saisissez la commande suivante:
config { type: "assertion" }
Sous le bloc
config
, écrivez votre requête SQL ou plusieurs requêtes.(Facultatif) Cliquez sur Format.
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
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 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 aboutissent, vous devez définir celles 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 action sélectionnée 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 à
dependencies: [ "" ]
dans le blocconfig
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 dépende uniquement des assertions sélectionnées de l'action A, vous pouvez ajouter ces assertions sélectionnées au bloc d'action
config
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 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 définir automatiquement toutes les assertions directes d'une action de workflow de dépendance sélectionnée en tant que dépendances de l'action modifiée. Dataform ajoute ces assertions en tant que 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 vous souhaitez 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 le paramètre
dependOnDependencyAssertions
pour définir automatiquement toutes les assertions directes de toutes les actions de dépendance de l'action modifiée en tant que 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 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, vous pouvez la modifier 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 les paramètres dependOnDependencyAssertions
et includeDependentAssertions
dans un seul fichier, le paramètre includeDependentAssertions
est prioritaire.
Par exemple, si vous définissez dependOnDependencyAssertions
sur true
, mais également includeDependentAssertions
sur false
pour une action de dépendance sélectionnée, Dataform n'ajoutera pas d'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 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 en tant que dépendance d'une action de workflow sélectionnée, procédez comme suit:
- Dans le volet Fichiers de votre espace de travail de développement, développez
definitions/
. - Sélectionnez un fichier SQLX d'action de workflow.
- Dans le bloc
config
du fichier d'action, saisissezdependencies: [ "" ]
. Dans
dependencies: [ "" ]
, saisissez le nom de l'assertion d'action ou le nom du 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
ouoperations
). - 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 des 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 du workflow (
table
,view
ouoperations
). - 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
ouoperations
). - 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 l'assertion
uniqueKey
que vous souhaitez ajouter en tant que dépendance. Par exemple,0
ou1
. Si un seul tableau de clés est défini dans l'assertion, l'index est0
.
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
ouoperations
). - 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 l'assertion
uniqueKeys
que vous souhaitez ajouter en tant que dépendance (par exemple,0
ou1
). Si un seul tableau de clés est défini dans l'assertion, l'index est0
.
assertion manuelle
config { type: "ACTION_TYPE", dependencies: [ "MANUAL_ASSERTION_NAME"] }
Remplacez les éléments suivants :
- ACTION_TYPE : type d'action du workflow (
table
,view
ouoperations
). - MANUAL_ASSERTION_NAME est le nom de l'assertion manuelle.
- ACTION_TYPE : type d'action du workflow (
Pour ajouter une autre assertion en tant que dépendance à la table modifiée, répétez l'étape 4.
(Facultatif) Cliquez sur Format.
L'exemple de code suivant montre des assertions ajoutées à la table A, 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
, 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 en tant que dépendances
Pour n'exécuter une action de workflow que lorsque toutes les assertions directes d'une action de dépendance sélectionnée sont conclues, 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 en tant que dépendance, procédez comme suit:
- Dans le volet Fichiers de votre espace de travail de développement, développez
definitions/
. - Sélectionnez un fichier SQLX d'action de workflow.
Dans le fichier, définissez le paramètre
includeDependentAssertions
surtrue
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
ouoperations
). - DEPENDENCY_ACTION_NAME: nom de l'action de dépendance que vous souhaitez définir en tant que 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
ouoperations
). - DEPENDENCY_ACTION_NAME: nom de l'action de dépendance que vous souhaitez définir en tant que dépendances de l'action modifiée.
- ACTION_TYPE : type d'action du workflow (
(Facultatif) Cliquez sur Format.
L'exemple de code suivant montre tableC
qui dépend de viewA
, de 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 à tableC
lors de la compilation.
Définir les assertions de toutes les actions de dépendance en tant que dépendances
Pour 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 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 les paramètres dependOnDependencyAssertions
et includeDependentAssertions
dans un seul 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 en tant que dépendance, procédez comme suit:
- Dans le volet Fichiers de votre espace de travail de développement, développez
definitions/
. - Sélectionnez un fichier SQLX d'action de workflow.
Dans le fichier, définissez le paramètre
dependOnDependencyAssertions
surtrue
, 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
etoperations
.(Facultatif) Cliquez sur Format.
L'exemple de code suivant montre sometableE
qui dépend de sometableA
, sometabletableB
, sometableC
et sometableD
, ainsi que de toutes les assertions directes des tables de dépendance:
// 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 à sometableE
lors de la compilation.
Étapes suivantes
- Pour en savoir plus sur les types d'assertion, consultez la page API Dataform.
- Pour apprendre à définir des assertions avec JavaScript, consultez la page Créer des workflows SQL avec JavaScript.
- Pour savoir comment exécuter des workflows manuellement, consultez la section Déclencher une exécution.