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駆動開発と私