1. このツールで何ができるか
「30代の会員は何人？」
こう日本語で質問するだけで、自動でSQLを生成・実行してくれるWebアプリケーション natural2sql を作りました。
データベースに対して自然言語でSQLを生成・実行します。主な特徴は：
- 自然言語でデータベース検索: 「評価4以上のイタリアンレストランは？」と聞くだけ
- カスタムDB対応: 自分のSQLite/MySQLデータベースにも接続可能
- 論理名・ビジネス用語対応: 業務特有の言葉をAIに理解させられる
- サンプルデータベース付属: すぐに試せます。
GitHub: https://github.com/yo2158/natural2sql
2. 試してみるには
以下は簡略版です。詳細な手順はGitHubのREADMEを参照してください。
前提条件
- Python 3.10以上
- Google Gemini APIキー（無料で取得可能）
セットアップ手順
ステップ1: リポジトリをクローン
git clone https://github.com/yo2158/natural2sql.git
cd natural2sql
ステップ2: 依存関係をインストール
pip install -r requirements.txt
ステップ3: 環境変数を設定
cp .env.example .env
.envファイルを編集して、最低限以下を設定：
# Gemini API設定(ここだけ自分のAPIキーに変える)
GEMINI_API_KEY=your_gemini_api_key_here
# データベース設定（設定済み）
DB_TYPE=sqlite
DATABASE_PATH=data/restaurant.db
# 論理名・ビジネス用語定義（設定済み）
LOGICAL_NAMES_PATH=config/logical_names_sample.csv
BUSINESS_TERMS_PATH=config/business_terms_sample.jsonl
ステップ4: アプリを起動
streamlit run app.py
ブラウザが自動で開きます（開かない場合は http://localhost:8501 にアクセス）。
サンプルデータベースについて
付属のサンプルDBはレストラン予約システムのドメインで、以下のデータが入っています：
- 会員: 10,000人
- レストラン: 200店舗
- 予約: 20,000件
- レビュー: 3,400件
スキーマはドキュメントだけでなく、画面からも呼び出して確認できます。
3. 基本的な使い方
自然言語で質問する
アプリが起動したら、検索ボックスに日本語で質問を入力してみましょう。
例1: 単純な集計
入力: 30代の会員は何人いますか？
→ 自動で以下のようなSQLが生成・実行されます：
SELECT COUNT(*) FROM members WHERE age BETWEEN 30 AND 39
例2: 少し複雑な条件
入力: 評価4以上のイタリアンレストランを表示して
→ 以下のようなSQLも生成されます：
SELECT r.name, AVG(rv.rating) as avg_rating
FROM restaurants r
JOIN reviews rv ON r.id = rv.restaurant_id
WHERE r.genre = 'Italian'
GROUP BY r.id, r.name
HAVING AVG(rv.rating) >= 4
ORDER BY avg_rating DESC
エラー自動修正
SQLに間違いがあってエラーとなった場合、AIが最大3回まで自動で修正を試みます。
例えば「休眠会員は何人？」と質問した場合、もしカラム名を間違えても、エラーメッセージを見て自動修正してくれます。
検索結果の活用
- テーブル表示: 結果は表形式で表示
- CSV出力: 「CSVをダウンロード」ボタンで結果をエクスポート可能
4. 自分のデータベースで使う
サンプルDBだけでなく、既存のデータベース(SQLite/MySQL対応)に接続することもできます。
カスタムDB接続（SQLite）
.envファイルを編集：
DB_TYPE=sqlite
DATABASE_PATH=/path/to/your/database.db
カスタムDB接続（MySQL）
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database_name
論理名定義（重要！）
このツールは論理名定義CSVがないとまともに動きません。サンプルDBには完備されていますが、カスタムDBを使う場合は自分で生成する必要があります。
もし試される場合は、CUSTOM_DATABASE.mdにガイドを掲載していますので、参照してください。
論理名定義CSVの例：
physical_name,logical_name
users,ユーザーマスタ
orders,注文トランザクション
user_id,ユーザーID
order_date,注文日
ビジネス用語辞書
業務特有の用語をJSONLに定義することで、定義できます。
例（config/business_terms.jsonl）：
{"term": "休眠会員", "definition": "90日以上予約していない会員"}
{"term": "常連客", "definition": "月1回以上予約している会員"}
.envで指定：
BUSINESS_TERMS_PATH=config/business_terms.jsonl
5. 重要な注意事項
このツールは技術検証目的で作成しており、以下の制約があります：
⚠️ 完璧な精度は保証できません
- AIが生成するSQLは必ずしも意図通りとは限りません
- 特に複雑なクエリほど誤りが含まれる可能性があります
- 実行結果について開発者は責任を負いません
⚠️ 本番環境での利用は非推奨
- パスワードは平文保存（
.envファイル） - あくまで開発・検証用途です
6. まとめ
natural2sql は、AIの力を借りて、日本語でSQL生成、データベース検索ができます。
- サンプルDBですぐ試せる
- 自分のDBにも接続可能（論理名定義の準備が必要）
- ビジネス用語でカスタマイズ可能
詳細については、GitHubのREADMEを参照してください。
このツールの開発につかったClaude Codeについて、別記事で書いています:
Claude Codeと開発した自然言語SQL生成アプリ ― AI駆動開発と私