Bonnes pratiques concernant les dépôts

Ce document présente les informations suivantes sur les dépôts Dataform :

Présentation des bonnes pratiques concernant les dépôts dans Dataform

Cette section présente les bonnes pratiques pour gérer la taille et la structure des dépôts, ainsi que le cycle de vie du code dans Dataform.

Bonnes pratiques concernant la taille des dépôts

La taille du dépôt a un impact sur plusieurs aspects du développement dans Dataform, tels que les suivants :

  • Collaboration
  • Lisibilité du codebase
  • Processus de développement
  • Compilation des workflows
  • Exécution du workflow

Dataform applique des quotas et des limites d'API aux ressources de compilation. Si la taille de votre dépôt est importante, il est possible qu'il dépasse ces quotas et limites. Cela peut entraîner l'échec de la compilation et de l'exécution de votre workflow.

Pour atténuer ce risque, nous vous recommandons de diviser les grands dépôts. Lorsque vous fractionnez un grand dépôt, vous divisez un grand workflow en plusieurs workflows plus petits hébergés dans différents dépôts et connectés par des dépendances entre dépôts.

Cette approche vous permet de respecter les quotas et les limites de Dataform, d'implémenter des processus et des autorisations précis, et d'améliorer la lisibilité et la collaboration du code. Toutefois, la gestion des dépôts fractionnés peut être plus difficile que celle d'un seul dépôt.

Pour en savoir plus sur l'impact de la taille du dépôt dans Dataform, consultez Présentation de la taille du dépôt. Pour en savoir plus sur les bonnes pratiques concernant la division des dépôts, consultez Diviser les dépôts.

Bonnes pratiques pour la structure des dépôts

Nous vous recommandons de structurer les fichiers du répertoire definitions pour refléter les étapes de votre workflow. N'oubliez pas que vous pouvez adopter une structure personnalisée qui répond le mieux à vos besoins.

La structure recommandée suivante des sous-répertoires definitions reflète les étapes clés de la plupart des workflows :

  • sources pour stocker les déclarations de sources de données.
  • intermediate pour stocker la logique de transformation des données.
  • output pour stocker les définitions des tables de sortie.
  • extras (facultatif) pour stocker des fichiers supplémentaires.

Les noms de tous les fichiers dans Dataform doivent respecter les consignes de dénomination des table 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.

Pour en savoir plus sur les bonnes pratiques concernant la structuration et la dénomination des fichiers dans un dépôt, consultez Structurer le code dans un dépôt.

Bonnes pratiques pour le cycle de vie du code

Le cycle de vie du code par défaut dans Dataform se compose des phases suivantes :

Pour gérer le cycle de vie du code dans Dataform, vous pouvez créer des environnements d'exécution tels que le développement, la préproduction et la production.

Pour en savoir plus sur le cycle de vie du code dans Dataform, consultez Présentation du cycle de vie du code dans Dataform.

Vous pouvez choisir de conserver vos environnements d'exécution dans un seul dépôt ou dans plusieurs.

Environnements d'exécution dans un seul dépôt

Vous pouvez créer des environnements d'exécution isolés tels que le développement, la préproduction et la production dans un seul dépôt Dataform avec des remplacements de compilation d'espace de travail et des configurations de version.

Vous pouvez créer des environnements d'exécution isolés de différentes manières :

  • Séparez les tables de développement et de production par schéma.
  • Séparez les tables de développement et de production par schéma et projet Google Cloud .
  • Répartissez les tables de développement, de préproduction et de production par Google Cloud projet.

Vous pouvez ensuite planifier des exécutions dans les environnements de préproduction et de production à l'aide des configurations de workflow. Nous vous recommandons de déclencher manuellement les exécutions dans l'environnement de développement.

Pour en savoir plus sur les bonnes pratiques de gestion du cycle de vie des workflows dans Dataform, consultez Bonnes pratiques pour le cycle de vie des workflows.

Cycle de vie du code dans plusieurs dépôts

