Structurer du code dans un dépôt

Ce document décrit les bonnes pratiques pour structurer et nommer les fichiers de workflow SQL dans le répertoire racine definitions d'un dépôt Dataform. La structure recommandée du répertoire definitions reflète les étapes d'un workflow SQL. Vous pouvez adopter n'importe quelle structure adaptée aux besoins de votre entreprise.

Vous pouvez structurer le code du workflow SQL dans le répertoire definitions pour les raisons suivantes:

  • améliorer la collaboration sur le codebase en désignant des équipes pour certaines parties de votre workflow ;
  • Améliorer la gestion du workflow SQL en cas de changements organisationnels.
  • Amélioration de la navigation dans votre codebase
  • Amélioration de l'évolutivité du codebase
  • Réduction des frais administratifs pour votre équipe

Le répertoire racine definitions d'un dépôt Dataform contient du code qui crée des éléments de votre workflow SQL. Vous pouvez organiser les fichiers du répertoire definitions dans une structure de répertoires reflétant la structure du workflow.

Lorsque vous développez un workflow SQL, vous déclarez des tables sources et les transformez pour créer des tables de sortie que vous pouvez utiliser à des fins commerciales ou d'analyse.

Vous pouvez distinguer trois étapes clés d'un workflow SQL:

  1. Déclaration des sources de données
  2. Transformation des données sources
  3. Définition des tables de sortie à partir des données sources transformées

La structure de sous-répertoires suivante du répertoire definitions reflète les étapes clés d'un workflow SQL:

sources
Déclarations de sources de données et transformation de base des données sources, par exemple le filtrage
intermediate
Tables et actions qui lisent des données à partir de sources, et transforment les données avant d'utiliser les données transformées pour définir des tables outputs. Les tables ne sont généralement pas exposées à d'autres processus ou outils, tels que les outils d'informatique décisionnelle, une fois que Dataform les a exécutés dans BigQuery.
outputs
Définitions des tables consommées par les processus ou outils tels que l'informatique décisionnelle, une fois que Dataform les a exécutés dans BigQuery.
extra
Fichiers situés en dehors du pipeline principal de votre workflow SQL, tels que les fichiers contenant des données de workflow préparées pour une utilisation supplémentaire, comme le machine learning Sous-répertoire personnalisé et facultatif.

Bonnes pratiques pour sources

Le sous-répertoire sources contient la première étape de votre workflow SQL : la déclaration et la transformation de base des données sources.

Dans le sous-répertoire sources, stockez les déclarations de source de données et les tables qui filtrent, catégorisent, convertissent ou renomment des colonnes.

Évitez de stocker des tables qui combinent des données provenant de plusieurs sources.

Transformation des données sources dans des tables stockées dans le sous-répertoire intermediate.

Si vous déclarez des sources de données provenant de plusieurs pools (par exemple, Google Ads ou Google Analytics), dédiez un sous-répertoire à chaque pool.

L'exemple suivant présente une structure de sous-répertoires de sources avec deux pools sources:

definitions/
    sources/
        google_ads/
            google_ads_filtered.sqlx
            google_ads_criteria_metrics.sqlx
            google_ads_criteria_metrics_filtered.sqlx
            google_ads_labels.sqlx
            google_ads_labels_filtered.sqlx
        google_analytics/
            google_analytics_users.sqlx
            google_analytics_users_filtered.sqlx
            google_analytics_sessions.sqlx

Si vous déclarez plusieurs tables de sources de données dans le même schéma, vous pouvez consolider leurs déclarations dans un seul fichier JavaScript. Dans un fichier JavaScript, vous pouvez stocker plusieurs déclarations de source de données. Pour en savoir plus sur la création de déclarations de source de données avec JavaScript, consultez Créer des workflows Dataform SQL avec JavaScript.

L'exemple de code suivant montre plusieurs sources de données au sein d'un même schéma, déclarées dans un seul fichier JavaScript:

[
  "source_table_1",
  "source_table_2",
  "source_table_3"
].forEach((name) =>
  declare({
    database: "gcp_project",
    schema: "source_dataset",
    name,
  })
);

Pour protéger votre workflow SQL contre les modifications de sources de données, vous pouvez créer une vue pour chaque déclaration de source de données, par exemple analytics_users_filtered.sqlx. L'affichage peut contenir un filtrage et une mise en forme de base des données sources. Stockez les vues dans le sous-répertoire sources.

