dct query¶
Run a named board query, execute raw SQL, validate SQL for structural issues, or inspect column schema; all in one command. The first operand is the query context: a data source name, 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, return sample rows |
| Raw SQL execute | dct query db 'SELECT …' |
Execute SQL directly against a data source |
| SQL from file | dct query db --file query.sql |
Execute SQL read from a file |
| Validate | dct query db 'SELECT …' --validate |
Lint SQL for fanout, missing joins, and re-aggregation |
| Column describe | dct query db 'SELECT …' --describe |
Return column schema without fetching rows |
| Board describe | dct query board.yml NAME --describe |
Return column schema for a named board query |
| Validate + describe | dct query db 'SELECT …' --validate --describe |
Run static lint, then return column schema (describe skipped on error-severity diagnostics) |
--describe never pays for a full query run to answer "what columns does
this return?"; it uses whatever mechanism the source's adapter offers:
DuckDB's own DESCRIBE (free), or a BigQuery dry run (unbilled). A
csv/json/parquet source also answers via DESCRIBE, but that is not free —
DuckDB has to materialize the source's files (read and parse them) first;
still far cheaper than executing, since DESCRIBE returns column metadata
rather than the result set. Postgres, Snowflake and Redshift have only
EXPLAIN, which validates the query in the warehouse (a real connection
round-trip) but returns no result schema, so --describe still reports that
it cannot list columns without executing the query, instead of running it
for you; use plain execute and read the columns off the sample rows if you
accept that cost.
Usage¶
CONTEXT is either a source name 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 before execution/describe output. |
--describe |
Return column schema via the adapter's DESCRIBE/dry-run check (materializing files first for a csv/json/parquet source); never a full query run. |
--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). |
--limit INT |
Max rows to return. Default 20, max 1000. |
--show-suppressed |
Include suppressed diagnostics in --validate output. |
--json |
Output JSON instead of rich text. |
--project-dir PATH |
Project directory for resolving relative paths. |
Examples¶
# Run the `revenue` query from a board, show first 20 rows
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 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
# Column schema introspection
dct query my_warehouse 'SELECT month, revenue FROM dundersign_serving.monthly_metrics ORDER BY month' --describe
# Validate then describe in one pass (describe skipped on error-severity lint)
dct query my_warehouse 'SELECT 1 AS n' --validate --describe
# Machine-readable output
dct query charts/sales.yml revenue --json
dct query my_warehouse 'SELECT 1' --validate --json
Exit codes¶
0: success (named-query execute, SQL execute, validate with no errors, describe ok)1: error (file not found, compile error, validation errors, warehouse error)