Most data questions start in plain English.
"Which customers spent the most?"
"How many orders are pending?"
"What products generated revenue last month?"
Someone can turn those questions into SQL, but that usually means waiting on a developer, analyst, or dashboard update.
This Python example shows how to build a small natural language to SQL API with Telnyx AI Inference.
Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/sql-natural-language-python
The Flask app exposes:
POST /query
POST /query/sample
POST /validate
GET /queries
GET /queries/<id>
GET /health
POST /query
accepts a natural-language question, SQL dialect, and schema DDL. It returns structured JSON with the generated SQL, explanation, tables used, and metadata.
POST /query/sample
uses a bundled SQLite sample dataset, so you can ask a question and see real rows come back without connecting a production database.
POST /validate
dry-runs a SQL string against the sample dataset.
Natural language to SQL needs guardrails.
This example asks the model for read-only SQL and then checks the generated query before execution. The validation layer rejects multiple statements, comments, and write-oriented SQL keywords.
That keeps the example focused on the useful workflow:
The model does the language translation. The app still owns the safety checks.
Clone the examples repo:
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/sql-natural-language-python
Create your .env
file:
cp .env.example .env
Add your Telnyx API key:
TELNYX_API_KEY=your_telnyx_api_key
AI_MODEL=moonshotai/Kimi-K2.6
HOST=127.0.0.1
Install and start:
pip install -r requirements.txt
python app.py
Ask a question against the sample dataset:
curl -X POST http://localhost:5000/query/sample \
-H "Content-Type: application/json" \
-d '{"question": "Show me the top 3 customers by total order revenue"}' | python3 -m json.tool
Validate a query:
curl -X POST http://localhost:5000/validate \
-H "Content-Type: application/json" \
-d '{"sql": "SELECT * FROM orders WHERE total > 100"}' | python3 -m json.tool
This is a small API, but it maps to real internal tooling:
The useful part is the boundary. The app does not blindly trust generated SQL. It asks for structured output, validates the query, and returns JSON that another system can inspect or display.
Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/sql-natural-language-python
Telnyx AI skills and toolkits: https://github.com/team-telnyx/ai
Telnyx AI Inference docs: https://developers.telnyx.com/docs/inference
Chat Completions API: https://developers.telnyx.com/api/inference/chat-completions
Telnyx Portal: https://portal.telnyx.com/