Créer une table

Ce document explique comment définir des tables avec Dataform Core 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 principal Dataform en SQL, exécute le code SQL et crée les tables que vous avez définies dans BigQuery.

Dans une instruction SELECT principale de Dataform, vous définissez une structure de table et faites référence à d'autres objets de votre workflow SQL.

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 les dépendances avec ref

Pour référencer un objet de workflow SQL 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 correct du pipeline.

La fonction ref est une fonction intégrée au cœur de Dataform. Elle est essentielle à la gestion des dépendances dans Dataform. La fonction ref vous permet de faire référence aux objets suivants définis dans votre workflow SQL Dataform et de les utiliser automatiquement au lieu de coder en dur les noms des schémas et des tables:

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

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

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 indiquez le nom de la table ou de la déclaration de la source de données dont vous souhaitez dépendre. Il s'agit généralement du nom du fichier SQLX dans lequel cette table ou cette déclaration de source de données est définie.

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

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

L'exemple de code suivant montre la fonction ref avec deux arguments permettant de 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 source de données ou les opérations SQL personnalisées qui ne sont pas référencées dans une fonction ref de 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 SQL, consultez la page 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 n'ajoute pas la référence en tant que dépendance. Cela signifie que l'objet référencé à l'aide de resolve n'affecte pas l'exécution de la table qui utilise resolve.

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

Avant de commencer

  1. Créez et initialisez un espace de travail de développement dans votre dépôt.
  2. Facultatif: déclarez une source de données.

Rôles requis

Afin d'obtenir les autorisations nécessaires pour définir une table, 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.

Créer un fichier SQLX pour définir une 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 Cloud, accédez à la page Dataform.

    Accéder à la page 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 le menu 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/. 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 Files (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 tables 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 documentation de référence de Dataform sur ITableConfig.

  5. (Facultatif) Cliquez sur Format.

Définir la structure et les dépendances des tables

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

  1. Dans votre espace de travail de développement, dans le volet Files (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 manuelles de table

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 Files (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 du tableau, 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" ] }

Étapes suivantes