-- smartql · the smart query language

Ask your database
in plain English.

SmartQL is the Smart Query Language: it turns natural-language questions, in English or any language your model speaks, into safe, validated SQL. Every query is parsed and checked before it runs, so you can hand the model your schema without handing it the keys.

pip install smartql v0.1.0 · MIT · PyPI
Get Started View on GitHub
CLI REST API Python PHP Node.js Go
smartql shell
> Show me top 5 customers by total spending
SELECT c.name, SUM(o.total) AS spending
FROM customers c
JOIN orders o ON o.customer_id = c.id
GROUP BY c.id
ORDER BY spending DESC LIMIT 5
✓ validated · read-only · 5 rows
Acme Corp 24,500.00
TechStart Inc 18,200.00
Global Trade 15,800.00
DataFlow LLC 12,400.00
CloudNine 9,850.00
> _

-- why smartql

Built for production, not the demo.

idcapabilitydetail
01 100+ LLM providers OpenAI, Claude, Gemini, Groq, Ollama, and the rest through LiteLLM. Switch providers in one line of YAML.
02 AST-based validation Every query is parsed with sqlglot and checked on the tree: read-only enforcement, allowlists, and complexity caps that string matching cannot fake.
03 Semantic layer A YAML map of what your tables and columns mean. Define revenue once, and the model stops guessing.
04 Auto-introspection Point it at a database and it discovers the schema. An empty config still works out of the box.
05 Runs local Pair it with Ollama and no data leaves your infrastructure. The validator never cares who proposed the query.
06 CLI, API, library An interactive shell for exploring, a REST API for products, and a Python library for embedding.
07 Ask in any language Pose the question in Spanish, French, Arabic, Hindi, or any language your model understands. SmartQL passes it straight through and returns SQL.
7 rows · query OK

-- getting started

Three files, then ask anything.

01 / connect

Point it at a database

database:
  type: mysql
  connection:
    host: localhost
    database: myapp
02 / configure

Choose your LLM

llm:
  provider: groq
  groq:
    model: llama-3.1-8b-instant
03 / ask

Query in English

from smartql import SmartQL

sql = SmartQL.from_yaml("config.yml")
sql.ask("Top 10 customers by revenue")

-- works with your stack

WHERE dialect IN (PostgreSQL, MySQL, SQLite, SQL Server)

-- from the blog

The thinking behind it.

01 Adding an Intelligence Layer to Your Laravel App A practical architecture for letting users ask questions of their data in plain English, drawn from how Trakli wires SmartQL into a Laravel application: an HTTP service, a queued job, a question router, and a semantic layer. → 02 Give AI Your Whole Database. Just Not the Keys. Teams are wiring LLMs directly into production databases. The payoff is real, and so are the failure modes. Here is the architecture that gets you the first without the second. → 03 Parse the SQL. Don't Trust the Prompt. Why SmartQL validates LLM-generated SQL with a real parser and an AST walk instead of system prompts and regex, with the actual checks it runs before a query touches your database. →
SELECT * FROM posts →

-- ready?

Query in plain English.

Open source and free forever. Set up in minutes.

pip install smartql
Get Started Star on GitHub
Star on GitHub