02 計画と設計

Snowflake ワークロードをプロファイリングし、マイグレーションで実行するアーキテクチャ上の判断を下します — エンジン選定、sort key、スキーマ変換、デプロイのウェーブ、dbt モデル設計。

開始チェックポイント

モジュール01が完了していること。Snowflake が完全に構築され、CDC ストリームと2つのスケジュールタスクが動作し、そして決定的に重要な点として、trip プロデューサーが TRIPS_RAW に毎分約60件を書き込み続けていること。動かしたままにしてください。このモジュールは Snowflake から読み取るだけです。約90分と、およそ0.5 Snowflake クレジットを見込んでください。

なぜ必要か

ClickHouse のマイグレーションが期待に届かない最も多い原因は、チューニングの問題ではなくアーキテクチャの問題です。チームはまずデータを移し、設計はあとから考えます。誤った MergeTree エンジンが黙って不正な結果を返していることや、ソーススキーマから写した sort key が実際のクエリパターンを無視していることに気づくころには、マイグレーションはすでに「完了」しています。このモジュールは逆の順序を強制します。実際に手元にあるものをプロファイリングし、そのうえでエンジン、sort key、型マッピング、実施順序のすべての判断を、モジュール03がそれを実行する前に文章として明示するのです。

このモジュールは、パートナーが最も飛ばしたくなるモジュールでもあります。モジュール03の setup.sh は migration-plan.md をチェックし、欠けている場合や未完成の場合は警告しますが、決してブロックはしません。それなしで突き進むことはできます。そうすると、モジュール03では自分が下していない判断を実行することになります。fact_trips が ReplacingMergeTree として立ち上がるのを、なぜ素の MergeTree ではなくそのエンジンなのか分からないまま目にし、ORDER BY キーがクエリワークロードからどう導かれたのか分からないまま目にし、dbt の設定にある delete_insert と FINAL を、別のワークロードでどう導けばよいのか分からないまま目にし、モジュール04ではベンチマークの高速化を、顧客に説明も再現もできないまま目にすることになります。ここでの90分が、ワークショップの残りをコマンドのコピーからマイグレーションの理解へと変えるものです。

概念 — 内部の仕組み

このモジュールが生み出す判断はすべて、次の5つのカテゴリーのいずれかに入り、それぞれにワークシートがあります。

エンジンファミリー — 各テーブルの書き込みパターンにどの MergeTree のバリアントが合うか: 追記のみなら素の MergeTree、CDC 経由で更新を受け取るテーブルなら ReplacingMergeTree、事前集計されたロールアップなら AggregatingMergeTree。 MergeTree エンジンを参照。
ORDER BY キー — ClickHouse にはあとから追加できるインデックスがありません。sort key は一度だけ選ぶもので、ソーステーブルの primary key からではなく、実際のクエリワークロードから決めます。
型マッピングと方言のギャップ — Snowflake の VARIANT、LATERAL FLATTEN、MERGE INTO には ClickHouse の直接的な対応物がなく、変換した形が必要です。 QUALIFY は例外です。ClickHouse には v24.5 以降ネイティブの QUALIFY 句がありますが、このラボでは引き続きサブクエリへの書き換えを教えます。QUALIFY より前の ClickHouse バージョンや、それを持たない SQL エンジンにも移植できるからです。 Snowflake と ClickHouse の比較を参照。
dbt モデル設計 — モデルごとのマテリアライゼーション、エンジン設定、増分戦略、FINAL の置き場所。dbt on ClickHouse を参照。
ウェーブの順序 — 下流にまだ依存関係がないため先に移せるオブジェクトはどれで、待たなければならないものはどれか。

手順1 — 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

これは稼働中のモジュール01の Snowflake インスタンスに対して実行され、4つのセクションを持つ profile_report.md を書き出します。オブジェクトインベントリ（すべてのテーブル、view、ストリーム、タスクを行数と複雑度グレード付きで）、直近7日間の総経過時間による上位10クエリ、テーブル統計（行数、日付範囲、null 率、VARIANT の使用状況）、そして自動検出されたスキーマ互換性のギャップです。

profile_report.md は gitignore されています。実行ごとにあなた自身の Snowflake アカウントから新しく生成されるため、マシン固有であり、コミットされることはありません。クローンしたばかりのリポジトリにあることを期待しないでください。また、自分でコミットしようとしないでください。

ACCOUNT_USAGE がまだ利用できない場合（1〜3時間の伝播待ち、または ACCOUNTADMIN ロールが必要です）、スクリプトは INFORMATION_SCHEMA にフォールバックし、測定できなかった項目を記録します。Snowflake の UI で scripts/02_query_history.sql を手動で実行することもできます。

手順2 — 5つのワークシートに取り組む

5つのワークシートを順番に進めてください。それぞれが概念を教えたうえで、実際の NYC タクシーワークロードについての選択式演習を出します。回答は選んだ時点ですぐに判定され、各ワークシートには「Copy as markdown」ボタンがあって、記入済みの表をマイグレーション計画に貼り付けられます。

ワークシート1: MergeTree エンジンの選定 — テーブルごとのエンジンファミリーとエンジンの選択
ワークシート2: sort key の設計 — クエリワークロードから導く ORDER BY
ワークシート3: スキーマ変換 — 型マッピングと関数の変換
ワークシート4: マイグレーションのウェーブ計画 — 依存関係の順序付けとウェーブの割り当て
ワークシート5: dbt モデル設計 — マテリアライゼーション、エンジン、増分戦略、FINAL の置き場所

回答はリポジトリではなくブラウザのローカルストレージに保存されます。別のマシンには引き継がれず、サイトデータを消すと残りません。ワークショップの途中でノートパソコンを変えると、そちらでワークシートをやり直す必要があります。

手順3 — マイグレーション計画を記入する

workshop_public/snowflake_migration_lab/02-plan-and-design/migration-plan.md を開き、ワークシートの回答を使って各セクションを記入してください。この文書には10のセクションと、先頭に5つのチェックボックスを持つ Completion Checklist があります。

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

モジュール03の setup.sh はこのチェックリストを確認し、未完成なら警告しますが、先に進むことをブロックはしません。それでも仕上げておくことが、モジュール03の判断を場当たり的に感じさせず、納得できるものにします。

完了の確認方法

次のすべてが成立していれば完了です。

5つのワークシートすべてが満点になっている。各ワークシート下部のスコア行が N/N correct と表示されている。
workshop_public/snowflake_migration_lab/02-plan-and-design/migration-plan.md の Completion Checklist のチェックボックスがすべてチェックされている。
手順1で生成した profile_report.md がディスク上に存在する（gitignore されているので git status には出てきません）。

自分の計画を書き上げたら、記入例: 完成した計画と比べてみてください。同じワークロードについて完全に記入済みの計画です。自分の推論の妥当性を確認し、違う選択をした箇所を理解するために使ってください。自分で考える前に埋めるためのテンプレートとしては使わないでください。

終了状態

記入済みの migration-plan.md がディスク上にあり、すべてのチェックボックスがチェックされ、 5つの完了済みワークシートに裏付けられています。Snowflake のプロデューサーはまだ動いています。 モジュール03は稼働中で動き続けるソースからデータを移行し、モジュール05のカットオーバーは、マイグレーション中にプロデューサーが Snowflake と ClickHouse の間に作るギャップを正確に測定します。いま止めないでください。