Skip to content

dft describe-query

Return the column schema (names + types) for a SQL string without executing it.

dft describe-query [OPTIONS] [SQL]

Gates on validate-query first — short-circuits on parse errors and missing join predicates with actionable diagnostics. Otherwise calls the warehouse adapter to retrieve the column schema.

Arguments

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

Options

Flag Description
--file PATH, -f PATH Read SQL from a file.
--source TEXT Data source name.
--dialect TEXT SQL dialect hint (duckdb, bigquery, etc.).
--json Output result as JSON.
--project-dir PATH Project directory for resolving data sources.

Examples

dft describe-query "SELECT month, SUM(revenue) FROM orders GROUP BY 1"
dft describe-query --file query.sql --source my_warehouse
dft describe-query "SELECT 1 AS x" --json

Why it exists

Two scenarios it solves cleanly:

  1. AI agents building queries. Get the column shape (names + types) of a candidate query before committing it to a face, without paying execution cost or polluting result caches.
  2. Validating column references. Confirm that a SQL string returns the columns a downstream chart or query expects.

Combine with dft validate-query for the full pre-flight: structural validation + schema introspection, all without executing.