natural2sql - AI-Powered Natural Language to SQL Generator

自然言語でデータベースクエリを実行できるStreamlitアプリケーション

📖 このアプリでできること

natural2sqlは、自然言語からSQLを生成してデータベースを閲覧できるWebアプリケーションです。

📹 動作デモ

実行例: 「30代の会員は何人いますか？」→ SQL自動生成 → 実行結果表示

「30代の会員は何人？」→ 自動でSQLを生成して実行
「評価4以上のイタリアンレストラン一覧」→ 結果を表形式で表示
エラーが出ても自動で修正を試みます（最大3回）
結果はCSVでダウンロード可能
カスタムDB対応: あなたのSQLite/MySQLデータベースに接続可能（詳細はdocs/CUSTOM_DATABASE.md）

🖥️ 動作環境

必須要件

Google Gemini APIキー（無料で取得可能、詳細はセットアップ手順参照）

動作確認済み環境

OS: Ubuntu 24.04 LTS、Windows 11
Python: 3.10以上（開発環境: Python 3.13.5）
ブラウザ: Chrome, Firefox, Edge, Safari（最新版推奨）

使用可能なAIモデル

Gemini:

gemini-2.5-flash（デフォルト、高速）
gemini-2.5-pro（高精度）
gemini-2.5-flash-lite（超高速）

Ollama（試験的機能）:

gemma3:12b / gemma3:27b / gpt-oss:latest
⚠️ 自前でOllamaサーバーを構築し、対象モデルをダウンロード済みの場合のみ利用可能
.env に OLLAMA_BASE_URL を設定すれば使用できます

未検証の環境

以下の環境では動作未確認です（動く可能性はあります）:

Windows 10
macOS
WSL (Windows Subsystem for Linux)

Windows環境での注意事項

Windowsでは python3 ではなく python コマンドを使用します:

✅ 正: python -m venv venv
❌ 誤: python3 -m venv venv

🚀 セットアップ手順（5分）

ステップ1: 前提条件の確認

1-1. Pythonのバージョン確認

ターミナルで以下を実行:

python3 --version

期待される出力例: Python 3.10.0 以上

✅ 3.10以上が表示された → 次へ進む
❌ 3.9以下またはコマンドが見つからない → Python 3.10がインストールされていないへ

1-2. pipの確認

pip3 --version

期待される出力例: pip 21.0 以上

✅ バージョンが表示された → 次へ進む
❌ コマンドが見つからない → pipがインストールされていないへ

ステップ2: リポジトリのクローン

git clone https://github.com/yo2158/natural2sql.git
cd natural2sql

確認: ls を実行して app.py requirements.txt などが表示されればOK

ステップ3: 仮想環境の作成（推奨）

Ubuntu/macOS:

python3 -m venv venv
source venv/bin/activate

Windows:

python -m venv venv
venv\Scripts\activate

確認: プロンプトの先頭に (venv) が表示されればOK

仮想環境を終了したい場合:

deactivate

ステップ4: 依存パッケージのインストール

pip install -r requirements.txt

所要時間: 約1-2分

確認: エラーなく完了すれば OK（警告は無視して構いません）

ステップ5: Gemini APIキーの取得と設定

5-1. APIキーの取得（無料）

Google AI Studio にアクセス
Googleアカウントでログイン
「Get API key」→「Create API key in new project」をクリック
生成されたAPIキーをコピー（AIza... で始まる文字列）

無料枠について:

Google AI Studioで取得したAPIキーは無料枠で利用可能です
無料枠を超えるとエラーが返されます（課金設定をしていない場合）
最新の料金・制限情報は公式サイトで必ず確認してください

APIキーの取り扱い:

⚠️ APIキーは絶対に公開しないでください（GitHubなどにアップロード厳禁）
.envファイルは.gitignoreで除外済みですが、誤ってコミットしないよう注意してください

5-2. 環境変数ファイルの作成

cp .env.example .env

5-3. APIキーの設定

.env ファイルをテキストエディタで開き、以下の行を編集:

GEMINI_API_KEY=your_gemini_api_key_here

↓

