Skip to content

dft validate-query

Validate a SQL query for structural issues without executing it.

dft validate-query [OPTIONS] [SQL]

Detects:

  • Missing join predicates (cartesian risk)
  • Fanout risk from aggregation over joined tables
  • Re-aggregation of already-aggregated columns through subqueries / CTEs
  • Other structural problems flagged by the Dataface SQL analyzer

Arguments

Argument Description
SQL SQL query string to validate. Omit if using --file.

Options

Flag Description
--file PATH, -f PATH Read SQL from a file.
--dialect TEXT SQL dialect: duckdb, postgres, bigquery, etc.
--json Output diagnostics as JSON.
--show-suppressed Include diagnostics that would normally be suppressed.

Examples

dft validate-query "SELECT SUM(a.x) FROM a JOIN b ON a.id = b.a_id"
dft validate-query --file query.sql
dft validate-query --file query.sql --dialect bigquery --json

What it catches

The validator is the same engine that powers fanout detection inside dft serve and dft render. It's tuned for the patterns that quietly break analytical SQL:

  • Cartesian joins — joins without a predicate
  • Fanout aggregation — SUM/AVG/COUNT over a table joined to a many-side without distinctness reasoning
  • Re-aggregation through CTEs — aggregating an already-aggregated subquery in a way that changes grain
  • Window function pitfalls — frame and partition issues that produce wrong-but-plausible output

See How we prevent fanout for the engine's design philosophy.