JSON output

Structured pretty-printed JSON with `columns`, `rows` (array of objects keyed by column name), `row_count`, and `execution_time_ms`. Stable schema intended for piping into jq and downstream tools.

Syntax

--format json

Description

## Overview `json` emits a single pretty-printed JSON document per query. It is the recommended format for scripting, agent-driven automation, and any downstream tool that expects structured input (jq, Python, Node). The schema is stable and does not depend on terminal width. ## Schema ```json { "columns": ["col_a", "col_b", ...], "rows": [ { "col_a": "value", "col_b": "value", ... }, ... ], "row_count": 42, "execution_time_ms": 17 } ``` - `columns`: array of strings, in schema order. - `rows`: array of JSON objects, one per result row, keyed by column name. Values are either JSON `null` (for SQL NULL) or a JSON string produced by the Arrow value formatter. Integers, floats, decimals, dates, and timestamps are all serialised as strings, not as JSON numbers. - `row_count`: total rows returned by the engine for this statement, as a JSON number. - `execution_time_ms`: wall-clock elapsed time for the request, as a JSON number. ## Behavior - Output is pretty-printed via `serde_json::to_string_pretty`. It ends with a single trailing newline from `println!`. - Row cap: at most `max_rows` (100 by default) row objects are emitted. The full engine `row_count` is still reported, so callers can detect truncation by comparing `rows.length` against `row_count`. - NULL values are emitted as JSON `null`. All non-null values are emitted as JSON strings, regardless of the underlying Arrow type. - If serialisation fails (should not occur in practice), the CLI writes ` Failed to serialize JSON: <error>` to stderr and emits no JSON on stdout. - Empty-column results still produce a valid document: `{ "columns": [], "rows": [], "row_count": 0, "execution_time_ms": <n> }`. ## Compatibility - Field names use snake_case (`row_count`, `execution_time_ms`), not camelCase. - Numeric values inside rows are strings, not JSON numbers. Consumers that need typed numerics must parse the string against the known column type.

Examples

delta-forge-cli --format json query SELECT * FROM orders LIMIT 5

delta-forge-cli --format json query SELECT id, total FROM orders | jq '.rows[]'

delta-forge-cli --format json query SELECT count(*) FROM orders | jq -r '.rows[0].count'

Pitfalls

• Row values are always JSON strings (or null), never JSON numbers or booleans. `jq -r '.rows[0].total'` returns a string; use `| tonumber` or `| test("true")` in jq when you need a typed value.
• The `rows` length is capped at the client-side `max_rows` (default 100) while `row_count` reports the full engine count. Callers that assume `rows.length == row_count` will silently miss data on large result sets; inspect both fields or add an explicit `LIMIT` in the SQL.
• Top-level field names are snake_case (`row_count`, `execution_time_ms`). Downstream parsers that expect camelCase (`rowCount`, `executionTimeMs`) must be adjusted to match the actual payload.

See Also

• CLI_OUTPUT_TABLE
• CLI_OUTPUT_COMPACT
• CLI_AUTOMATION_JQ