Configuration du projet dbt GA4

Un projet dbt GA4 nécessite une configuration qui le rend à la fois réutilisable entre propriétés et explicite sur ses comportements par défaut. Le dbt_project.yml porte quatre catégories de configuration : identité du projet, comportement piloté par variables, matérialisations par dossier, et valeurs par défaut des tests.

Le dbt_project.yml complet

name: 'ga4_analytics'
version: '1.0.0'

profile: 'ga4_analytics'

model-paths: ["models"]
analysis-paths: ["analyses"]
test-paths: ["tests"]
seed-paths: ["seeds"]
macro-paths: ["macros"]

target-path: "target"
clean-targets:
  - "target"
  - "dbt_packages"

vars:
  # Configuration GCP
  ga4_project_id: "{{ env_var('GA4_PROJECT_ID') }}"
  ga4_dataset: "{{ env_var('GA4_DATASET', 'analytics_123456789') }}"

  # Configuration du traitement
  ga4_start_date: "20230101"
  ga4_static_incremental_days: 3

  # Configuration métier
  ga4_conversion_events:
    - 'purchase'
    - 'sign_up'
    - 'generate_lead'
    - 'contact_form_submit'

  # Nettoyage des URLs
  ga4_query_params_to_remove:
    - 'gclid'
    - 'fbclid'
    - 'utm_id'
    - '_ga'

models:
  ga4_analytics:
    base:
      +schema: base
      +materialized: view
      +tags: ['ga4', 'base']
      ga4:
        +materialized: incremental

    intermediate:
      +schema: intermediate
      +materialized: incremental
      +tags: ['ga4', 'intermediate']

    marts:
      +schema: marts
      +materialized: table
      +tags: ['ga4', 'marts']

tests:
  +severity: warn
  +store_failures: true

Le système de variables

Chaque valeur spécifique à une propriété doit être une variable plutôt qu’une valeur codée en dur dans les modèles. Cela rend le projet réutilisable : clonez-le pour une nouvelle propriété GA4, mettez à jour dbt_project.yml, et c’est tout.

ga4_project_id et ga4_dataset : Le projet GCP et le dataset BigQuery où se trouve l’export GA4. L’utilisation de env_var() garde les credentials hors du versionnement. ga4_dataset a une valeur par défaut de secours pour le développement local.

ga4_start_date : La date la plus ancienne à traiter. Lors d’un full refresh initial, cela détermine jusqu’où remonte l’historique. Le définir trop tôt gaspille du compute ; le définir trop tard perd de l’historique. Utilisez la première date d’export significative de la propriété.

ga4_static_incremental_days : Contrôle la taille de la fenêtre de lookback. La valeur par défaut de 3 jours gère la plupart des scénarios de données tardives. Augmentez à 5 pour les propriétés avec un tracking lourd des conversions Google Ads. Consultez Modèle de base shardé vers partitionné GA4 pour le raisonnement.

ga4_conversion_events : La liste des événements qui comptent comme conversions. Utilisée dans le modèle sessionisé pour les flags session__has_*. En faire une variable signifie que vous ajoutez un nouveau type d’événement de conversion en un seul endroit plutôt que de chercher dans le SQL des modèles.

ga4_query_params_to_remove : Paramètres à supprimer des URLs de page. gclid, fbclid, utm_id et _ga sont des paramètres de tracking qui font apparaître la même page comme des pages différentes dans l’analyse des pages d’entrée. Cette liste varie selon l’organisation.

Matérialisations par dossier

Le bloc models: définit les valeurs par défaut de matérialisation par dossier, en les remplaçant uniquement là où nécessaire :

models:
  ga4_analytics:
    base:
      +materialized: view      # Par défaut : vue
      ga4:
        +materialized: incremental  # Sous-dossier GA4 : incrémental
    intermediate:
      +materialized: incremental
    marts:
      +materialized: table

Le dossier base passe par défaut à view — les modèles de base non-GA4 (si vous ajoutez d’autres sources) obtiennent des vues par défaut. Le sous-dossier ga4 remplace cela par incremental car le volume d’événements GA4 rend tout autre choix prohibitivement coûteux. Le remplacement est au niveau du sous-dossier, pas par modèle.

Cette structure suit le pattern : configuration par dossier pour les valeurs par défaut, configuration par modèle uniquement pour les exceptions.

Séparation des schémas

La configuration +schema à chaque niveau de dossier crée des schémas séparés dans BigQuery :

• base__ga4__events → {project}.base.base__ga4__events
• int__ga4__events_sessionized → {project}.intermediate.int__ga4__events_sessionized
• mrt__analytics__sessions → {project}.marts.mrt__analytics__sessions

Cette séparation est importante pour le contrôle d’accès (les analystes peuvent avoir un accès en lecture aux marts mais pas aux intermediate) et pour l’attribution des coûts (BigQuery INFORMATION_SCHEMA peut afficher les coûts par schéma).

Valeurs par défaut des tests

tests:
  +severity: warn
  +store_failures: true

severity: warn globalement signifie qu’aucun échec de test ne bloque le pipeline. Pour un projet GA4 où les données arrivent de systèmes externes que vous ne contrôlez pas, les échecs bloquants nécessiteraient une gestion d’incidents constante. Les avertissements signalent les problèmes pour investigation sans arrêter le reporting.

store_failures: true écrit les lignes en échec dans le schéma dbt_test__audit. Lorsque le test de regroupement des canaux avertit sur des valeurs inattendues, vous pouvez interroger les échecs stockés pour voir quelles combinaisons source/medium l’ont déclenché — essentiel pour diagnostiquer les problèmes de nommage UTM.

Remplacez par la sévérité error pour les tests où le blocage du pipeline est approprié :

- name: event__key
  tests:
    - unique:
        severity: error

Exécuter le projet

Configuration initiale :

# Vérifier la connexion et la configuration
dbt debug

# Full refresh pour construire depuis ga4_start_date
dbt build --full-refresh

# Générer la documentation
dbt docs generate && dbt docs serve

Incrémental quotidien :

dbt build

Backfill sur une plage de dates spécifique :

dbt build --vars '{"ga4_start_date": "20240101"}'

Planification recommandée : Exécutez 4 à 6 heures après minuit dans votre fuseau horaire principal. L’export quotidien GA4 se termine généralement dans les quelques heures suivant la fin de la journée. Exécuter trop tôt signifie que certaines données de la journée ne sont pas encore arrivées ; exécuter trop tard retarde inutilement le reporting.

Structure des dossiers du projet

models/
├── base/
│   └── ga4/
│       ├── _ga4__sources.yml
│       ├── _ga4__models.yml
│       └── base__ga4__events.sql
├── intermediate/
│   └── ga4/
│       ├── _int_ga4__models.yml
│       ├── int__ga4__event_items.sql
│       └── int__ga4__events_sessionized.sql
└── marts/
    └── ga4/
        ├── _mrt_ga4__models.yml
        ├── mrt__analytics__sessions.sql
        └── mrt__analytics__users.sql

macros/
└── ga4/
    ├── extract_event_param.sql
    ├── extract_event_param_numeric.sql
    └── default_channel_grouping.sql

tests/
└── singular/
    ├── test_sessions_missing_session_start.sql
    └── test_purchase_without_session.sql

Le sous-dossier ga4 sous chaque couche maintient la propreté du projet si vous ajoutez d’autres systèmes sources. Le sous-dossier de macros évite les collisions de nommage. Les tests singuliers dans leur propre dossier sont faciles à localiser.