text-to-sql

モード：認知／プロンプト駆動 — 単独のユーティリティスクリプトはありません。エージェントのコンテキストを通じて使用します。

テキストから SQL への変換スキル

アイデンティティ

テキストから SQL への変換 — データベーススキーマのコンテキストとクエリパターンを使用して、自然言語のクエリを SQL に変換します。

機能

• クエリ生成：自然言語を SQL に変換します
• スキーマ認識：正確なクエリのためにデータベーススキーマを使用します
• クエリ最適化：最適化された SQL クエリを生成します
• パラメーター化クエリ：安全なパラメーター化クエリを作成します

使用方法

基本的な SQL 生成

使用する場面：

• 自然言語によるデータベースクエリ
• データ分析のリクエスト
• レポート用クエリ
• アドホックなデータベースクエリ

呼び出し方法：

"Generate SQL to find all users who signed up in the last month"
"Create a query to calculate total revenue by product"
"Write SQL to find duplicate records"

処理内容：

• 自然言語のクエリを分析します
• データベーススキーマを参照します
• SQL クエリを生成します
• クエリ構文を検証します
• パラメーター化クエリを返します

高度な機能

スキーマ統合：

• データベーススキーマを読み込みます
• テーブル間の関係を理解します
• 列の型と制約を使用します
• 結合と集計を処理します

クエリ最適化：

• 効率的なクエリを生成します
• 適切なインデックスを使用します
• 結合を最適化します
• データ転送を最小限に抑えます

安全性：

• パラメーター化クエリ（SQL インジェクションを防止します）
• クエリ構文を検証します
• サンプルデータでテストします
• エラーを処理します

ベストプラクティス

1. スキーマのコンテキスト：完全なデータベーススキーマを提供します
2. クエリの検証：実行前に SQL を検証します
3. パラメーター化：常にパラメーター化クエリを使用します
4. テスト：サンプルデータでクエリをテストします
5. 最適化：クエリのパフォーマンスを確認します

統合

Database Architect との連携

テキストから SQL への変換では、database-architect のスキーマを使用します：

• テーブル定義
• 関係
• 制約
• インデックス

Developer との連携

テキストから SQL への変換では、開発者向けのクエリを生成します：

• クエリテンプレート
• パラメーター化クエリ
• クエリ最適化
• エラー処理

例

例 1：単純なクエリ

User: "Find all users who signed up in the last month"

Text-to-SQL:
1. Analyzes query
2. References users table schema
3. Generates SQL:
   SELECT * FROM users
   WHERE created_at >= DATE_SUB(NOW(), INTERVAL 1 MONTH)
4. Returns parameterized query

例 2：複雑なクエリ

User: "Calculate total revenue by product for Q4"

Text-to-SQL:
1. Analyzes query
2. References orders and products tables
3. Generates SQL:
   SELECT p.name, SUM(o.total) as revenue
   FROM orders o
   JOIN products p ON o.product_id = p.id
   WHERE o.created_at >= '2024-10-01'
     AND o.created_at < '2025-01-01'
   GROUP BY p.id, p.name
4. Returns optimized query

評価

評価フレームワーク

Claude Cookbooks のパターンに基づくテキストから SQL への変換の評価には、以下が含まれます：

構文検証：

• SQL 構文の正確性
• スキーマへの準拠
• クエリ構造の検証

機能テスト：

• テストデータベースでのクエリ実行
• 結果の正確性
• パフォーマンスの検証

Promptfoo との統合：

• 複数のプロンプトバリエーション（基本、少数例、思考の連鎖、RAG）
• 温度のスイープ
• モデルの比較（Haiku 対 Sonnet）

評価設定： 評価設定用の promptfoo 設定ファイル（例：text_to_sql_config.yaml）を作成します。

評価の実行

# Run text-to-SQL evaluation (create config first)
npx promptfoo@latest eval -c text_to_sql_config.yaml

評価指標

• 構文の正確性：有効な SQL 構文を持つクエリの割合
• 機能的な正確性：正しい結果を返すクエリの割合
• スキーマへの準拠：正しいスキーマを使用するクエリの割合
• パフォーマンス：クエリの実行時間と最適化

Cookbooks のベストプラクティス

1. スキーマのコンテキストを提供する

常に完全なデータベーススキーマを含めます：

• 列の型を含むテーブル定義
• 関係と外部キー
• 制約とインデックス
• サンプルデータのパターン

2. 少数例を使用する

類似したクエリの例を提示します：

• 単純なクエリ
• 結合を含む複雑なクエリ
• 集計クエリ
• サブクエリのパターン

3. 複雑なクエリには思考の連鎖を使用する

複雑なクエリでは、思考の連鎖による推論を使用します：

• クエリを手順に分解します
• 必要なテーブルを特定します
• 結合と集計を計画します
• SQL を段階的に生成します

4. スキーマの理解に RAG を使用する

RAG を使用して、関連するスキーマ情報を検索します：

• クエリに関連するテーブルを見つけます
• 関係を理解します
• 列の詳細を取得します
• クエリパターンを検索します

関連スキル

• classifier：データベースクエリを分類します
• database-architect：スキーマ設計に使用します
• developer：クエリコードを生成します

関連ドキュメント

• 分類パターン - 分類ガイド
• 評価ガイド - 包括的な評価
• Claude Cookbooks - Text-to-SQL

厳守事項

1. SQL を生成する前に、必ずすべてのテーブル名とカラム名を提供されたスキーマと照合してください
2. クエリ値に文字列補間を使用してはなりません。例外なく、パラメーター化クエリを使用してください
3. ユーザーが明示的に変更を指定しない限り、SELECT クエリには必ず LIMIT 句を適用してください（デフォルトは 100 です）
4. ユーザーの明示的な確認なしに、DROP、DELETE、TRUNCATE、UPDATE 文を実行してはなりません
5. 生成したクエリのロジックを平易な言葉で必ず説明し、実行される内容をユーザーが理解できるようにしてください

アンチパターン

アンチパターン	失敗する理由	正しい方法
値に文字列補間を使用する	SQL インジェクションの脆弱性	? または $N のプレースホルダーを使ったパラメーター化クエリを使用する
SELECT クエリに LIMIT 句がない	すべての行を返すため、OOM やタイムアウトのリスクがある	デフォルトで LIMIT 100 を設定し、明示的な変更をユーザーに求める
確認なしに破壊的な SQL を実行する	元に戻せないデータ損失	DROP／DELETE／TRUNCATE はユーザーの確認を必須とする
スキーマを検証しない	存在しないテーブルやカラムを参照する	すべての識別子を提供されたスキーマと照合する
カラムリストなしで SELECT * を使う	結果が予測できず、パフォーマンスも無駄になる	必ず明示的なカラムリストを指定する

メモリープロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターン → .claude/context/memory/learnings.md
• 問題の発見 → .claude/context/memory/issues.md
• 決定事項 → .claude/context/memory/decisions.md