Configurer une table incrémentielle

Ce document explique comment utiliser Dataform Core, qui permet de configurer table incrémentielle.

À propos d'une table incrémentielle

Dataform met à jour les tables différemment selon leur type. Pendant chaque exécution d'une table ou d'une vue, Dataform recrée l'ensemble une table ou une vue en partant de zéro.

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

Dataform insère les nouvelles lignes uniquement dans les colonnes qui existent déjà dans le table incrémentielle. Si vous modifiez la définition de la table incrémentielle (par exemple, ajouter une colonne), vous devez recréer la table en partant de zéro. Pour ce faire, la prochaine fois que vous déclencher une exécution de la table ; sélectionnez l'option Run with full refresh (Exécuter avec l'actualisation complète).

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

Optimisation des performances
Pour certains types de données, comme les journaux Web ou les données d'analyse, vous pouvez de ne traiter que les nouveaux enregistrements au lieu de retraiter l'ensemble de la table.
Réduction de la latence
Vous pouvez utiliser des tables incrémentielles pour exécuter des workflows rapidement, mais fréquemment. ce qui réduit 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 du Données de table, par exemple pour l'analyse longitudinale des paramètres utilisateur stockés dans une base de données de production.

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. Créez une table des Type de table incremental.

Rôles requis

Pour obtenir les autorisations dont vous avez besoin pour configurer une table incrémentielle, 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.

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

Déterminer un sous-ensemble de lignes que Dataform doit traiter lors de chaque , ajoutez une clause WHERE conditionnelle à la table incrémentielle SQLX fichier de définition d'origine. Dans la clause WHERE, vous pouvez spécifier une condition incrémentielle et une condition non incrémentielle. Dataform applique la condition incrémentielle lors de l'exécution de la table sans actualisation complète, et la condition non incrémentielle est appliquée lors de l'exécution avec une actualisation complète.

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

  1. Accédez à votre espace de travail de développement.
  2. Dans le volet Fichiers, développez definitions/.
  3. Ouvrez un fichier SQLX de définition de table incrémentielle.

  4. Saisissez une clause WHERE au format suivant:

    config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }

    Remplacez les éléments suivants :

    • SELECT_STATEMENT: l'instruction SELECT qui définit votre tableau

    • INCREMENTAL_CONDITION: condition que vous spécifiez dans WHERE pour sélectionner les lignes à traiter par Dataform lors de l'exécution de la table sans une actualisation complète.

    • NON_INCREMENTAL_CONDITION: la condition que vous spécifiez dans le Clause WHERE pour sélectionner les lignes à traiter par Dataform pendant la table avec une actualisation complète.

  5. (Facultatif) Cliquez sur Format.

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

config { type: "incremental" }

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

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

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 d'une table incrémentielle

Pour garantir 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 sur fusionner les lignes ayant le même uniqueKey. Lors de la mise à jour du tableau, Dataform fusionne les lignes avec uniqueKey au lieu de les ajouter.

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

  1. Accédez à votre espace de travail de développement.
  2. Dans le volet Fichiers, développez definitions/.
  3. Sélectionner un fichier SQLX de définition de table incrémentielle

  4. 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 de la colonne sélectionnée.

  5. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une table incrémentielle avec le transaction_id définie sur uniqueKey pour qu'elle contienne 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 d'analyser Dataform, tableau entier pour trouver les lignes correspondantes, définissez updatePartitionFilter pour ne prendre en compte un sous-ensemble d'enregistrements.

L'exemple de code suivant montre une table partitionnée incrémentielle avec fusion configuré 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 fait référence à une table partitionnée, nous vous recommandons de créer votre requête de table pour éviter une analyse complète la table partitionnée à chaque mise à jour incrémentielle.

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

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

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

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

L'exemple de code suivant montre une table incrémentielle dans laquelle les valeurs La table raw_events 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éfini dans le bloc pre_operations. La variable event_timestamp_checkpoint est ensuite utilisée en tant qu'expression constante. dans la clause WHERE.

Reconstruire une table incrémentielle à partir de zéro avec l'actualisation complète

Vous pouvez forcer la recompilation d'une table incrémentielle à partir de zéro à l'aide de la méthode Interface de ligne de commande avec l'option --full-refresh ou avec l'option Exécuter avec actualisation complète lorsque déclencher l'exécution d'un workflow.

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

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

Pour éviter qu'une table incrémentielle ne soit recompilée à partir de zéro et une perte de données, vous pouvez définir la table incrémentielle sur protected. Vous voudrez peut-être 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:

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

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

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

Étape suivante