Pour adapter les autorisations Identity and Access Management à chaque étape du cycle de vie du code, vous pouvez créer plusieurs copies d'un dépôt et les stocker dans différents projets Google Cloud .

Chaque projet Google Cloud sert d'environnement d'exécution correspondant à une étape du cycle de vie de votre code (développement et production, par exemple).

Dans cette approche, nous vous recommandons de conserver la même base de code du dépôt dans tous les projets. Pour personnaliser la compilation et l'exécution dans chaque copie du dépôt, utilisez les remplacements de compilation d'espace de travail, les configurations de version et les configurations de workflow.

Présentation de la taille du dépôt

Cette section vous aide à comprendre l'impact de la taille du dépôt sur le développement du workflow et l'utilisation des ressources de compilation Dataform. Elle vous explique également comment estimer l'utilisation des ressources de compilation de votre dépôt.

À propos de la taille des dépôts dans Dataform

La taille d'un dépôt a un impact sur les aspects suivants du développement dans Dataform :

  • Collaboration : Plusieurs collaborateurs travaillant sur un grand dépôt peuvent créer un nombre excessif de demandes d'extraction, ce qui augmente le risque de conflits de fusion.

  • Lisibilité de la codebase Un grand nombre de fichiers constituant un workflow dans un même dépôt peut rendre la navigation difficile.

  • Processus de développement : Certaines zones d'un grand workflow dans un seul dépôt peuvent nécessiter des autorisations ou des processus personnalisés, tels que la planification, qui sont différents des autorisations et des processus appliqués au reste du workflow. Une grande taille de dépôt rend difficile l'adaptation des processus de développement à des domaines spécifiques du workflow.

  • Compilation de workflows Dataform applique des limites d'utilisation aux ressources de compilation. Une taille de dépôt importante peut entraîner le dépassement de ces limites, ce qui provoque l'échec de la compilation.

  • Exécution du workflow : Lors de l'exécution, Dataform exécute le code du dépôt dans votre espace de travail et déploie les composants dans BigQuery. Plus le dépôt est volumineux, plus Dataform met de temps à l'exécuter.

Si la grande taille de votre dépôt a un impact négatif sur votre développement dans Dataform, vous pouvez le diviser en plusieurs dépôts plus petits.

À propos des limites de ressources de compilation de dépôt

Pendant le développement, Dataform compile tout le code du dépôt dans votre espace de travail pour générer une représentation du workflow dans votre dépôt. C'est ce qu'on appelle un résultat de compilation. Dataform applique des limites d'utilisation aux ressources de compilation.

Votre dépôt peut dépasser les limites d'utilisation pour les raisons suivantes :

  • Un bug de boucle infinie dans le code du dépôt.
  • Un bug de fuite de mémoire dans le code du dépôt.
  • Un dépôt de grande taille, avec environ plus de 1 000 actions de workflow.

Pour en savoir plus sur les limites d'utilisation des ressources de compilation, consultez Limites des ressources de compilation Dataform.

Estimer l'utilisation des ressources de compilation de votre dépôt

Vous pouvez estimer l'utilisation des ressources de compilation suivantes pour votre dépôt :

  • Utilisation du temps CPU.
  • Taille totale maximale des données sérialisées du graphique d'actions généré défini dans votre dépôt.

Pour obtenir une approximation approximative de l'utilisation actuelle du temps de compilation du processeur pour la compilation de votre dépôt, vous pouvez chronométrer la compilation de votre workflow Dataform sur une machine Linux ou macOS locale.

  • Pour chronométrer la compilation de votre workflow, exécutez la commande CLI Dataform dataform compile dans le format suivant à l'intérieur de votre dépôt :

    time dataform compile

    L'exemple de code suivant montre un résultat de l'exécution de la commande time dataform compile :

    real    0m3.480s
user    0m1.828s
sys     0m0.260s

Vous pouvez considérer le résultat real comme un indicateur approximatif de l'utilisation du temps CPU pour la compilation de votre dépôt.

