Skip to content

NL2SQL 0.3.0

Results at any size: a question can now return up to 100,000 rows by default, the whole result is saved and can be paged through or downloaded as CSV, and the answer model reads a 20-row preview instead of every row.

Released 2026-10-12.

Highlights

  • The default row cap rises from 1,000 to 100,000 (10,000 in the demo). A result that hits the cap is flagged, and the answer says it is incomplete and asks you to narrow the question.
  • The answer model sees the first 20 rows and the total count, not the whole result, so a large result no longer fills the prompt.
  • Every run's result is saved whole. Page through it or download it as CSV from the SDK, nl2sql-api or the playground, where each result gets its own tab and every sub-query is shown.
  • A run can stream its progress and its answer as Server-Sent Events. The playground lights up each step as it finishes and writes the answer as it arrives.

What's included

Features

  • The answer model gets a 20-row preview and the row count (ANSWER_PREVIEW_ROWS). RESULT_ROW_LIMIT (default 100,000) replaces the 1,000-row cap, and a result cut at the cap is flagged in truncated and in the answer's warnings (#231).
  • Results are fetched in batches of RESULT_FETCH_BATCH_SIZE rows through a new optional StreamingAdapterProtocol; adapters without it work unchanged. Each run's combined result is saved as parquet in its artifact folder (#234).
  • A run writes a manifest.json of its results, returned as QueryResult.result_manifest. get_result_manifest, get_result_page and export_result_csv read a result back, and nl2sql-api and the playground serve the same as page and CSV routes (#235).
  • The playground pages through the saved result 100 rows at a time, shows a tab per result, downloads the full CSV and shows every sub-query in the Plan and SQL steps (#236).
  • NL2SQL.stream_query, POST /api/v1/query/stream and the playground's /api/ask/stream send a run's progress, its result manifest and its answer token by token as Server-Sent Events. The playground falls back to the non-streaming call if the stream fails (#237).

Fixes

  • A datasource's row_limit, statement_timeout_ms and max_bytes written beside connection, as the docs show, are now honoured; they were silently ignored. If a limit is set both there and under options, the lower wins (#233).

Known limits

  • Anyone with a role who knows a run's id can read its saved result. There is no access check beyond the tenant's folder.
  • The downloaded CSV does not guard against spreadsheet formulas in cell values.
  • A join, sort or group-by across results may still hold its inputs in memory (as polars columns, not Python rows).
  • When a stream breaks, the playground asks the question again without streaming, so it is run a second time.
  • Questions across several databases are still limited.

Upgrading

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

Breaking changes: none. Three behaviour changes:

  • The default row cap is 100,000, not 1,000. To keep a lower cap, set RESULT_ROW_LIMIT or a datasource's row_limit.
  • terminal_results now holds only the 20-row preview. The full result is the saved artifact; read it with get_result_page or export_result_csv.
  • Every run writes its combined result as parquet and a manifest.json in its artifact folder. On S3 or ADLS, the manifest needs s3fs or adlfs installed.

What's next

Next: 0.4.0.

Full changelog: v0.2.4...v0.3.0