Ensuite, lorsque vous créez des tables intermediate ou outputs, référencez les vues au lieu des tables sources brutes. Cette approche vous permet de tester les tables sources. Si une table source est modifiée, vous pouvez modifier sa vue, par exemple en ajoutant des filtres ou en recastant les données.

Bonnes pratiques pour intermediate

Le sous-répertoire intermediate contient la deuxième étape de votre workflow SQL : transformation et agrégation des données sources provenant d'une ou de plusieurs sources.

Dans le sous-répertoire intermediate, stockez les fichiers qui transforment de manière significative les données sources d'une ou de plusieurs sources dans le sous-répertoire sources, par exemple les tables qui joignent des données. Les tables du sous-répertoire intermediate interrogent généralement les données de tables sources ou d'autres tables intermediate.

Utilisez des tables intermediate pour créer des tables outputs. En règle générale, les tables intermediate ne sont pas utilisées à d'autres fins, par exemple pour l'analyse de données, une fois que Dataform les a exécutées dans BigQuery. Vous pouvez considérer les tables intermediate comme la logique de transformation des données qui permet de créer des tables de sortie.

Nous vous recommandons de documenter et de tester toutes les tables intermediate.

Bonnes pratiques pour outputs

Le sous-répertoire outputs contient l'étape finale de votre workflow SQL, qui consiste à créer des tables de sortie à des fins commerciales à partir de données transformées.

Dans le répertoire outputs, stockez les tables que vous prévoyez d'utiliser dans d'autres processus ou outils après leur exécution par Dataform dans BigQuery (par exemple, des rapports ou des tableaux de bord). Les tables du répertoire outputs interrogent généralement les données des tables intermediate.

Regroupez les tables outputs en fonction de l'entité commerciale à laquelle elles sont liées (par exemple, le marketing, les commandes ou l'analyse). Dédiez un sous-répertoire à chaque entité commerciale.

Pour stocker les tables de sortie séparément dans BigQuery, vous pouvez configurer un schéma dédié aux tables de sortie. Pour savoir comment configurer un schéma de table, consultez Configurer des paramètres de table supplémentaires.

L'exemple suivant montre une structure de sous-répertoires de outputs avec deux entités commerciales:

definitions/
    outputs/
        orders/
            orders.sqlx
            returns.sqlx
        sales/
            sales.sqlx
            revenue.sqlx
        marketing/
            campaigns.sqlx

Nous vous recommandons de documenter et de tester toutes les tables outputs.

Stratégie d'attribution de noms

Les noms de tous les fichiers dans Dataform doivent respecter les consignes de dénomination des tables BigQuery.

Dans un dépôt Dataform, nous recommandons que les noms des fichiers du répertoire definitions reflètent la structure des sous-répertoires.

Dans le sous-répertoire sources, les noms de fichiers doivent pointer vers la source à laquelle ce fichier est associé. Ajoutez le nom de la source en tant que préfixe aux noms de fichiers, par exemple analytics_filtered.sqlx.

Dans le sous-répertoire intermediate, les noms de fichiers doivent identifier le sous-répertoire, afin que les collaborateurs puissent clairement distinguer les fichiers intermediate. Sélectionnez un préfixe unique et appliquez-le uniquement aux fichiers du répertoire intermediate. Exemple : stg_ads_concept.sqlx.

Dans le sous-répertoire outputs, les noms de fichiers doivent être concis, par exemple orders.sqlx. Si vous avez des tables outputs portant les mêmes noms dans différents sous-répertoires d'entités, ajoutez un préfixe qui identifie l'entité, par exemple, sales_revenue.sqlx et ads_revenue.sqlx.

L'exemple suivant montre une structure de sous-répertoires dans le répertoire definitions avec des noms de fichiers conformes à la stratégie d'attribution de noms recommandée:

definitions/
    sources/
        google_analytics.sqlx
        google_analytics_filtered.sqlx
    intermediate/
        stg_analytics_concept.sqlx
    outputs/
        customers.sqlx
        sales/
            sales.sqlx
            sales_revenue.sqlx
        ads/
            campaigns.sqlx
            ads_revenue.sqlx

Étapes suivantes