sql-query-explainer

SQL クエリ解説スキル

このスキルは、SQL クエリを平易な言葉で解説し、最適化の機会を特定して、技術に詳しくない関係者にもデータロジックを伝えやすくします。また、自然言語での説明に基づいて、新しいクエリを作成し、ドキュメント化します。

必要な入力

• SQL（Explain／Optimise／Document モード）— 実際のクエリ。可能であれば方言（Postgres、BigQuery、Snowflake、MySQL など）も指定してください。方言によって、セマンティクスと最適化に関するアドバイスの両方が変わります。
• 意図を平易な言葉で説明したもの（Write モード）— データから答えたい質問と、分かる場合はテーブル名やカラム名。スキーマがない場合は、前提を明示し、決して黙って補いません。
• 任意ですが、あると非常に役立つ情報：EXPLAIN／EXPLAIN ANALYZE の出力と、おおよそのテーブルサイズ。一般的なアドバイスを、実際のクエリプランに即したアドバイスにできます。

モード

ユーザーの依頼に基づいて、必要なモードを判断します。

1. Explain — 既存の SQL を平易な日本語に翻訳します
2. Optimise — SQL のパフォーマンス上の問題を確認し、改善策を提案します
3. Write — 自然言語での説明から SQL を生成します
4. Document — データディクショナリまたはクエリのドキュメントを作成します

---

モード 1：Explain

SQL クエリを受け取ったら、次の内容を作成します。

平易な言葉での概要

[1～3 文。クエリが何を行い、どのようなデータを返すかを説明します。開発者向けではなく、ビジネスアナリストに説明するように書いてください。]

手順ごとの解説

クエリを論理的なセクションに分けます。各セクションについて、次の内容を説明します。

• SQL 句を引用する
• 平易な言葉で、その処理内容を説明する
• 複雑な要素（例：ウィンドウ関数、サブクエリ、CTE）を指摘する

結果の形式

[出力の形を説明します：「ユーザーごとに 1 行を返し、X、Y、Z のカラムが含まれます。[フィールド]の降順で並べ替えられます。」]

指摘すべき潜在的な問題

• [このクエリにある落とし穴、エッジケース、暗黙の前提]
• [例：「LEFT JOIN で一致するものが見つからない場合、user_id カラムに NULL が含まれます」]

---

モード 2：Optimise

クエリの最適化を依頼されたら、次の内容を作成します。

パフォーマンス評価

全体を評価します：🟢 適切に最適化されています／🟡 改善の余地があります／🔴 重大な問題があります

見つかった問題

問題ごとに、次の形式で記載します。

問題 [N]：[短い名前。例：「結合カラムにインデックスがありません」]

• 内容：[平易な説明]
• 重要な理由：[パフォーマンスへの影響。例：「1,000 万行のテーブル全体をスキャンします」]
• 修正方法：

-- Before
[original snippet]

-- After
[improved snippet]

• 期待される改善：[可能であれば見積もり]

最適化チェックリスト

• SELECT * を使用しているか？（特定のカラムに置き換える）
• JOIN／WHERE のカラムで暗黙的な型変換が行われているか？
• JOIN または WHERE のカラムにインデックスがないか？
• N+1 パターン（ループ内でのクエリ）がないか？
• GROUP BY のほうが高速なのに DISTINCT を使用していないか？
• サブクエリのほうが明快で高速なのにウィンドウ関数を使用していないか？
• CTE が不必要に再利用またはマテリアライズされていないか？
• JOIN に置き換えられる大きな IN() リストがないか？

---

モード 3：Write

自然言語での説明を受け取ったら、SQL クエリを生成し、続けてモード 1 の形式で解説します。

次の内容をユーザーに確認します。

• データベース／方言（PostgreSQL／MySQL／BigQuery／Snowflake／SQLite／Standard SQL）
• テーブル名とカラム名（分かる場合。分からない場合は、users、orders、user_id のような説明的な仮の名前を使用します）
• フィルター、並べ替え、集計に関する要件

次の内容を作成します。

1. インラインコメント付きの SQL クエリ
2. 平易な言葉での説明（モード 1 の形式）

---

モード 4：Document

クエリまたはテーブルのドキュメント作成を依頼されたら、次の内容を作成します。

クエリのドキュメント

Query: [Name]
Purpose: [One sentence — what business question this answers]
Author: [If provided]
Last reviewed: [If provided]

Inputs:
  - Table: [table_name] — [what it contains]
  - Filter: [any WHERE conditions and their business meaning]

Output columns:
  | Column | Type | Description |
  |--------|------|-------------|
  | [name] | [type] | [plain English description] |

Assumptions:
  - [Any implicit assumptions the query makes]

Known limitations:
  - [Edge cases not handled, data quality dependencies, etc.]

---

出力形式

どのモードでも、同じ規律ある形式で返します。

1. 1行の要約 — SQL の話に入る前に、このクエリが何をするのかをビジネス用語で説明します（「返金を除いた地域別の月間収益」など）。
2. 解説または成果物 — モードに応じて、節ごとに注釈を付けた説明（Explain）、変更点と理由を示す差分付きの書き換え後のクエリ（Optimise）、前提を明記した新しいクエリ（Write）、またはドキュメントブロック（Document）を提示します。
3. 注意点 — NULL の挙動、JOIN による行数の増加、タイムゾーンの落とし穴、インデックスへの影響など、このクエリに当てはまる事項を示します。一般論は避けます。
4. 検証 — 要約どおりにクエリが動作することを確認できる、小さな SELECT を提示します（実行前後の行数、特定の条件での抜き取り確認など）。

品質チェック

• 平易な英語による説明で、SQL の専門用語を避けている
• 最適化の提案に変更前と変更後の SQL が含まれている
• 作成するクエリにインラインコメントが含まれている
• 出力形式（列、1行の粒度、並び順）が説明されている
• 標準ではない方言固有の構文に注意書きがある

アンチパターン

• クエリが何をして何を返すのかを説明せず、SQL を疑似コードで言い換える
• 変更前後のクエリや、新しいクエリが高速になる理由を示さない最適化アドバイス
• 方言を無視する（MySQL ユーザーに PostgreSQL 専用の構文を書くなど）
• 正確性、パフォーマンス、行の粒度を確認せずに「問題なさそうです」と答える
• ユーザーのクエリを説明または最適化するのではなく、最初から書き直す

きっかけとなるフレーズの例

• 「この SQL クエリを説明してください：[クエリを貼り付け]」
• 「この遅いクエリを最適化してください：[クエリを貼り付け]」
• 「[自然言語による説明] を実行する SQL クエリを書いてください」
• 「技術者以外の関係者向けに、このクエリをドキュメント化してください」
• 「このクエリが予期しない結果を返すのはなぜですか？」