Pour obtenir une approximation approximative de la taille totale du graphique d'actions généré dans votre dépôt, vous pouvez écrire la sortie du graphique dans un fichier JSON. Vous pouvez considérer la taille du fichier JSON non compressé comme une indication approximative de la taille totale du graphique.

  • Pour écrire la sortie du graphique compilé de votre workflow dans un fichier JSON, exécutez la commande CLI Dataform suivante dans votre dépôt :

    dataform compile --json > graph.json

Fractionner des dépôts

Cette section présente des stratégies pour diviser un dépôt Dataform et gérer les dépendances entre dépôts.

Les dépôts sont les unités de base de Dataform. Un dépôt stocke tous les fichiers SQLX et JavaScript qui composent votre workflow, ainsi que les packages et fichiers de configuration Dataform. Vous pouvez stocker un workflow dans un seul dépôt ou le répartir entre plusieurs dépôts.

La division d'un dépôt dans Dataform présente les avantages suivants :

  • Respecter les limites d'utilisation des ressources de compilation Dataform. En divisant un workflow volumineux en plusieurs dépôts plus petits, vous réduisez le risque de dépasser les limites de Dataform concernant les ressources de compilation.
  • Processus de précision. Vous pouvez définir des processus, tels que des règles d'intégration continue (CI), individuellement pour chaque fragment de votre workflow et pour l'équipe qui le développe.
  • Affiner les autorisations. Vous pouvez définir des autorisations individuelles pour chaque fragment de votre workflow et pour l'équipe qui le développe afin d'améliorer la sécurité globale du workflow.
  • Améliorer la collaboration en minimisant le nombre de collaborateurs travaillant sur chaque fragment divisé de votre workflow.
  • Amélioration de la lisibilité du codebase. Il est plus facile de parcourir chaque dépôt individuellement que de parcourir l'ensemble du workflow en une seule fois.
  • Accélérer l'exécution du workflow de chaque fragment divisé par rapport à l'exécution de l'intégralité du workflow.

La division d'un dépôt dans Dataform présente les inconvénients suivants :

  • Une configuration personnalisée d'intégration continue et de développement continus (CI/CD) est requise pour chaque dépôt Dataform et son dépôt Git correspondant.
  • Une configuration de planification personnalisée est requise pour chaque dépôt Dataform et son dépôt Git correspondant.
  • Difficulté à gérer les dépendances entre les objets de votre workflow hébergés dans plusieurs dépôts.
  • Manque de visualisation complète du graphe orienté acyclique (DAG) du workflow SQL réparti entre plusieurs dépôts. Dans chaque dépôt, le DAG généré ne représente qu'une partie du workflow complet.

Stratégies pour scinder un dépôt

Lorsque vous divisez un dépôt, vous répartissez les fichiers qui composent un workflow SQL parent en workflows enfants plus petits, hébergés dans des dépôts Dataform distincts.

Vous pouvez choisir de diviser un dépôt de l'une des manières suivantes :

  • Un dépôt par équipe de développement.
  • Un dépôt par domaine (ventes, marketing ou logistique, par exemple).
  • Un dépôt central et un dépôt par domaine qui utilise le contenu du dépôt central comme source de données.

Pour héberger le workflow parent sur une plate-forme d'hébergement Git tierce, vous devez connecter individuellement chacun des dépôts distincts contenant des workflows enfants à un dépôt Git tiers dédié.

Gérer les dépendances entre dépôts

Le moyen le plus efficace de diviser un dépôt consiste à diviser le workflow SQL parent en workflows enfants autonomes, en créant des dépôts indépendants. Un dépôt indépendant n'utilise pas le contenu d'un autre dépôt comme source de données. Cette approche ne nécessite pas de gérer les dépendances entre les dépôts.

