Créer une table

Ce document explique comment définir 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 de la table et référencez 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 des dépendances avec ref

Pour faire référence à 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 de pipeline correct.

La fonction ref est une fonction intégrée de base Dataform 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 SQL 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 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 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 vous avez plusieurs tables portant 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 SQL, 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 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'a aucune incidence sur l'exécution de la table qui utilise 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.

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

Pour obtenir les autorisations nécessaires pour définir une table, 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 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 Cloud Console, 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/. 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 documentation de référence de base sur ITableConfig Dataform.

  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" ] }

Étape suivante