Authoring derived tables (DBTs)

A DBT is a saved SELECTover your project’s sources or other DBTs. The SQL is the DBT — every downstream visualization re-reads it whenever upstream data changes. The materialized Parquet next to the DBT is just a cache.

Three ways to create one

• From scratch — + DBTin the project sidebar. Type SQL; the editor autocompletes table and column names from the project’s schema, and the preview pane runs the query against DuckDB-WASM as you type.
• From a cross-filter — on any dataset, set up the filters you want and click Promote to DBT. ST-1 writes a parameterized WHERE clause for you.
• From a quality report — sources flagged with fixable issues offer a one-click Create cleanup DBT that bakes the suggested fixes into a <source>_clean table.

What the editor does

• Autocompleteagainst the project’s schema — table names from sources and DBTs, column names once you’re inside a SELECT.
• Live preview — DuckDB-WASM runs the query in your browser and shows the first 100 rows + execution time.
• Validation— saving runs the SQL through DuckDB and rejects the DBT if it doesn’t parse, doesn’t execute, or returns zero columns.

Editing a DBT

DBTs are not snapshots — editing the SQL re-materializes the cache and every downstream chart picks up the change. If a downstream DBT references columns that are no longer produced, you’ll see the failure on its detail page; ST-1 flags broken references explicitly rather than silently dropping them.

Reading the SQL

Every DBT page shows its definition. Copy it; rewrite it; the canonical truth is what you read. The web UI wraps the editor in a Definition panel; the MCP surface returns the same SQL string on get_dataset.