Lorsque vous ne pouvez pas éviter les dépendances entre dépôts, vous pouvez les gérer en divisant un dépôt en une succession de dépôts, dans lesquels un dépôt dépend de son prédécesseur et constitue une source de données pour son successeur. La succession des dépôts et de leurs dépendances doit refléter au mieux la structure de votre workflow parent.

Vous pouvez créer des dépendances entre les dépôts avec les déclarations de sources de données Dataform. Vous pouvez déclarer un type de table BigQuery provenant d'un autre dépôt Dataform comme source de données dans le dépôt en cours de modification. Une fois que vous avez déclaré une source de données, vous pouvez y faire référence comme à n'importe quelle autre action de workflow Dataform et l'utiliser pour développer votre workflow.

Lorsque vous planifiez l'exécution d'un workflow réparti entre des dépôts avec des dépendances entre dépôts, vous devez exécuter les dépôts un par un dans l'ordre des dépendances entre dépôts.

Nous vous recommandons d'éviter de diviser un dépôt en un groupe de dépôts avec des dépendances bidirectionnelles. Une dépendance bidirectionnelle entre les dépôts se produit lorsqu'un dépôt est une source de données pour un autre dépôt et utilise également ce dépôt comme source de données. Les dépendances bidirectionnelles entre les dépôts compliquent la planification et l'exécution du workflow parent, ainsi que les processus de développement.

Structurer le code dans un dépôt

Cette section décrit les bonnes pratiques pour structurer et nommer les fichiers de workflow 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. Vous pouvez adopter la structure qui répond le mieux aux besoins de votre entreprise.

Vous pouvez structurer le code du workflow 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 facilité de maintenance du workflow en cas de changements organisationnels.
  • Améliorer la navigation dans votre base de code.
  • Améliorer l'évolutivité du codebase.
  • Réduire les frais administratifs pour votre équipe.

Le répertoire racine definitions d'un dépôt Dataform contient le code qui crée les éléments de votre workflow. 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, 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.

Un workflow peut être divisé en trois étapes clés :

  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 :

sources
Déclarations de sources de données et transformation de base des données sources (filtrage, par exemple).
intermediate
Tables et actions qui lisent les données de sources et les transforment avant que vous n'utilisiez les données transformées pour définir les tables outputs. Tables qui ne sont généralement pas exposées à des processus ou outils supplémentaires, tels que les outils de informatique décisionnelle (BI), après que Dataform les a exécutées dans BigQuery.
outputs
Définitions des tables utilisées par les processus ou les outils, tels que la BI, après que Dataform les a exécutées dans BigQuery.
extra
Fichiers
en dehors du pipeline principal de votre workflow, par exemple les 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 : 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 les 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), consacrez un sous-répertoire à chaque pool.

L'exemple suivant montre une structure de sous-répertoires de sources avec deux pools de 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.

Pour en savoir plus sur la création de déclarations de sources de données avec JavaScript, consultez Créer des workflows exclusivement 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 contre les modifications apportées aux 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). La vue peut contenir le filtrage et la 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 change, vous pouvez modifier sa vue, par exemple en ajoutant des filtres ou en modifiant le type de données.

Bonnes pratiques pour intermediate

Le sous-répertoire intermediate contient la deuxième étape de votre workflow : 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 provenant 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 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, 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 : la création de tables de sortie à des fins commerciales à partir des données transformées.

Dans le répertoire outputs, stockez les tables que vous prévoyez d'utiliser dans des processus ou outils supplémentaires après que Dataform les a exécutées 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 par entité commerciale à laquelle elles sont associées (par exemple, marketing, commandes ou analytics). Consacrez 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 un schéma de table, consultez Remplacer les paramètres de table.

L'exemple suivant montre une structure de sous-répertoires de outputs avec les 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 de dénomination

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

Nous vous recommandons de faire en sorte 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 clairement distinguer les fichiers intermediate. Sélectionnez un préfixe unique et appliquez-le uniquement 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 ou ads_revenue.sqlx).

L'exemple suivant montre une structure de sous-répertoires à l'intérieur du 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

Étapes suivantes