Skip to content

NL2SQL 0.2.3

A correctness release: the model now knows today's date, what values a column holds and where its data starts and ends, and a query that comes back wrong or empty is retried or explained instead of answered as fact.

Released 2026-10-12.

Highlights

  • "This year" and "the last 30 days" are resolved against today's date, not a year the model guessed. When the period falls outside the data, the planner uses the latest period the data has and says so.
  • A filter on a value the column does not hold, such as 'Metal' for 'Heavy Metal', no longer turns into a confident "none". A close match is retried once; a missing value is named as a warning in the answer.
  • A query the database rejects as wrong (an unknown column, a type mismatch, bad syntax) goes back to the refiner for another try, instead of ending the run.
  • A column the plan names but the schema does not have is caught before the query runs, and the planner is asked to fix it.

What's included

Fixes

  • Strict column checking is on by default: an unknown column is a retryable COLUMN_NOT_FOUND. LOGICAL_VALIDATOR_STRICT_COLUMNS=false restores the old warning (#219).
  • The plan's offset is rendered, so "rows 11 to 20" no longer returns rows 1 to 10. An offset without an order is refused before generation (#221).
  • A query the database rejects as wrong is retried through the refiner. A refusal (permission, timeout, connection) still ends the run. Retry feedback carries only the latest error, with no SQL echo or stack trace (#223).
  • An empty result that filtered on a missing value is checked: a close stored value sends the plan back once, otherwise the answer carries a warning such as "There is no Genre with Name 'Polka'." (#226).
  • DATE and DATETIME leave the function allow-list, which now matches the planner prompt. STRFTIME is still accepted as a legacy name (#218).
  • The planner and refiner are told today's date. NL2SQL_TODAY pins it; unset, it is the UTC date (#220).
  • A text column with 50 or fewer distinct values keeps all of them in the index, not five samples (#222).
  • Date and numeric columns carry their data range in the prompt, with a rule for relative periods outside it (#224).
  • Two gold questions cover data ranges and value matching. The gold set is now 47 questions (#225).

Docs

  • Every version has a release page, written by a skill and required in CI before a release (#216).

Known limits

  • Each query returns at most 1,000 rows by default, and the answer model sees the whole result.
  • A cached plan for a relative-date question ("this month") can be reused on a later day. 0.2.4 fixes this.
  • "Rows 11 to 20" reaches the planner only through the question text.
  • Questions across several databases are still limited.

Upgrading

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

Breaking changes: none. Two behaviour changes: an unknown column is now a retried error rather than a warning (set LOGICAL_VALIDATOR_STRICT_COLUMNS=false for the old behaviour), and a plan calling DATE or DATETIME is refused. Re-index an existing demo folder to pick up the full column values: nl2sql setup --demo or nl2sql --env demo index.

What's next

Next: 0.2.4, starting with cached plans for relative-date questions.

Full changelog: v0.2.2...v0.2.3