GEMINI_API_KEY=AIzaSyC... （コピーしたAPIキーに置き換え）

保存して閉じてください。

ステップ6: アプリケーションの起動

streamlit run app.py

期待される出力:

You can now view your Streamlit app in your browser.

  Local URL: http://localhost:8501
  Network URL: http://192.168.x.x:8501

ブラウザが自動で開きます。開かない場合は http://localhost:8501 にアクセスしてください。

初回起動時: メールアドレスの入力を求められることがあります。何も入力せずEnterキーを押せばスキップできます。

確認: 画面に「🔍 natural2sql - Natural Language to SQL Generator」と表示されればOK

💡 使い方

基本的な使い方

テキストエリアに質問を入力

例: 「30代の会員は何人いますか？」
「🚀 SQL生成・実行」ボタンをクリック
結果を確認
- 生成されたSQLクエリが表示されます
- クエリ実行結果が表形式で表示されます（最大1000件）
- 結果をCSVでダウンロードできます

サンプルクエリ

アプリ内のドロップダウンから選択できます:

「30代の会員は何人いますか？」
「評価4以上のイタリアンレストランを表示」
「2025年1月に最も予約が多かった店舗TOP5」
「休眠会員（90日以上予約なし）は何人？」

エラーが出た場合

アプリが自動で修正を試みます（最大3回）
データベースに関係ない質問（例: 「今日の天気は？」）は拒否されます

⚠️ 重要な注意事項

生成されたSQLの精度について

AIが生成するSQLは、データベースのスキーマとユーザーの質問を基に自動生成されます。しかし、以下の点にご注意ください：

必ずしも意図通りのSQLが生成されるとは限りません
データの特性や業務ロジックを完全に理解しているわけではありません
複雑なクエリほど、誤りが含まれる可能性が高くなります
生成されたSQLをそのまま、または参考に実行する前に以下を確認ください
- 構文、条件、結合が適切か確認する
- 不明な場合は、有識者への確認を行う
- テスト環境での検証を十分に行う

免責事項

このツールはあくまで補助ツールです。実行結果について、開発者は一切の責任を負いません。

📊 データセット

アプリにはレストラン予約サービスのサンプルデータ（33,600レコード）が含まれています。

テーブル	レコード数	内容
members	1,000件	会員情報（年齢、性別等）
restaurants	200件	飲食店情報（店名、ジャンル等）
reservations	4,000件	予約履歴
access_logs	25,000件	アクセス履歴
reviews	400件	レビュー（1-5点評価）
favorites	3,000件	お気に入り登録

詳細は data/README.md を参照してください。

🛠️ トラブルシューティング

Gitがインストールされていない

Windows:

Git for Windows公式サイトにアクセス
「Download」ボタンをクリックしてインストーラーをダウンロード
ダウンロードした .exe ファイルをダブルクリック
重要な設定項目:
- Adjusting your PATH environment: 「Git from the command line and also from 3rd-party software」を選択（デフォルト）
- その他の設定: すべてデフォルトのまま「Next」で進めてOK
インストール完了後、コマンドプロンプト/PowerShellを新しく開いて確認:
```
git --version
```
バージョンが表示されればOK

Ubuntu/Debian:

sudo apt update
sudo apt install git

macOS (Homebrew):

brew install git

Python 3.10がインストールされていない

Ubuntu/Debian:

sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip

macOS (Homebrew):

brew install python@3.10

Windows:

Python公式サイトから最新版（3.10以上）をダウンロード
ダウンロードした .exe ファイルをダブルクリック
【最重要】 インストーラー起動時の最初の画面で、下部にある Add python.exe to PATH に必ずチェックを入れる
- ⚠️ このチェックを忘れると python コマンドが使えません
Install Now をクリック（pipも自動的にインストールされます）
「Setup was successful」と表示されたら完了
インストール完了後、開いているコマンドプロンプト/PowerShellをすべて閉じて、新しく開く
確認:
```
python --version
pip --version
```
両方ともバージョンが表示されればOK

pipがインストールされていない

# Ubuntu/Debian
sudo apt install python3-pip

