Configurer une table incrémentielle

Ce document explique comment utiliser Dataform Core pour configurer une table incrémentielle.

À propos d'une table incrémentielle

Dataform met à jour les tables différemment en fonction du type de table. Lors de chaque exécution d'une table ou d'une vue, Dataform recompile l'intégralité de la table ou de la vue en partant de zéro.

Lorsque vous définissez une table incrémentielle, Dataform crée la table incrémentielle à partir de zéro uniquement pour la première fois. Lors des exécutions suivantes, Dataform insère ou fusionne les nouvelles lignes dans la table incrémentielle uniquement en fonction des conditions que vous configurez.

Dataform n'insère de nouvelles lignes que dans les colonnes déjà présentes dans la table incrémentielle. Si vous modifiez la requête de définition de table incrémentielle (par exemple, en ajoutant une colonne), vous devez recréer la table à partir de zéro. Pour ce faire, la prochaine fois que vous déclenchez une exécution de la table, sélectionnez l'option Exécuter avec une actualisation complète.

Voici quelques cas d'utilisation courants des tables incrémentielles:

Optimisation des performances: Pour certains types de données, tels que les journaux Web ou les données d'analyse, vous souhaiterez peut-être traiter uniquement les nouveaux enregistrements au lieu de retraiter l'intégralité de la table.
Réduction de la latence: Vous pouvez utiliser des tables incrémentielles pour exécuter des workflows rapidement, mais fréquemment, afin de réduire la latence en aval des tables de sortie.
Instantanés quotidiens: Vous pouvez configurer une table incrémentielle pour créer des instantanés quotidiens des données de la table, par exemple pour une analyse longitudinale des paramètres utilisateur stockés dans une base de données de production.

Avant de commencer

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

Accéder à la page Dataform
Sélectionnez ou créez un dépôt.
Sélectionnez ou créez un espace de travail de développement.
Créez une table de type incremental.

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer une table incrémentielle, demandez à votre administrateur de vous attribuer 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.

Traiter un sous-ensemble de lignes dans une table incrémentielle

Pour déterminer un sous-ensemble de lignes que Dataform doit traiter lors de chaque exécution, ajoutez une clause WHERE conditionnelle au fichier de définition SQLX de la table incrémentielle.

Pour configurer une table incrémentielle, procédez comme suit:

