Monitoring de l'évolution du schéma GA4

Le schéma d’export BigQuery de GA4 est une cible mouvante. Google ajoute de nouveaux champs sans annonces, ne publie pas de changelog officiel, et ne renseigne jamais rétroactivement les tables historiques avec des champs ajoutés après leur date d’export. Si vous traitez le schéma comme stable, vous passerez à côté de nouvelles fonctionnalités — et pourriez potentiellement casser des modèles lorsque des champs inattendus apparaissent.

L’historique des évolutions

Le schéma a considérablement évolué depuis le lancement de l’export BigQuery GA4 vers 2019 sous le nom « App+Web », héritant de sa structure de l’export Firebase. Principaux ajouts par période approximative :

Les ajouts de juillet 2024 — champs de séquençage batch (batch_event_index, batch_ordering_id, batch_page_id) et session_traffic_source_last_click — représentent les changements structurels les plus significatifs du schéma d’export dans l’histoire de GA4. Les équipes qui avaient construit des modèles de sessionisation et d’attribution avant cette date ont dû mettre à jour leur logique pour tirer parti des nouveaux champs. Celles qui ne surveillaient pas le schéma les ont manqués entièrement.

La règle de non-rétroactivité

Chaque nouveau champ est absent des tables historiques. session_traffic_source_last_click est null pour chaque ligne exportée avant juillet 2024. collected_traffic_source est null avant mai 2023. Ce n’est pas un problème de qualité des données — c’est une propriété fondamentale des tables date-shardées.

Les implications pratiques :

Les modèles d’attribution nécessitent une logique conditionnelle lorsqu’ils couvrent la date d’ajout d’un champ. Une requête sur les 2 dernières années utilisant session_traffic_source_last_click pour l’attribution de session produira des résultats corrects pour les données à partir de juillet 2024 et des nulls pour tout ce qui est antérieur. Le guide des champs de source de trafic couvre le pattern de logique conditionnelle pour gérer cet écart.

Le backfill est impossible pour les champs qui n’existaient pas au moment de l’export. Il n’y a pas d’export GA4 rétroactif qui ajoute session_traffic_source_last_click aux tables de janvier 2024. Vos données historiques auront toujours cet écart.

Les tests de schéma vérifiant la présence d’un champ doivent tenir compte de la date d’introduction. Un test qui vérifie session_traffic_source_last_click IS NOT NULL échouera sur toutes les données historiques antérieures à juillet 2024.

Surveillance des changements de schéma

Puisqu’il n’y a pas de changelog officiel, les praticiens doivent surveiller INFORMATION_SCHEMA pour détecter les ajouts.

Interroger INFORMATION_SCHEMA pour les changements de colonnes

-- Vérifier les colonnes actuelles dans le schéma de la table events
SELECT
  column_name,
  data_type,
  is_nullable
FROM `project.analytics_123456789.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS`
WHERE table_name LIKE 'events_%'
  AND table_name NOT LIKE 'events_intraday_%'
ORDER BY table_name DESC, ordinal_position
LIMIT 500

Exécutez cela sur votre table la plus récente et comparez avec un snapshot datant de 30 jours. Toutes les nouvelles lignes dans la sortie indiquent des ajouts de schéma.

Un pattern de surveillance par snapshot

Dans votre plateforme de données, maintenez une petite table de référence des colonnes de schéma connues et leurs dates d’introduction :

CREATE TABLE `project.analytics_meta.ga4_schema_log` (
  column_name STRING,
  first_seen_date DATE,
  data_type STRING,
  notes STRING
);

Une requête planifiée ou un modèle dbt peut vérifier les colonnes présentes dans les tables récentes mais absentes de ce log — signalant un nouveau champ à évaluer.

Que faire quand un nouveau champ est découvert

Lorsque INFORMATION_SCHEMA révèle une nouvelle colonne :

1. Documentez-la : Quand était-elle présente pour la première fois ? Quel suffixe de table ? Mettez à jour votre référence de schéma interne.
2. Évaluez-la : Ce champ est-il utile pour vos cas d’usage ? Remplace-t-il ou améliore-t-il une logique existante ?
3. Testez la disponibilité historique : Exécutez la requête INFORMATION_SCHEMA sur des tables plus anciennes pour trouver la date d’introduction, afin que vos requêtes puissent gérer le cas null avant l’introduction.
4. Mettez à jour les modèles si pertinent : Si le champ améliore un modèle existant (comme session_traffic_source_last_click pour l’attribution), planifiez une mise à jour du modèle avec une logique conditionnelle appropriée pour la période de transition historique.

L’angle de validation du schéma source dbt

La Validation du schéma source dbt peut détecter lorsque GA4 ajoute une colonne que votre modèle de base n’expose pas, mais seulement si vous avez configuré votre source avec des columns dans le YAML. La direction inverse — un champ que vous attendez absent d’une table historique — nécessite une vérification différente.

Un test personnalisé validant la disponibilité d’un champ pour une plage de dates donnée :

-- Devrait retourner 0 ligne (pas de nulls pour les données post-juillet 2024)
SELECT COUNT(*) AS null_count
FROM {{ ref('base__ga4__events') }}
WHERE event_date >= '2024-07-01'
  AND session_traffic_source_last_click IS NULL
  AND event_name = 'session_start'

Associer cela à un seuil raisonnable (certains nulls sont attendus même dans les données post-juillet 2024 en raison de cas limites) et alerter lorsqu’il le dépasse vous donne un signal si le champ cesse de se renseigner — signe potentiel d’un changement de configuration de liaison GA4.

Traiter le schéma comme une infrastructure

Le schéma de GA4 est une infrastructure versionnée qui évolue selon le calendrier de Google, sans annonces. Une révision trimestrielle des changements INFORMATION_SCHEMA, combinée à la surveillance des notes de version de GA4, permet de détecter les nouveaux champs avant qu’ils ne soient découverts via des modèles cassés ou manqués dans les pipelines en production.