# macOS (通常はPythonに同梱)
python3 -m ensurepip --upgrade

Windows: Python公式インストーラーから入れたPythonには通常pipが含まれています。

"No module named 'streamlit'" エラー

仮想環境がアクティブか確認:

# 仮想環境をアクティブ化
source venv/bin/activate  # Windows: venv\Scripts\activate

# 再度インストール
pip install -r requirements.txt

Gemini APIエラー

以下を確認してください:

.env ファイルが存在するか: ls -la .env
APIキーが正しく設定されているか: .env をエディタで開いて確認
APIキーが有効か: Google AI Studioで確認

ブラウザが起動しない

手動で http://localhost:8501 にアクセスしてください。

📁 プロジェクト構造

natural2sql/
├── app.py                    # メインアプリケーション
├── requirements.txt          # 依存パッケージリスト
├── .env.example              # 環境変数テンプレート
├── README.md                 # このファイル
├── LICENSE                   # MITライセンス
│
├── src/                      # ソースコード
│   ├── config.py             # 設定管理
│   ├── database_connector.py # DB接続抽象化
│   ├── sqlite_connector.py   # SQLite接続
│   ├── mysql_connector.py    # MySQL接続
│   ├── logical_names_loader.py   # 論理名定義ローダー
│   ├── business_terms_loader.py  # ビジネス用語ローダー
│   ├── schema_viewer.py      # スキーマ表示
│   ├── prompt_generator.py   # AI用プロンプト生成
│   ├── ai_connector.py       # AI API接続
│   ├── sql_parser.py         # SQL抽出
│   ├── sql_executor.py       # SQL実行（読み取り専用）
│   └── error_handler.py      # エラー処理
│
├── config/                   # 設定ファイル（オプション）
│   ├── logical_names_sample.csv      # 論理名定義サンプル
│   └── business_terms_sample.jsonl   # ビジネス用語サンプル
│
├── data/                     # データセット
│   ├── restaurant.db         # SQLiteデータベース（4.6MB）
│   └── README.md             # データセット説明
│
├── docs/                     # ドキュメント
│   └── CUSTOM_DATABASE.md    # カスタムDB接続ガイド
│
└── dataset/                  # データ生成スクリプト
    ├── generate_data.py      # データベース生成
    ├── config.py             # 生成設定
    └── README.md             # 生成方法説明

🔧 技術スタック

Python 3.10+: プログラミング言語
Streamlit: UIフレームワーク
SQLite/MySQL: データベース
Google Gemini API: AI（SQL生成）

📄 ライセンス

このプロジェクトはMITライセンスで公開されています。詳細は LICENSE ファイルを参照してください。

📞 質問・不具合報告

Issues まで

更新日: 2025-10-03 バージョン: 1.1.0

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.streamlit		.streamlit
config		config
data		data
dataset		dataset
docs		docs
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
app.py		app.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

natural2sql - AI-Powered Natural Language to SQL Generator

📖 このアプリでできること

📹 動作デモ

🖥️ 動作環境

必須要件

動作確認済み環境

使用可能なAIモデル

未検証の環境

Windows環境での注意事項

🚀 セットアップ手順（5分）

ステップ1: 前提条件の確認

1-1. Pythonのバージョン確認

1-2. pipの確認

ステップ2: リポジトリのクローン

ステップ3: 仮想環境の作成（推奨）

ステップ4: 依存パッケージのインストール

ステップ5: Gemini APIキーの取得と設定

5-1. APIキーの取得（無料）

5-2. 環境変数ファイルの作成

5-3. APIキーの設定

ステップ6: アプリケーションの起動

💡 使い方

基本的な使い方

サンプルクエリ

エラーが出た場合

⚠️ 重要な注意事項

生成されたSQLの精度について

免責事項

📊 データセット

🛠️ トラブルシューティング

Gitがインストールされていない

Python 3.10がインストールされていない

pipがインストールされていない

"No module named 'streamlit'" エラー

Gemini APIエラー

ブラウザが起動しない

📁 プロジェクト構造

🔧 技術スタック

📄 ライセンス

📞 質問・不具合報告

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages