Skip to content

dct validate

Fast YAML schema and cross-reference validation. No DB hit, no execute (by default). Use it for sub-second checks in editors, pre-commit hooks, and CI. Add --warehouse to extend validation to the warehouse layer.

dct validate [OPTIONS] [PATH]

Arguments

Argument Description
PATH Path to board YAML file or directory. Defaults to charts/ when omitted.

Options

Flag Description
--project-dir PATH Project root for resolving relative paths.
--json Output as JSON.
--strict / --no-strict Exit 1 on warnings. Default: off.
--warehouse Validate queries against the warehouse using the cheapest per-adapter mechanism (see below). Requires resolvable credentials.

Examples

dct validate                        # Validate all boards in charts/
dct validate charts/                 # Validate all boards in a directory
dct validate charts/sales.yml        # Validate one file
dct validate charts/sales.yml --json
dct validate charts/sales.yml --strict
dbt parse && dct validate            # Validate with manifest-backed ref checks
dct validate charts/sales.yml --warehouse   # Warehouse-level validation

When given a directory, dct validate globs **/*.yml and **/*.yaml, skipping any file whose name starts with _ (partials and templates).

What it validates

  • YAML syntax
  • Schema conformance (every field, every chart family, every query shape)
  • Cross-references inside the board (chart query: names exist, rows: references exist, variable references resolve)
  • Variable defaults and types
  • Field-level constraints (enums, ranges, mutually exclusive options)
  • Structural SQL lint on named queries: entries (cartesian joins, missing join predicates) — emitted as warnings; exit code 1 with --strict. Inline chart queries are skipped.
  • ref()/source() names exist in the dbt manifest (when a manifest is present at target/manifest.json)

--warehouse validation

Adds a warehouse-level check per query using the cheapest available mechanism:

Adapter Mechanism What it checks
DuckDB DESCRIBE Validity + result column schema — schema only, no billing
BigQuery Native dry-run Validity + result column schema — unbilled (QueryJobConfig(dry_run=True))
Everything else None Nothing — reported as unchecked (WARN-WAREHOUSE-CHECK-UNAVAILABLE)

The last row is the important one: an adapter with no primitive that runs without executing the query is reported as unchecked, not as passing. --warehouse will never run your query at full cost to find out whether it works.

Two other things report as unchecked, each with the reason in the warning message:

  • a query composing another query's cached result ({{ queries.x.cache }}) — that result only exists at render time, so no warehouse has heard of it
  • a warehouse that could not be reached (bad host, expired credentials) — a fault raised before any SQL reaches the warehouse says nothing about your query, so it is never reported as an invalid query

A query naming no source is different: it is a project configuration fault, not a per-query warning, so it is reported as an error and stops the sweep immediately instead of being reported as unchecked.

Under --strict, every one of those warnings exits 1 — that is the mode to use in CI when "unchecked" is not good enough.

When column schema is available (DuckDB, BigQuery), --warehouse also checks that every chart's channel fields (x, y, color, theta, etc. — including those on layers:) reference a column the query actually returns.

--warehouse is additive: the full stateless pass above runs first and its findings are always reported. Queries are checked exactly as dct render would run them — dbt ref()s resolved, setup_sql on the same connection, face variable defaults applied — so a check never fails on SQL your render would never send.

What it does not check (without --warehouse)

  • Whether referenced dbt models / tables actually exist in the warehouse
  • Whether queries execute successfully
  • Whether columns return rows
  • Chart-render output

For those, use dct validate --warehouse or dct render.