Structurer le code dans un dépôt

Ce document décrit les bonnes pratiques à suivre 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 qui répond aux besoins de votre entreprise.

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

  • Améliorez la collaboration sur le codebase en désignant des équipes pour certaines parties de votre workflow.
  • Amélioration de la facilité de maintenance du workflow SQL en cas de modifications organisationnelles.
  • Améliorer la navigation dans votre codebase
  • Amélioration de l'évolutivité du codebase.
  • Réduire les 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 qui reflète 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 analytiques.

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 suivante des sous-répertoires 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, filtrage).
intermediate
Tables et actions qui lisent à partir de sources et transforment les données avant de les utiliser pour définir des tables outputs. Les tables ne sont généralement pas exposées à des processus ou outils supplémentaires, tels que des outils d'informatique décisionnelle (BI), après leur exécution dans BigQuery par Dataform.
outputs
Définitions des tables utilisées par des processus ou des outils, tels que l'analyse BI, après leur exécution par Dataform dans BigQuery.
extra
Fichiers en dehors du pipeline principal de votre workflow SQL, par exemple, des fichiers contenant des données de workflow préparées pour une utilisation supplémentaire, comme le machine learning. Sous-répertoire facultatif et personnalisé.

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 sources de données et les tables qui filtrent, catégorisent, castent ou renomment des colonnes.

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

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

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

L'exemple suivant montre une structure de sous-répertoire 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 regrouper leurs déclarations dans un seul fichier JavaScript. a Pour en savoir plus sur la création de déclarations de sources de données avec JavaScript, consultez Créer des workflows Dataform avec JavaScript.

L'exemple de code suivant montre plusieurs sources de données dans 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 la source de données, vous pouvez créer une vue pour chaque déclaration de source de données, par exemple analytics_users_filtered.sqlx. La vue 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 plutôt que les tables sources brutes. Cette approche vous permet de tester les tables sources. Si une table source change, vous pouvez modifier sa vue, par exemple en ajoutant des filtres ou en recalculant les données.

Bonnes pratiques pour intermediate

Le sous-répertoire intermediate contient la deuxième étape de votre workflow SQL : la transformation et l'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 associent des données). Les tables du sous-répertoire intermediate interrogent généralement les données des 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 des 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 la dernière étape de votre workflow SQL : la création de 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 des processus ou des outils supplémentaires 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 associé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é pour les tables de sortie. Pour savoir comment configurer le schéma de table, consultez la section Configurer des paramètres de table supplémentaires.

L'exemple suivant montre une structure de sous-répertoire de outputs avec des entités commerciales sales et marketing:

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 de Dataform doivent respecter les consignes de dénomination des tables BigQuery.

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

Dans le sous-répertoire sources, les noms de fichiers doivent pointer vers la source à laquelle le 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 distinguer clairement les fichiers intermediate. Sélectionnez un préfixe unique et ne l'appliquez qu'aux fichiers du répertoire intermediate. Par 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 le même nom 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 de dénomination 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

Étape suivante