Skip to content

NL2SQL 0.4.0

Curated answers: a data team can write verified queries, reviewed SQL with typed parameters, and when a question matches one the engine runs that SQL with the values bound instead of generating new SQL, and labels the answer as verified. Any other question is answered by generated SQL, as before.

Released 2026-10-13.

Highlights

  • Write verified queries in configs/curated.yaml: a description, the phrasings people ask, typed parameters and the SQL. When a question matches one, its reviewed SQL runs with the values bound by the driver, never pasted into the text.
  • An answer from a verified query says so. QueryResult.source is verified or generated in the SDK, the REST response and the trace, and the playground shows a "Verified" badge with the query's id and values.
  • Point the planner at the tables your team trusts with preferred_tables in datasources.yaml. The built-in adapters now index views as well as tables.
  • Thumbs-up feedback on generated answers can become proposed verified queries with nl2sql curated proposals export, for a person to review and commit.

What's included

Features

  • configs/curated.yaml, its settings CURATED_CONFIG and CURATED_ENABLED, and nl2sql curated validate, which checks every verified query, its parameters and its SQL against the indexed schema (#240).
  • nl2sql index indexes each verified query's phrasings, nl2sql index --curated-only refreshes only those after an edit, and nl2sql doctor warns when curated.yaml changed since the last index (#242).
  • A new first step, the curated matcher, picks a verified query and its values, checks the values and the role's access in code, and runs the saved SQL with bound parameters; anything else goes to the generated pipeline with a reason in the trace (#243).
  • preferred_tables in datasources.yaml puts those tables first in the schema the planner sees, and the SQLAlchemy-based adapters now snapshot views (#244).
  • The playground's "Verified" badge, six verified queries in the demo, and nl2sql curated test, which runs every verified query once with its defaults or examples (#245).
  • Feedback records the datasources a run used and the answer's source, and nl2sql curated proposals export turns thumbs-up feedback into proposed verified queries (#246).

Docs

  • The design for curated answers: verified queries, preferred tables and feedback proposals, with business metrics deferred (#239).

Known limits

  • Matching runs once, on the whole question. A question with two parts falls back to generated SQL, even if one part matches a verified query.
  • A question missing a value a verified query needs falls back to generated SQL; it does not ask a follow-up question.
  • The match threshold (CURATED_MATCH_FLOOR) was calibrated with the local embedding model only.
  • Business metrics are parsed and checked in curated.yaml but not used yet.
  • PostgreSQL materialized views are not indexed.
  • Feedback given before this release cannot become a proposal, because it did not record its datasource.

Upgrading

pip install --upgrade "nl2sql-engine[demo]==0.4.0"

Breaking changes: none. Curated answers are off unless a curated.yaml exists at the default path or CURATED_CONFIG names one. Two behaviour changes:

  • Views now appear in the schema snapshot of the built-in adapters, so a re-index picks them up.
  • If CURATED_CONFIG points at a missing or broken file, startup fails with a message naming every problem.

What's next

Next: 0.5.0, questions across several databases.

Full changelog: v0.3.0...v0.4.0