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:
- les tables de tous les types de tables compatibles ;
- déclarations de sources de données ;
- Opérations SQL personnalisées avec la propriété
hasOutput
définie surtrue
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
- Créez et initialisez un espace de travail de développement dans votre dépôt.
- 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:
Dans Cloud Console, accédez à la page Dataform.
Pour ouvrir un dépôt, cliquez sur son nom.
Pour ouvrir un espace de travail de développement, cliquez sur son nom.
Dans le volet Fichiers, à côté de
definitions/
, cliquez sur le menu Plus.Cliquez sur Créer un fichier.
Dans le champ Ajouter un chemin d'accès au fichier, saisissez le nom du fichier suivi de
.sqlx
aprèsdefinitions/
. 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.
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:
- Dans votre espace de travail de développement, dans le volet Fichiers, développez le répertoire
definitions/
. - Sélectionnez le fichier SQLX de définition de table que vous souhaitez modifier.
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
Facultatif: pour définir une vue matérialisée, saisissez la propriété
materialized
soustype: "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.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:
- Dans votre espace de travail de développement, dans le volet Fichiers, développez le répertoire
definitions/
. - Sélectionnez le fichier SQLX de définition de table que vous souhaitez modifier.
- Sous le bloc
config
, écrivez une instructionSELECT
. - 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:
- Dans votre espace de travail de développement, dans le volet Fichiers, développez le répertoire
definitions/
. - Sélectionnez le fichier SQLX de définition de table que vous souhaitez modifier.
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.
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
- Pour savoir comment configurer des tables incrémentielles, consultez la section Configurer des tables incrémentielles.
- Pour découvrir comment configurer des partitions et des clusters de tables, consultez la section Créer des partitions et des clusters de tables.
- Pour savoir comment ajouter de la documentation aux tableaux, consultez la section Ajouter de la documentation aux tableaux.
- Pour savoir comment tester les données de table à l'aide d'assertions, consultez la section Tester des tables à l'aide d'assertions.
- Pour savoir comment définir des tables avec JavaScript, consultez la page Créer des workflows Dataform avec JavaScript.
- Pour savoir comment configurer des paramètres de table supplémentaires, consultez la section Configurer des paramètres de table supplémentaires.