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
- Présentation de la taille des dépôts
- Diviser les dépôts
- Structurer le code dans un dépôt
- Bonnes pratiques pour la compilation et la planification
Présentation des bonnes pratiques concernant les dépôts dans Dataform
Cette section présente les bonnes pratiques à suivre 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, par exemple :
- Collaboration
- Lisibilité du codebase
- Processus de développement
- Compilation de workflows
- Exécution du workflow
Dataform applique des quotas et des limites d'API aux ressources de compilation. Si votre dépôt est volumineux, il peut dépasser ces quotas et limites. Cela peut entraîner l'échec de la compilation et de l'exécution de votre workflow.
Pour limiter ce risque, nous vous recommandons de diviser les dépôts volumineux. Lorsque vous divisez un dépôt volumineux, vous divisez un workflow volumineux 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 limites de Dataform, d'implémenter des processus et des autorisations précis, et d'améliorer la lisibilité du codebase et la collaboration. Toutefois, la gestion de dépôts fractionnés peut être plus difficile que la gestion d'un dépôt unique.
Pour en savoir plus sur l'impact de la taille des dépôts dans Dataform, consultez Présentation de la taille des dépôts. Pour en savoir plus sur les bonnes pratiques concernant la division des dépôts, consultez Diviser des dépôts.
Bonnes pratiques pour la structure des dépôts
Nous vous recommandons de structurer les fichiers du répertoire definitions de manière à refléter les étapes de votre workflow. N'oubliez pas que vous pouvez adopter une structure personnalisée qui répond au mieux à vos besoins.
La structure recommandée de sous-répertoires definitions suivante reflète les étapes clés de la plupart des workflows :
sourcespour stocker les déclarations de sources de données.intermediatepour stocker la logique de transformation des données.outputpour 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 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.
Pour en savoir plus sur les bonnes pratiques de structuration et de 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 comprend les phases suivantes :
Développement du code de workflow dans les espaces de travail Dataform.
Vous pouvez développer avec Dataform Core ou exclusivement avec JavaScript.
Compilation de votre code dans un résultat de compilation à l'aide des paramètres de votre fichier de paramètres de workflow.
Vous pouvez configurer des résultats de compilation personnalisés avec des configurations de version et des remplacements de compilation d'espace de travail.
Les configurations de version vous permettent de configurer des résultats de compilation personnalisés pour l'ensemble de votre dépôt. Vous pouvez planifier leur exécution ultérieurement dans les configurations de workflow.
Les remplacements de compilation d'espace de travail vous permettent de configurer des remplacements de compilation pour tous les espaces de travail de votre dépôt, en créant des résultats de compilation personnalisés pour chaque espace de travail.
Exécution du résultat de la compilation dans BigQuery.
Vous pouvez planifier des exécutions ou des résultats de compilation de dépôt avec des configurations de workflow.
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 dépôts.
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 par projet Google Cloud .
- Séparez les tables de développement, de préproduction et de production par projet Google Cloud .
Vous pouvez ensuite planifier des exécutions dans des environnements de préproduction et de production avec des configurations de workflow. Nous vous recommandons de déclencher les exécutions manuellement 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 (par exemple, le développement et la production).
Dans cette approche, nous vous recommandons de conserver la même codebase du dépôt dans tous les projets. Pour personnaliser la compilation et l'exécution dans chaque copie du dépôt, utilisez des remplacements de compilation d'espace de travail, des configurations de version et des configurations de workflow.
Présentation de la taille des dépôts
Cette section vous aide à comprendre l'impact de la taille du dépôt sur le développement des workflows et l'utilisation des ressources de compilation Dataform, et à 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 :
La collaboration. Plusieurs collaborateurs travaillant sur un dépôt volumineux peuvent créer un nombre excessif de demandes d'extraction, ce qui augmente le risque de conflits de fusion.
Lisibilité du codebase Un grand nombre de fichiers composant un workflow dans un seul dépôt peut rendre la navigation dans le dépôt difficile.
Processus de développement Certaines zones d'un workflow volumineux dans un dépôt unique 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. Un dépôt de grande taille complique 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 entraîne l'échec de la compilation.
Exécution du workflow Pendant l'exécution, Dataform exécute le code du dépôt dans votre espace de travail et déploie les éléments dans BigQuery. Plus le dépôt est volumineux, plus Dataform met de temps à l'exécuter.
Si la taille importante de votre dépôt a un impact négatif sur votre développement dans Dataform, vous pouvez diviser le dépôt en plusieurs dépôts plus petits.
À propos des limites de ressources de compilation des dépôts
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, contenant 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.
- Utilisation de la durée d'exécution.
- Taille maximale totale des données sérialisées du graphique d'actions généré défini dans votre dépôt.
Pour obtenir une approximation du temps de compilation actuel 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 de la CLI Dataform
dataform compileau format suivant dans votre dépôt :time dataform compileL'exemple de code suivant montre le 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 la durée d'exécution et le résultat user comme un indicateur approximatif du temps CPU utilisé pour la compilation de votre dépôt.
Pour obtenir une approximation 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 un indicateur approximatif de la taille totale du graphique.
Pour écrire la sortie du graphe compilé de votre workflow dans un fichier JSON, exécutez la commande de la CLI Dataform suivante dans votre dépôt :
dataform compile --json > graph.json
Diviser des dépôts
Cette section traite des stratégies de division d'un dépôt Dataform et de gestion des 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 de ressources de compilation Dataform. La division d'un workflow volumineux en plusieurs dépôts plus petits réduit le risque de dépassement des limites de Dataform concernant les ressources de compilation.
- Processus de réglage précis. 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 individuellement 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 réduisant le nombre de collaborateurs travaillant sur chaque fragment de votre workflow.
- Améliorer la lisibilité du codebase En divisant les fichiers qui composent un workflow volumineux en plusieurs dépôts, 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 de votre workflow par rapport à l'exécution de l'ensemble du workflow.
La division d'un dépôt dans Dataform présente les inconvénients suivants :
- Configuration personnalisée d'intégration continue et de développement continus (CI/CD) requise pour chaque dépôt Dataform et son dépôt Git correspondant.
- Configuration de planification personnalisée 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 de division d'un dépôt
Lorsque vous divisez un dépôt, vous divisez 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 (par exemple, ventes, marketing ou logistique).
- Un dépôt central et un dépôt par domaine qui utilise le contenu du dépôt central comme sources 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 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 laquelle 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 des déclarations de source de données Dataform. Vous pouvez déclarer un type de table BigQuery d'un autre dépôt Dataform en tant que source de données dans le dépôt en cours de modification. Après avoir déclaré une source de données, vous pouvez la référencer 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 des dépôts se produit lorsqu'un dépôt est une source de données pour un autre dépôt et qu'il 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 n'importe quelle structure adaptée 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élioration de la facilité de maintenance du workflow en cas de changements organisationnels.
- Améliorer la navigation dans votre codebase.
- Amélioration de l'évolutivité du codebase.
- Réduire les frais administratifs pour votre équipe.
Structure recommandée du répertoire definitions
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.
On peut distinguer trois étapes clés dans un workflow :
- Déclaration des sources de données.
- Transformation des données sources.
- 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 (par exemple, filtrage).
intermediate- Tables et actions qui lisent les données de
sourceset les transforment avant que vous n'utilisiez les données transformées pour définir des tablesoutputs. Tables qui ne sont généralement pas exposées à des processus ou des outils supplémentaires, tels que des outils d'informatique décisionnelle (BI), après que Dataform les a exécutées dans BigQuery. outputs- Définitions des tables utilisées par des processus ou des outils, tels que la BI, après leur exécution par Dataform dans BigQuery.
extra- Fichiers en dehors du pipeline principal de votre workflow, par exemple des fichiers contenant des données de workflow préparées pour une utilisation supplémentaire, comme le machine learning. Un sous-répertoire personnalisé facultatif.
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 les 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), dédiez 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.
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 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 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 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 refondant les 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 d'une ou de plusieurs sources du 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 de données) après 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 : la création de tables de sortie pour vos besoins métier à partir des 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 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 analyses. 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 Remplacer les paramètres de table.
L'exemple suivant montre une structure de sous-répertoire 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 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 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 distinguer clairement 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 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
Bonnes pratiques pour la compilation et la planification
Lorsque vous configurez des exécutions planifiées et des workflows d'orchestration pour votre dépôt, suivez ces bonnes pratiques pour garantir une compilation fiable :
- Utiliser des configurations de version pour les exécutions de production planifiées : une configuration de version compile le code de votre dépôt selon un calendrier prévisible et stocke le résultat de la compilation. Lorsque vos pipelines d'exécution de production s'exécutent, ils s'exécutent immédiatement sur ce résultat enregistré sans lancer de requêtes réseau vers votre dépôt Git distant.
- Limitez la compilation de commitish aux tâches de développement et à faible fréquence : l'appel de
CreateCompilationResultdirectement sur un commitish Git, tel qu'une branche, un tag ou un SHA de commit, nécessite que Dataform clone le dépôt sur le réseau à chaque appel. Évitez de configurer des jobs Cron de production ou des DAG d'orchestration pour compiler de manière répétée à partir d'un commitish Git à des fréquences élevées. - Configurez des nouvelles tentatives automatiques et des planifications échelonnées : si votre architecture nécessite une compilation à partir d'un commitish Git dans des planificateurs externes, configurez des nouvelles tentatives automatiques avec un intervalle exponentiel entre les tentatives et échelonnez les minuteurs cron simultanés. Pour obtenir des exemples de code de nouvelle tentative détaillés et des instructions de dépannage, consultez Impossible d'accéder au dépôt distant.
Étapes suivantes
- Pour en savoir plus sur le cycle de vie du code dans Dataform et les différentes façons de le configurer, consultez Présentation du cycle de vie du code dans Dataform.
- Pour en savoir plus sur les bonnes pratiques concernant le cycle de vie des workflows, consultez Bonnes pratiques concernant le cycle de vie des workflows.
- Pour en savoir plus sur les limites de ressources de compilation, consultez Limites de ressources de compilation Dataform.
- Pour savoir comment connecter un dépôt Dataform à un dépôt Git tiers, consultez Se connecter à un dépôt Git tiers.
- Pour en savoir plus sur les workflows dans Dataform, consultez Présentation des workflows.