Créer des tables

Dans Dataform, un tableau est l'un des types d'objets qui constituent un workflow. Vous pouvez créer des tables qui font référence aux données des sources de données déclarées pour votre workflow ou à celles d'autres tables de votre workflow. Dataform compile vos définitions de tables en SQL en temps réel. Lorsque vous déclenchez l'exécution, Dataform exécute le code SQL et crée les tables définies dans BigQuery.

Vous pouvez créer les types de tables suivants dans un fichier SQLX type: "table":

Vous pouvez également définir des partitions et des clusters de table.

Pour conserver une trace de l'objectif d'un tableau ou de sa relation avec d'autres tableaux dans votre workflow, vous pouvez ajouter de la documentation au tableau ou à ses colonnes sélectionnées.

Pour tester les données d'un tableau en fonction de conditions spécifiques, vous pouvez créer des requêtes de test de qualité des données appelées assertions. Dataform exécute des assertions chaque fois qu'il met à jour votre workflow et vous avertit en cas d'échec.

Pour remplacer les paramètres de table par défaut, tels que database ou schema, et désactiver la création de table, ou exécuter une instruction SQL avant ou après la création de table, vous pouvez configurer des paramètres de table supplémentaires.

Vous pouvez configurer des paramètres de table supplémentaires pour effectuer les opérations suivantes:

  • Remplacez les paramètres de table par défaut, tels que database ou schema.
  • Désactivez la création de tableaux.
  • Exécutez une instruction SQL avant ou après la création de la table.

Pour organiser vos tables dans BigQuery après les avoir exécutées, vous pouvez ajouter des libellés BigQuery. Pour en savoir plus, consultez la section Présentation des libellés.

Pour restreindre l'accès aux données au niveau des colonnes de la table, vous pouvez ajouter des tags avec stratégie BigQuery. Pour en savoir plus, consultez la page Présentation du contrôle des accès au niveau des colonnes.

En plus de définir des tables dans un fichier SQLX type: "table", vous pouvez créer des tables vides en définissant une requête SQL personnalisée dans un fichier SQLX type: "operations". Vous pouvez créer une table vide afin qu'un autre service puisse la remplir de données.

Avant de commencer

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

    Accéder à Dataform

  2. Créez et initialisez un espace de travail de développement dans votre dépôt.

  3. Facultatif: Déclarez une source de données.

Rôles requis

Pour obtenir les autorisations nécessaires pour effectuer les tâches de ce document, 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 page Gérer l'accès aux projets, aux dossiers et aux organisations.

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

Créer une table

Cette section explique comment créer des tables avec le noyau Dataform dans Dataform.

À propos des définitions de table

Pour définir une table, vous devez définir son type et écrire une instruction SELECT dans un fichier SQLX type: "table". Dataform compile ensuite votre code de base Dataform en SQL, exécute le code SQL et crée les tables définies dans BigQuery.

Dans une instruction SELECT de base Dataform, vous définissez la structure du tableau et référencez d'autres objets de votre workflow.

En plus de définir des tables dans un fichier SLQX type: "table", vous pouvez créer des tables vides en définissant une requête SQL personnalisée dans un fichier SQLX type: "operations". Pour en savoir plus, consultez la section Créer une table vide.

Référencer des dépendances avec ref

Pour faire référence à un objet de workflow dans une instruction SELECT et l'ajouter automatiquement en tant que dépendance, utilisez la fonction ref. Dataform exécute les dépendances avant les tables qui en dépendent pour garantir un ordre de pipeline correct.

La fonction ref est une fonction de base Dataform intégrée qui est essentielle à la gestion des dépendances dans Dataform. La fonction ref vous permet de référencer et de dépendre automatiquement des objets suivants définis dans votre workflow Dataform, au lieu de coder en dur le schéma et les noms de table:

Dataform utilise la fonction ref pour créer un arbre de dépendances de toutes les tables à créer ou à mettre à jour.

Après la compilation, Dataform ajoute des instructions standards à l'instruction SQL, telles que CREATE, REPLACE, INSERT ou MERGE.

L'exemple de code suivant montre une définition de table à l'aide de la fonction ref:

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

