IntentQL¶
Reliable natural-language analytics without giving an LLM control of your database.
IntentQL lets a model provide semantic hints, then uses schema-aware deterministic infrastructure to resolve those hints into a typed plan, validate it, and compile parameterized Postgres SQL. The model interprets language. The compiler owns execution.
Why IntentQL Exists¶
Text-to-SQL systems often make a probabilistic model responsible for interpretation, schema selection, joins, SQL syntax, and safety at the same time. When the answer is wrong, it is difficult to tell which responsibility failed.
IntentQL introduces a semantic compiler between the model and the database.
| Raw model-generated SQL | IntentQL |
|---|---|
| Model produces executable SQL | Model output is treated as untrusted hints |
| Schema policy lives in a prompt | Tables and columns are checked against an allowlist |
| User values may become SQL text | Values are emitted as bind parameters |
| Join behavior depends on generation | Joins must follow declared schema links |
| Model and prompt changes alter everything | Compiler behavior is independently testable |
| Invalid guesses may look plausible | Unknown references fail validation |
IntentQL does not claim that a compiler makes language unambiguous. It makes the boundary between uncertain interpretation and database execution explicit, inspectable, and testable.
Current Evidence¶
The BIRD result is a partial development evaluation over case IDs 20-149 using provided evidence. It is not an official leaderboard score. See Benchmarks for the methodology, caveats, and publication standard.
What The Compiler Owns¶
Allowlisted access
Only configured tables, columns, and links can enter a valid plan. Unknown references fail before execution.
Grounded semantic planning
Names, types, descriptions, values, keys, dates, and relationships help resolve model hints into valid plan elements.
Typed QueryPlan contract
A structured intermediate representation separates language interpretation from executable SQL.
Parameterized SQL
Filter values become bind parameters. The model never receives a path for directly executing generated SQL.
Use expensive models less
The compiler performs structural work so a model can focus on compact semantic hints. Mistral, Ollama, and custom adapters are supported.
General improvements only
Benchmark failures guide reusable compiler capabilities. Domain-specific benchmark branches are not accepted in core logic.
Quick Start¶
from sqlalchemy import create_engine
from intentql.agent import QueryAgent
engine = create_engine("postgresql+psycopg2://user:pass@host/db")
agent = QueryAgent(
engine=engine,
schema_path="config/schema.yaml",
llm="mistral", # or "ollama", an adapter, or a compatible client
)
result = agent.ask("Which customers placed the most orders last year?")
print(result["rows"])
print(result["sql"])
IntentQL can also validate and execute hand-written QueryPlan objects without any model.
See Getting Started for setup and provider configuration.
Open By Design¶
The public core includes the semantic plan formats, schema resolver, planner, validator, compiler, executor, adapters, and benchmark harnesses. You can run it locally against your own model and database.
IntentQL is licensed under Apache License 2.0. Contributions are proposed through pull requests and become part of the official project after review and merge by the lead maintainer.
Read the open-source project principles
Explore¶
Architecture Why a semantic compiler? Understand the trust boundary between model hints and deterministic execution. Read architecture → Evidence Benchmarks and limitations See current results, methodology, caveats, and the standard for future claims. Inspect evaluation → Reference QueryPlan grammar Explore the typed intermediate representation compiled by IntentQL. Open reference → Community Open-source direction Learn what belongs in the public core and how to contribute without reward hacking. Read project principles →