02 Planification et conception

Point de départ

Module 01 terminé : Snowflake est entièrement construit, le stream CDC et les deux tâches planifiées fonctionnent et — point essentiel — le producteur de courses écrit toujours environ 60 courses par minute dans TRIPS_RAW. Laissez-le fonctionner ; ce module ne fait que lire Snowflake. Prévoyez environ 90 minutes et près de 0,5 crédit Snowflake.

Pourquoi

La cause la plus fréquente de performances décevantes après une migration ClickHouse n’est pas un problème d’optimisation, mais d’architecture. Les équipes déplacent d’abord les données et réfléchissent ensuite à la conception. Lorsqu’elles découvrent que le mauvais moteur MergeTree produit silencieusement des résultats erronés, ou qu’une clé de tri copiée depuis le schéma source ignore les véritables habitudes de requête, la migration est déjà « terminée ». Ce module impose l’ordre inverse : établissez le profil de l’existant, puis explicitez par écrit chaque choix de moteur, de clé de tri, de correspondance de type et d’ordonnancement avant que le module 03 ne l’exécute.

C’est aussi le module que les partenaires seront le plus tentés de sauter. Le setup.sh du module 03 vérifie migration-plan.md et avertit s’il est absent ou incomplet, mais il ne bloque jamais : vous pouvez continuer sans lui. Dans ce cas, vous exécuterez au module 03 des décisions que vous n’avez jamais prises : fact_trips apparaîtra comme un ReplacingMergeTree sans que vous sachiez pourquoi ce moteur convient mieux qu’un simple MergeTree, vous verrez une clé ORDER BY sans connaître son lien avec les requêtes, vous rencontrerez delete_insert et FINAL dans la configuration dbt sans savoir les déduire pour une autre charge, puis observerez au module 04 des gains que vous ne pourrez ni expliquer ni reproduire chez un client. Ces 90 minutes transforment la suite de l’atelier : vous ne recopiez plus des commandes, vous comprenez une migration.

Concepts — fonctionnement interne

Toutes les décisions de ce module appartiennent à l’une des cinq catégories suivantes, chacune associée à une fiche :

• Famille de moteurs — quelle variante MergeTree correspond au modèle d’écriture de chaque table : MergeTree simple pour les ajouts seuls, ReplacingMergeTree pour les tables mises à jour par CDC et AggregatingMergeTree pour les agrégats pré-calculés. Consultez Moteurs MergeTree.
• Clé ORDER BY — ClickHouse n’offre aucun index à ajouter après coup ; la clé de tri est choisie une fois à partir des requêtes réelles, et non de la clé primaire de la table source.
• Correspondance des types et différences de dialecte — VARIANT, LATERAL FLATTEN et MERGE INTO de Snowflake n’ont pas d’équivalent direct dans ClickHouse et doivent être traduits. QUALIFY constitue l’exception : ClickHouse propose une clause QUALIFY native depuis la version 24.5, mais cet atelier enseigne tout de même la réécriture en sous-requête, portable vers les anciennes versions de ClickHouse et les moteurs SQL qui n’offrent pas QUALIFY. Consultez Snowflake face à ClickHouse.
• Conception des modèles dbt — matérialisation, configuration du moteur, stratégie incrémentielle et emplacement de FINAL pour chaque modèle. Consultez dbt sur ClickHouse.
• Ordre des vagues — quels objets peuvent être déplacés en premier parce que rien n’en dépend encore, et lesquels doivent attendre.

Étape 1 — Établir le profil de l’environnement Snowflake

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/02-plan-and-design"
source ../01-setup-snowflake/.env
./scripts/01_profile_snowflake.sh

Le script interroge l’instance Snowflake active du module 01 et écrit profile_report.md, qui comporte quatre sections : inventaire des objets (chaque table, vue, stream et tâche, avec le nombre de lignes et un niveau de complexité), 10 requêtes ayant cumulé la plus longue durée sur les 7 derniers jours, statistiques des tables (nombre de lignes, plages de dates, taux de valeurs nulles et usage de VARIANT) et différences de compatibilité du schéma détectées automatiquement.

profile_report.md est ignoré par Git : il est régénéré depuis votre propre compte Snowflake à chaque exécution, dépend donc de la machine et n’est jamais validé dans le dépôt. Ne vous attendez pas à le trouver dans un clone neuf et ne tentez pas de le valider vous-même.

Si ACCOUNT_USAGE n’est pas encore disponible (il faut attendre 1 à 3 heures ou utiliser le rôle ACCOUNTADMIN), le script se rabat sur INFORMATION_SCHEMA et indique ce qu’il n’a pas pu mesurer. Vous pouvez également exécuter manuellement scripts/02_query_history.sql dans l’interface Snowflake.

Étape 2 — Remplir les cinq fiches

Remplissez les cinq fiches dans l’ordre. Chacune présente un concept, puis propose des exercices à choix multiple portant sur la charge NYC Taxi réelle. Chaque réponse est vérifiée dès votre choix, et le bouton « Copy as markdown » fournit le tableau rempli à coller dans votre plan de migration.

• Fiche 1 : choix du moteur MergeTree — famille et choix du moteur par table
• Fiche 2 : conception des clés de tri — ORDER BY déduite des requêtes
• Fiche 3 : traduction du schéma — correspondance des types et traduction des fonctions
• Fiche 4 : plan des vagues de migration — ordre des dépendances et affectation aux vagues
• Fiche 5 : conception des modèles dbt — matérialisation, moteur, stratégie incrémentielle et emplacement de FINAL

Vos réponses sont enregistrées dans le stockage local du navigateur, pas dans le dépôt. Elles ne vous suivent donc pas sur une autre machine et disparaissent si vous effacez les données du site. Si vous changez d’ordinateur pendant l’atelier, vous devrez y refaire les fiches.

Étape 3 — Remplir le plan de migration

Ouvrez workshop_public/snowflake_migration_lab/02-plan-and-design/migration-plan.md et remplissez chaque section à partir de vos réponses. Le document comporte dix sections et une liste de contrôle de cinq cases au début :

- [ ] Engine selection: completed
- [ ] Sort key design: completed
- [ ] Schema translation: completed
- [ ] Migration wave plan: completed
- [ ] dbt model design: completed

Le setup.sh du module 03 vérifie cette liste et signale si elle est incomplète, sans toutefois vous empêcher de continuer. La terminer permet de comprendre les décisions du module 03 plutôt que de les trouver arbitraires.

Comment vérifier que vous avez terminé

Vous avez terminé lorsque toutes les conditions suivantes sont remplies :

• Les cinq fiches affichent la note maximale — la ligne de score au bas de chacune indique N/N correct.
• Toutes les cases de la liste de contrôle de workshop_public/snowflake_migration_lab/02-plan-and-design/migration-plan.md sont cochées.
• profile_report.md, produit à l’étape 1, existe sur le disque (il est ignoré par Git et n’apparaît donc pas dans git status).

Une fois votre propre plan rédigé, comparez-le à l’exemple résolu, qui fournit un plan complet pour la même charge. Utilisez-le pour vérifier la cohérence de votre raisonnement et comprendre vos éventuels choix divergents, pas comme modèle à remplir avant d’avoir réfléchi vous-même.

État final

migration-plan.md est rempli sur le disque, toutes ses cases sont cochées et il repose sur cinq fiches terminées. Le producteur Snowflake fonctionne toujours : le module 03 migre les données depuis une source active et mouvante, et la bascule du module 05 mesure précisément l’écart que le producteur crée entre Snowflake et ClickHouse. Ne l’arrêtez pas maintenant.