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