debugging-snowflake-queries

Snowflake クエリのデバッグ

Snowflake SQL を体系的にデバッグします。まず問題を再現して分類し、失敗する最小の単位を特定し、粒度と結合を確認してからクエリを書き直します。

使用する場面

• SQL compilation error、invalid identifier、object does not exist、ambiguous column、キャストエラー、権限エラー、タイムアウトなどの Snowflake エラーを診断する
• クエリは実行されるものの、カウントが誤っている、重複行がある、結果が空になる、データが古く見える、またはあり得ない割合が返る場合にデバッグする
• 長時間のスキャン、ウェアハウスの問題、予想以上にコストのかかる結合など、パフォーマンスの問題を調査する
• アドホック SQL クエリをレビューし、正しく再現可能にする方法を説明する

使用しない場面

• Snowflake SQL 自体をデバッグしていない、テンプレートまたはアプリケーション層での SQL 生成の失敗
• 主な作業がクエリ自体のデバッグではなく、質問への回答となる一般的なビジネス調査

ワークフロー

1. 失敗するクエリをそのまま再現するか、同等の最小クエリを再構築します。
2. SQL を変更する前に問題を分類します。
   • コンパイル／名前解決
   • 権限／環境
   • 型／キャスト／NULL のセマンティクス
   • 結合／粒度／結果の正しさ
   • パフォーマンス／スキャン／ウェアハウス
   • 上流データの古さ、または不完全さ
3. クエリを失敗する最小の要素まで絞り込みます。
   • CTE を 1 つずつ
   • 結合を 1 つずつ
   • 計算式を 1 つずつ
   • フィルターを 1 つずつ
4. 何かを仮定する前に、オブジェクトの存在、スキーマ、正確なカラム名を確認します。
5. 各入力と中間結果の粒度を明示します。
6. 結合の各境界でカウントと NULL 率を検証します。
7. クエリに論理的な誤りがあるものの構文上は有効な場合、対象を絞った反例または診断クエリで失敗の仕組みを証明します。
8. 根本原因を特定してから、クエリ全体を書き直します。

基本ルール

• 推測に基づく書き直しより、最小限の診断クエリを優先します。
• デバッグの各ステップを検証可能にします。それぞれのクエリで 1 つの問いに答えます。
• ID の名前が似ているという理由だけで、2 つのテーブルを結合できると決めつけないでください。
• 行数の急増は、そうでないと証明されるまで粒度の不一致として扱います。
• 0 行になる場合は、データの欠損を疑う前にフィルター、時間範囲、または結合キーの問題を疑います。
• 意外な割合が返る場合は、計算を疑う前に分母の対象範囲の問題を疑います。
• dbt マクロの外で作業する場合や、環境が曖昧な可能性がある場合は、完全修飾名を使用します。
• バックエンドのミラーが関係する場合は、論理削除カラムと鮮度／取り込み時刻を確認します。
• 大規模なファクトテーブルでは、広範な診断を実行する前に日付フィルターの範囲を狭め、スキャンの挙動を確認します。

参考資料

必要に応じて、以下の参考資料を読み込みます。

• references/debugging-playbook.md エンドツーエンドのワークフロー、診断クエリのテンプレート、失敗の絞り込み方法に使用します。
• references/error-taxonomy.md 一般的な Snowflake エラーメッセージを、考えられる原因と次に確認すべき項目に対応付ける際に使用します。
• references/result-correctness-checklist.md クエリは実行されるものの、重複、欠落、分母の誤り、古いデータなど、結果に問題がある場合に使用します。
• references/query-patterns-and-failure-modes.md よくある失敗パターンとその修正方法について、特定のウェアハウスに依存しない具体例を確認する際に使用します。

期待される出力

デバッグの回答を返す際は、次の内容を含めます。

1. 考えられる根本原因を 1 文で述べます。
2. 最小限の診断結果を示します。
3. 修正後のクエリ、または具体的な修正方法を提示します。
4. 特に粒度、環境、上流データの鮮度に関する未解決の前提条件を記します。