dct query¶
Run a named board query, execute raw SQL, or validate SQL for structural issues; all in one command. The first operand is the query context: a data source name, a CSV/JSON/Parquet file path, or a board file (.yml, .yaml, .md, .markdown).
Modes¶
| Mode | Invocation | Description |
|---|---|---|
| Board execute | dct query board.yml NAME |
Run a named query from a board, print the result as CSV |
| Raw SQL execute | dct query db 'SELECT …' |
Execute SQL directly against a data source |
| File execute | dct query data/orders.csv 'SELECT …' |
Execute SQL against one data file; the table name is the file stem |
| SQL from file | dct query db --file query.sql |
Execute SQL read from a file |
| Validate | dct query db 'SELECT …' --validate |
Lint SQL for missing joins and re-aggregation |
Usage¶
CONTEXT is a source name, a data file path (resolved like a board's inline source:: from the project root), or a board path (.yml, .yaml, .md, .markdown). QUERY is SQL for source contexts, or a named query/reference for board contexts.
Options¶
| Flag | Description |
|---|---|
--validate |
Run static lint instead of executing. |
--file PATH |
Read SQL from a file instead of passing inline. Requires a source context. |
--dialect NAME |
SQL dialect hint for --validate (duckdb, bigquery, etc.). |
--var KEY=VALUE |
Variable override (repeatable). |
--show-suppressed |
Include suppressed diagnostics in --validate output. |
--json |
Output JSON instead of CSV: one object per row, up to 1,000 rows, with truncated set when more exist. |
--project-dir PATH |
Project directory for resolving relative paths. |
Examples¶
# Run the `revenue` query from a board and print it as CSV
dct query charts/sales.yml revenue
# Execute raw SQL against a named source
dct query my_warehouse 'SELECT month, revenue FROM dundersign_serving.monthly_metrics ORDER BY month'
# Execute SQL against a CSV file (table name = file stem)
dct query data/orders.csv 'SELECT status, count(*) FROM orders GROUP BY 1'
# Execute SQL from a file
dct query my_warehouse --file analytics/monthly.sql
# Static lint
dct query my_warehouse 'SELECT SUM(a.x), SUM(b.y) FROM a JOIN b ON a.id = b.id GROUP BY 1' --validate
# Static lint on a named board query
dct query charts/sales.yml revenue --validate
# Machine-readable output
dct query charts/sales.yml revenue --json
dct query my_warehouse 'SELECT 1' --validate --json
Output¶
Results print as CSV: a header line, then one line per row. The output is capped at about 37,500 bytes, the same cap the MCP execute_sql tool applies to what a model reads. When rows are cut, a notice on stderr says how many were shown and how to narrow the query. There is no row-count flag; put LIMIT in the SQL, or filter, aggregate, and select fewer columns.
Errors¶
A failed query prints each error on stderr, and the first line carries the registered error code:
With --json, a failed result has an error_code field holding the same code; it is absent on success. The Error Reference explains what a code means and what to do about it.
Exit codes¶
0: success (named-query execute, SQL execute, validate with no errors)1: error (file not found, compile error, validation errors, warehouse error)