Skip to content

ADR 0002: Columnar JSON output for queries ​

  • Status: Accepted
  • Date: 2026-10-19

Context ​

The output of execute_sql is read by a model, so the criterion is the cost in tokens. It was measured with the o200k_base tokenizer (an approximation; the Claude tokenizer is not public) on 100 rows and 8 columns with nulls.

FormatTokensRatio
Array of JSON objects7966100%
{ columns, rows } (the current one)555570%
{ columns, rows } with unquoted numbers546769%
CSV with header525866%
Markdown table610877%

Decision ​

Keep { columns: [{ name, type }], rows: [[...]] } with values as text and null for SQL NULL.

Consequences ​

  • An array of objects costs 43% more because it repeats the keys in every row.
  • CSV saves only 5% more and cannot tell NULL from the empty string.
  • Writing numbers without quotes saves 1%, but it requires converting BIGINT and DECIMAL to numbers and losing precision. It is not worth it.
  • The real saving is exporting large results instead of returning them (ADR 0003).

Released under the MIT License.