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 .yaml board file.
Modes¶
| Mode | Invocation | Description |
|---|---|---|
| Board execute | dct query board.yaml 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.yaml 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) |
Usage¶
CONTEXT is either a source name or a .yaml board path. 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 warehouse adapter. |
--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.yaml revenue
# Execute raw SQL against a named source
dct query my_warehouse 'SELECT month, SUM(revenue) 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.yaml revenue --validate
# Column schema introspection
dct query my_warehouse 'SELECT month, SUM(revenue) FROM orders GROUP BY 1' --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.yaml 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)