NL2SQL · Natural Language to SQL
Upload CSV/Excel files → Ask questions in plain English → AI generates and executes SQL → Returns readable results + optional charts
Trigger Phrases
nl2sql text to sql natural language sql ask database csv query excel sql 数据查询 自然语言查数
Usage
Command Line
# Basic query
python -m scripts.main "Which product has the highest sales?" -f data/sales.csv
# Generate chart
python -m scripts.main "Monthly sales trend" -f data/sales.csv --chart line
# Export results
python -m scripts.main "Top 10 customers" -f data/customers.csv --format csv -o result.csv
Python API
from scripts import NL2SQLService, QueryRequest
service = NL2SQLService(api_key="your-api-key")
request = QueryRequest(
question="Which product has the highest sales?",
files=["data/sales.csv"],
chart_type="bar",
explain=True
)
response = service.query(request)
if response.success:
print(f"SQL: {response.sql}")
print(f"Results: {response.data}")
Parameters
QueryRequest
| Parameter | Type | Required | Description |
|---|---|---|---|
| question | str | Yes | Natural language question |
| files | List[str] | Yes | File paths (CSV/Excel) |
| chart_type | str | No | Chart type: bar/line/pie/scatter/area/histogram |
| explain | bool | No | Whether to explain the SQL |
| output_format | str | No | Output format: markdown/json/csv (default: markdown) |
QueryResponse
| Field | Type | Description |
|---|---|---|
| success | bool | Whether the query succeeded |
| sql | str | Generated SQL |
| explanation | str | SQL explanation |
| row_count | int | Number of result rows |
| columns | List[str] | Column names |
| data | List[dict] | Result data |
| chart_base64 | str | Chart image as base64 |
| error | str | Error message if failed |
Supported Formats
| Format | Extensions | Notes |
|---|---|---|
| CSV | .csv | UTF-8/GBK auto-detected |
| Excel | .xlsx, .xls | Multi-sheet supported |
Tech Stack
- Parsing: pandas, openpyxl
- AI: OpenAI GPT-4 (via user-provided API key)
- Charts: matplotlib
- Execution: pandasql (SQL on DataFrame, fully offline sandbox)
Tiered Features
| Feature | FREE | PRO |
|---|---|---|
| Queries | 3 per session | Unlimited |
| File size | 5 MB max | 200 MB max |
| JOIN support | No | Yes |
| Chart types | bar, line, pie | All types |
| Export formats | CSV | CSV, Excel, PDF |
| AI SQL generation | No (rule-based) | Yes (GPT-4) |
Billing
$0.01 USDT per call — billed via SkillPay at https://skillpay.me/ai-nl2sql
Privacy Note: Your Feishu User ID (Open ID) may be transmitted to skillpay.me for billing purposes only.
| Price | $0 (FREE tier) | $0.01 / call (PRO tier) |
For paid use, visit https://skillpay.me/ai-nl2sql
Required Environment Variables
| Variable | Description |
|---|---|
SKILL_BILLING_API_KEY | SkillPay Builder API Key (from skillpay.me) |
SKILL_BILLING_SKILL_ID | Skill ID on SkillPay (default: ai-nl2sql) |
API Key Format
Any non-empty string works as an API key. The tier is determined automatically:
- No API key → FREE tier (rule-based SQL only)
- Any API key → PRO tier (GPT-4 powered)
Slug
ai-nl2sql
Security Notes
- SQL Safety: All AI-generated SQL passes through an SQLValidator that blocks all non-SELECT queries (DROP, DELETE, INSERT, UPDATE, CREATE, EXEC, GRANT, etc.). Only read-only queries are permitted.
- Data Isolation: SQL execution runs entirely in a local pandas DataFrame sandbox. No real database connection is made. No data leaves the user's environment.
- External Data Transmission: Your Feishu User ID (Open ID) is transmitted to skillpay.me exclusively for billing purposes. See ## Billing for details.
Notes
- All SQL execution runs in a local pandas DataFrame sandbox — no real database connection
- AI SQL generation requires a valid OpenAI API key provided by the user
- Network errors gracefully degrade to FREE tier