Dans la fonction ref, vous devez indiquer le nom de la déclaration de table ou de source de données sur laquelle vous souhaitez dépendre. Il s'agit généralement du nom de fichier du fichier SQLX dans lequel cette déclaration de table ou de source de données est définie.

Si un nom de table est remplacé, utilisez le nom remplacé dans la fonction ref. Par exemple, référencez une table avec config { name: "overridden_name" } en tant que ref("overridden_name"). Pour en savoir plus sur le forçage des noms de table, consultez Configurer des paramètres de table supplémentaires.

Lorsque plusieurs tables portent le même nom dans différents schémas, vous pouvez faire référence à une table spécifique en fournissant deux arguments à la fonction ref : le nom du schéma et le nom de la table.

L'exemple de code suivant montre la fonction ref avec deux arguments pour spécifier une table dans un schéma spécifique:

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

Vous pouvez également ajouter manuellement des dépendances de table au bloc config pour les tables, les assertions, les déclarations de sources de données ou les opérations SQL personnalisées qui ne sont pas référencées dans une fonction ref dans l'instruction SELECT. Dataform exécute ces dépendances avant les tables dépendantes.

L'exemple de code suivant montre une dépendance de table dans le bloc config:

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

Pour en savoir plus sur la gestion des dépendances dans votre workflow, consultez la section Déclarer des dépendances.

Référencer d'autres tables avec resolve

La fonction resolve vous permet de faire référence à une déclaration de table ou de source de données dans une instruction SELECT, comme la fonction ref, mais elle n'ajoute pas la référence en tant que dépendance. Cela signifie que l'objet référencé à l'aide de la fonction resolve n'affecte pas l'exécution de la table qui utilise la fonction resolve.

Pour en savoir plus sur les fonctions de base Dataform intégrées, consultez la documentation de référence sur les fonctions de base Dataform.

Créer un fichier SQLX pour une définition de table

Stockez les fichiers SQLX de définition de table dans le répertoire definitions/. Pour créer un fichier SQLX dans le répertoire definitions/, procédez comme suit:

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

    Accéder à Dataform

  2. Pour ouvrir un dépôt, cliquez sur son nom.

  3. Pour ouvrir un espace de travail de développement, cliquez sur son nom.

  4. Dans le volet Fichiers, à côté de definitions/, cliquez sur Plus.

  5. Cliquez sur Créer un fichier.

  6. Dans le champ Ajouter un chemin d'accès au fichier, saisissez le nom du fichier suivi de .sqlx après definitions/. Par exemple, definitions/my-table.sqlx.

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

  7. Cliquez sur Créer un fichier.

Définir le type de table

Pour créer une définition de type de table, procédez comme suit:

  1. Dans votre espace de travail de développement, dans le volet Fichiers, développez le répertoire definitions/.
  2. Sélectionnez le fichier SQLX de définition de table que vous souhaitez modifier.

  3. Dans le fichier, saisissez l'extrait de code suivant :

    config { type: "TABLE_TYPE" }

    Remplacez TABLE_TYPE par l'un des types de tableaux suivants:

    • table
    • incremental
    • view

  4. Facultatif: pour définir une vue matérialisée, saisissez la propriété materialized sous type: "view" au format suivant:

    config {
  type: "view",
  materialized: true
}

    Pour en savoir plus, consultez la section ITableConfig.

  5. Facultatif: cliquez sur Format.

Définir la structure et les dépendances de la table

Pour écrire une instruction SELECT de définition de table et définir la structure et les dépendances de la table, procédez comme suit:

  1. Dans votre espace de travail de développement, dans le volet Fichiers, développez le répertoire definitions/.
  2. Sélectionnez le fichier SQLX de définition de table que vous souhaitez modifier.
  3. Sous le bloc config, écrivez une instruction SELECT.
  4. Facultatif: cliquez sur Format.

L'exemple de code suivant montre une définition de table avec une instruction SELECT et la fonction ref:

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

Ajouter des dépendances de table manuelles