Accédez à votre espace de travail de développement.
Dans le volet Fichiers, développez definitions/.
Ouvrez un fichier SQLX de définition de table incrémentielle.
Saisissez une clause WHERE au format suivant:
```
config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE CONDITION`) }
```
Remplacez les éléments suivants :
- SELECT_STATEMENT: instruction SELECT qui définit votre table
- CONDITION: votre condition pour la clause WHERE qui sélectionne les lignes à traiter par Dataform lors de l'exécution de la table.
(Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une table incrémentielle qui traite de manière incrémentielle les lignes de la table productiondb.logs:

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

L'exemple de code suivant montre une table incrémentielle qui crée un instantané de la table productiondb.customers:

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

Fusionner les lignes dans une table incrémentielle

Pour vous assurer qu'une table incrémentielle ne contient qu'une seule ligne correspondant à une combinaison de colonnes sélectionnée, définissez les colonnes sélectionnées sur uniqueKey afin de fusionner les lignes ayant le même uniqueKey. Lors de la mise à jour de la table, Dataform fusionne les lignes avec uniqueKey au lieu de les ajouter.

Pour configurer la fusion dans une table incrémentielle, procédez comme suit:

Accédez à votre espace de travail de développement.
Dans le volet Fichiers, développez definitions/.
Sélectionner un fichier SQLX de définition de table incrémentielle
Dans le bloc config, définissez les colonnes sélectionnées sur uniqueKey au format suivant:
```
uniqueKey: ["COLUMN_NAME"]
```
Remplacez COLUMN_NAME par le nom d'une colonne sélectionnée.
(Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une table incrémentielle avec la colonne transaction_id définie sur uniqueKey pour s'assurer qu'elle contient toujours une ligne:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Filtrer les lignes d'une table incrémentielle

Dans une table partitionnée incrémentielle, pour éviter que Dataform analyse la table entière et trouver les lignes correspondantes, définissez updatePartitionFilter pour qu'il ne prenne en compte qu'un sous-ensemble d'enregistrements.

L'exemple de code suivant montre une table partitionnée incrémentielle dans laquelle la fusion est configurée en définissant les propriétés uniqueKey et updatePartitionFilter:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Éviter les analyses complètes de table lors de l'ingestion à partir d'une table partitionnée

Lorsque vous créez une table incrémentielle qui référence une table partitionnée, nous vous recommandons de créer votre requête de table pour éviter les analyses complètes de la table partitionnée lors de chaque mise à jour incrémentielle.

Vous pouvez limiter le nombre de partitions analysées par BigQuery pour mettre à jour la table incrémentielle en utilisant une expression constante dans votre requête de table. Pour transformer une valeur de la table partitionnée en expression constante, utilisez les scripts BigQuery pour déclarer la valeur en tant que variable dans le bloc pre_operations. Ensuite, utilisez la variable en tant qu'expression constante dans une clause WHERE de la requête SELECT.

Avec cette configuration, Dataform met à jour la table incrémentielle en fonction des partitions les plus récentes de la table partitionnée référencée, sans analyser l'intégralité de la table.

Pour configurer une table incrémentielle qui référence une table partitionnée et évite des analyses complètes de table, procédez comme suit:

Accédez à votre espace de travail de développement.
Dans le volet Fichiers, développez definitions/.
Sélectionner un fichier SQLX de définition de table incrémentielle
Dans le bloc pre_operations, déclarez une variable avec un script BigQuery.
Filtrez l'instruction SELECT qui définit la table avec une clause WHERE qui référence la variable déclarée.
(Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une table incrémentielle dans laquelle la table raw_events référencée est partitionnée par event_timestamp:

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

Dans l'exemple de code précédent, la variable event_timestamp_checkpoint est définie dans le bloc pre_operations. La variable event_timestamp_checkpoint est ensuite utilisée en tant qu'expression constante dans la clause WHERE.

Recréer une table incrémentielle en partant de zéro grâce à une actualisation complète

Vous pouvez forcer la recompilation d'une table incrémentielle en partant de zéro à l'aide de l'interface de ligne de commande avec l'option --full-refresh ou avec l'option Exécuter avec une actualisation complète lors du déclenchement d'une exécution de workflow.

Lorsque vous sélectionnez l'option d'actualisation complète, dans votre espace de travail de développement ou à l'aide de la CLI Dataform, Dataform ignore le paramètre ${when(incremental(), ... } lors de l'exécution et recrée la table avec une instruction CREATE OR REPLACE.

Protéger une table incrémentielle contre l'actualisation complète

Pour empêcher une table incrémentielle d'être recréée à partir de zéro et d'éviter une perte de données potentielle, vous pouvez la définir sur protected. Vous pouvez empêcher la recompilation d'une table incrémentielle si votre source de données est temporaire.

Pour marquer une table incrémentielle comme protected, procédez comme suit:

Accédez à votre espace de travail de développement.
Dans le volet Fichiers, développez definitions/.
Sélectionnez un fichier SQLX de définition de table incrémentielle.
Dans le bloc config, saisissez protected: true.
(Facultatif) Cliquez sur Format.

L'exemple de code suivant montre des tables incrémentielles marquées comme protected:

config {
  type: "incremental",
  protected: true
}
SELECT ...

Étapes suivantes

Pour savoir comment définir une table, consultez Créer une table.
Pour apprendre à utiliser l'interface de ligne de commande Dataform, consultez la page Utiliser la CLI Dataform.
Pour apprendre à déclencher manuellement des exécutions, consultez Déclencher une exécution.