DEV Community

Sonam
Sonam

Posted on

Build a Natural Language to SQL API in Python

#python #ai #flask #sql

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

What it does

The Flask app exposes:

POST /query
POST /query/sample
POST /validate
GET /queries
GET /queries/<id>
GET /health
Enter fullscreen mode Exit fullscreen mode

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.

Why validation matters

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:

  1. ask a question
  2. include schema context
  3. generate a query
  4. validate the query
  5. return structured results

The model does the language translation. The app still owns the safety checks.

Run it

Clone the examples repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/sql-natural-language-python
Enter fullscreen mode Exit fullscreen mode

Create your .env file:

cp .env.example .env
Enter fullscreen mode Exit fullscreen mode

Add your Telnyx API key:

TELNYX_API_KEY=your_telnyx_api_key
AI_MODEL=moonshotai/Kimi-K2.6
HOST=127.0.0.1
Enter fullscreen mode Exit fullscreen mode

Install and start:

pip install -r requirements.txt
python app.py
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Where this could go

This is a small API, but it maps to real internal tooling:

  • analytics assistants
  • support dashboards
  • sales operations tools
  • data warehouse query helpers
  • product usage exploration
  • internal admin tools

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.

Resources

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/

Top comments (0)