Pour ajouter des dépendances de table qui ne sont pas référencées dans l'instruction SELECT, mais qui doivent être exécutées avant la table actuelle, procédez comme suit:

  1. Dans votre espace de travail de développement, dans le volet Fichiers, développez le répertoire definitions/.
  2. Sélectionnez le fichier SQLX de définition de table que vous souhaitez modifier.

  3. Dans le bloc config de la table, saisissez l'extrait de code suivant:

    dependencies: [ "DEPENDENCY_TABLE", ]

    Remplacez DEPENDENCY_TABLE par le nom de fichier de la table que vous souhaitez ajouter en tant que dépendance. Vous pouvez saisir plusieurs noms de fichiers.

  4. Facultatif: cliquez sur Format.

L'exemple de code suivant montre deux tables ajoutées en tant que dépendances de table manuelles au bloc config d'un fichier de définition de table:

config { dependencies: [ "some_table", "some_other_table" ] }

Créer des partitions et des clusters de tables

Cette section explique comment utiliser le noyau Dataform pour créer des partitions et des clusters de tables. BigQuery est compatible avec les tables partitionnées et le clustering de tables. Pour en savoir plus, consultez les pages Présentation des tables partitionnées et Créer et utiliser des tables en cluster.

Créer une partition de table

Pour créer une partition de table, 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.

  4. Dans le bloc config, ajoutez le bloc bigquery sous la déclaration de type de table au format suivant:

    config {
  type: "table",
  bigquery: {
  }
}

  5. Dans le bloc bigquery, saisissez l'extrait de code suivant:

        partitionBy: "PARTITION_EXPRESSION"

    Remplacez PARTITION_EXPRESSION par une expression de partitionnement de la table.

  6. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre comment partitionner une table par heure dans un fichier SQLX de définition de table:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

L'exemple de code suivant montre comment partitionner une table par valeur entière dans un fichier SQLX de définition de table:

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

Définir un filtre de partitionnement

Pour définir un filtre de partition, 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 partitionnée.

  4. Dans le bloc bigquery, saisissez l'extrait de code suivant:

    requirePartitionFilter : true

  5. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre un filtre de partition défini dans le bloc bigquery d'un fichier SQLX de table partitionnée:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Pour en savoir plus sur le filtre de partitionnement dans BigQuery, consultez la section Définir l'attribut de filtrage de partition requis sur une table partitionnée.

Définir une durée de conservation pour les partitions

Pour contrôler la conservation de toutes les partitions d'une table partitionnée, 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 partitionnée.

  4. Dans le bloc bigquery, saisissez l'extrait de code suivant:

    partitionExpirationDays: NUMBER_OF_DAYS

    Remplacez NUMBER_OF_DAYS par le nombre de jours pendant lesquels vous souhaitez conserver les partitions.

  5. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une période de conservation des partitions définie sur 14 jours dans le bloc bigquery d'un fichier SQLX de table partitionnée:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Créer un cluster de tables

Pour créer un cluster de tables, 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.

  4. Dans le bloc bigquery, saisissez l'extrait de code suivant:

        clusterBy: ["CLUSTER_COLUMN"]

    Remplacez CLUSTER_COLUMN par le nom de la colonne par laquelle vous souhaitez regrouper le tableau. Pour en savoir plus, consultez clustering_column_list.

  5. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une table partitionnée mise en cluster par les colonnes name et revenue:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

Configurer un tableau incrémentiel

Cette section explique comment utiliser le noyau Dataform pour configurer une table incrémentielle.

À propos des tables incrémentielles

Dataform met à jour les tables différemment en fonction du type de table. À chaque exécution d'une table ou d'une vue, Dataform reconstruit l'ensemble de la table ou de la vue à partir de zéro.

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

Dataform n'insère de nouvelles lignes que dans les colonnes qui existent déjà 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éclencherez une exécution de la table, sélectionnez l'option Exécuter avec 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 pouvez ne traiter que les nouveaux enregistrements au lieu de retraiter l'ensemble du tableau.
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 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.

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

Pour déterminer un sous-ensemble de lignes que Dataform doit traiter à chaque exécution, ajoutez une clause WHERE conditionnelle au fichier de définition SQLX de la table incrémentielle. 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 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: instruction SELECT qui définit votre table.
    • INCREMENTAL_CONDITION: condition que vous spécifiez dans la clause WHERE pour sélectionner les lignes que Dataform doit traiter lors de l'exécution de la table sans actualisation complète.
    • NON_INCREMENTAL_CONDITION: condition que vous spécifiez dans la clause WHERE pour sélectionner les lignes que Dataform doit traiter lors de l'exécution de la table avec une actualisation complète.

  5. 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 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 des lignes dans un tableau incrémentiel

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

Pour configurer la fusion dans un tableau incrémentiel, 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 d'une colonne sélectionnée.

  5. (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'un tableau incrémentiel

Dans un tableau partitionné par incréments, pour éviter que Dataform analyse l'ensemble du tableau afin de trouver les lignes correspondantes, définissez updatePartitionFilter pour ne prendre en compte qu'un sous-ensemble d'enregistrements.

L'exemple de code suivant montre une table partitionnée incrémentielle avec la fusion 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 de table complètes 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 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 à l'aide d'une expression constante dans votre requête de table. Pour transformer une valeur de la table partitionnée en expression constante, utilisez le script BigQuery pour déclarer la valeur en tant que variable dans le bloc pre_operations. Utilisez ensuite la variable comme 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'ensemble de la table.

Pour configurer une table incrémentielle qui fait référence à une table partitionnée et évite les analyses complètes de la table, 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éclarez une variable avec le script BigQuery.
  5. Filtrez 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 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 comme expression constante dans la clause WHERE.

Recréer une table incrémentielle à partir de zéro avec une actualisation complète

Vous pouvez forcer la recréation d'une table incrémentielle à partir de zéro à l'aide de l'interface de ligne de commande avec l'option --full-refresh ou de l'option Exécuter avec actualisation complète lorsque vous déclenchez l'exécution d'un 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 une actualisation complète

Pour éviter qu'une table incrémentielle ne soit recréée à partir de zéro et qu'elle ne perde des données, vous pouvez définir la table incrémentielle sur protected. Vous pouvez empêcher la recréation 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 un tableau incrémentiel marqué comme protected:

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

Ajouter la documentation du tableau

Cette section explique comment ajouter des descriptions d'une table, de ses colonnes et de ses enregistrements à un fichier SQLX de base Dataform.

Vous pouvez ajouter des descriptions de table, de colonne et d'enregistrement à tous les types de tableaux dans Dataform: tableaux, tableaux incrémentaux et vues.

Vous pouvez documenter les éléments suivants:

  • Objectif de la table.
  • Contenu ou rôle des colonnes ou des enregistrements du tableau.
  • Relation entre le tableau et les autres actions de votre workflow, par exemple les tables ou les vues qui dépendent du tableau actuel.
  • Les assertions appliquées au tableau.
  • Les pré-opérations ou post-opérations appliquées à la table.
  • Propriétaire de la table, c'est-à-dire l'utilisateur qui l'a créée. Ces informations peuvent être utiles si plusieurs membres de l'équipe travaillent sur un workflow.

Ajouter une description de la table

Pour ajouter une description à une table dans un fichier SQLX, procédez comme suit:

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

    Accéder à Dataform

  2. Sélectionnez un dépôt.

  3. Sélectionnez un espace de travail de développement.

  4. Dans le volet Fichiers, cliquez sur le fichier SQLX de définition de table que vous souhaitez modifier.

  5. Dans le bloc config du fichier, saisissez la description de la table au format suivant:

    description: "Description of the table",

  6. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une description de table ajoutée au bloc config d'un fichier de définition de table SQLX:

config {
  type: "table",
  description: "Description of the table",
 }

Ajouter des descriptions de colonnes et d'enregistrements

Pour ajouter des descriptions de colonnes et d'enregistrements individuels à un fichier SQLX, procédez comme suit:

  1. Dans le bloc config de votre fichier de définition de table, saisissez columns: {}.

  2. Dans columns: {}, saisissez les descriptions des colonnes au format suivant:

    column_name: "Description of the column",

  3. Dans columns: {}, saisissez les descriptions des enregistrements au format suivant:

      record_name: {
      description: "Description of the record",
      columns: {
        record_column_name: "Description of the record column"
      }
}

  4. Facultatif: cliquez sur Format.

L'exemple de code suivant montre les descriptions de la table, des colonnes et des enregistrements dans le bloc config d'un fichier de définition de table SQLX:

config {
  type: "table",
  description: "Description of the table.",
  columns: {
    column1_name: "Description of the first column",
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    record_name: {
      description: "Description of the record.",
      columns: {
       record_column1_name: "Description of the first record column",
       record_column2_name: "Description of the second record column",
      }
    }
  }
}
SELECT
  "first_column_value" AS column_1_name,
  "second_column_value" AS column_2_name,
  "third_column_value" AS column_3_name,
  STRUCT("first" AS record_column1_name,
    "second" AS record_column2_name) AS record_name

Réutiliser la documentation des colonnes avec des inclusions

Vous pouvez réutiliser les descriptions des colonnes dans Dataform dans votre workflow SQL à l'aide d'inclusions JavaScript. Vous pouvez réutiliser la documentation des colonnes si vous avez plusieurs colonnes avec le même nom et la même description dans votre workflow SQL.

Vous pouvez définir une constante avec la description d'une seule colonne, ou une constante avec une description de l'ensemble ou de la colonne pour réutiliser les descriptions de toutes les colonnes d'une table. Pour en savoir plus sur la création et l'utilisation d'inclusions dans Dataform, consultez la section Réutiliser du code dans un seul dépôt avec des inclusions.

L'exemple de code suivant présente plusieurs constantes avec des descriptions de colonnes individuelles définies dans le fichier JavaScript includes/docs.js:


// filename is includes/docs.js

const user_id = `A unique identifier for a user`;
const age = `The age of a user`;
const creation_date = `The date this user signed up`;
const user_tenure = `The number of years since the user's creation date`;
const badge_count = `The all-time number of badges the user has received`;
const questions_and_answer_count = `The all-time number of questions and answers the user has created`;
const question_count = `The all-time number of questions the user has created`;
const answer_count = `The all-time number of answers the user has created`;
const last_badge_received_at = `The time the user received their most recent badge`;
const last_posted_at = `The time the user last posted a question or answer`;
const last_question_posted_at = `The time the user last posted an answer`;
const last_answer_posted_at = `The time the user last posted a question`;

module.exports = {
   user_id,
   age,
   creation_date,
   user_tenure,
   badge_count,
   questions_and_answer_count,
   question_count,
   answer_count,
   last_badge_received_at,
   last_posted_at,
   last_question_posted_at,
   last_answer_posted_at,
};

L'exemple de code suivant montre les constantes user_id et age, définies dans includes/docs.js, utilisées dans le fichier de définition de table SQLX definitions/my_table.sqlx pour générer de la documentation pour les colonnes sélectionnées dans la table:

config {
  type: "table",
  description: "Table description.",
  columns: {
    user_id: docs.user_id,
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    age: docs.age,
  }
}

SELECT ...

L'exemple de code suivant montre une constante avec un ensemble de descriptions de colonnes définies dans le fichier JavaScript includes/docs.js:


// filename is includes/docs.js

const columns = {
    user_id = `A unique identifier for a user`,
    age = `The age of a user`,
    creation_date = `The date this user signed up`,
    user_tenure = `The number of years since the user's creation date`,
    badge_count = `The all-time number of badges the user has received`,
    questions_and_answer_count = `The all-time number of questions and answers the user has created`,
    question_count = `The all-time number of questions the user has created`,
    answer_count = `The all-time number of answers the user has created`,
    last_badge_received_at = `The time the user received their most recent badge`,
    last_posted_at = `The time the user last posted a question or answer`,
    last_question_posted_at = `The time the user last posted an answer`,
    last_answer_posted_at = `The time the user last posted a question`,
}


module.exports = {
  columns
};

L'exemple de code suivant montre la constante columns, qui est définie dans includes/table_docs.js et utilisée dans le fichier de définition de table SQLX definitions/my_table.sqlx pour générer de la documentation pour toutes les colonnes de la table:

config { type: "table",
description: "My table description",
columns: docs.columns
}

SELECT 1 AS one

Étape suivante