SQL EditorSQL frameworks

Dataform

Paste a Dataform SQLX file and the editor treats it as SQL. Completions, diagnostics, hover, and cost estimates work on the resolved BigQuery query, and template expressions resolve through mappings you keep in a side panel, with no Dataform CLI or compilation step.

daily_orders.sqlx · Dataform

123456789

config {
type: "incremental",
schema: "warehouse"
}

SELECT order_id, user_id, amount, order_date
FROM ${ ref("orders") }
WHERE order_date >= ${ dataform.projectConfig.vars.start_date }
${ when(incremental(), "AND order_date > (SELECT MAX(order_date) FROM " + self() + ")") }

How SQLX becomes SQL

Dataform mode switches on for a tab as soon as the text contains a ${ expression, or a line that starts with config {, js {, pre_operations {, or post_operations {. A Dataform button appears in the status bar; the tab’s language switches to a SQLX-aware highlighter. Before every parse, dry run, and run, the file is rewritten to plain BigQuery SQL:

In the file	Becomes
`config { … }`, `js { … }`, `pre_operations`, `post_operations` blocks	Removed. Their contents are highlighted but never read
`${ ref("orders") }`, `${ resolve("…") }`	The mapped table, or a placeholder identifier if unmapped
`${ self() }`	The Self table from the panel’s Options
`${ dataform.projectConfig.vars.x }`	The mapped value as a quoted string literal
`${ when(incremental(), "…") }`	The quoted SQL if Incremental mode is on, nothing otherwise
Any other `${ … }`	A placeholder identifier

Everything downstream (the schema tree, column completions, diagnostics, the cost footer) sees the rewritten SQL. That is why unresolved references matter: a placeholder table has no columns.

Mapping references to tables

References resolve through mappings. Open the panel with the Dataform status-bar button, or accept the quick fix on an unresolved reference:

SELECT *
FROM ${ ref("orders") }

The quick fix opens the panel with the form prefilled. The panel’s sections:

Active Directives: every ref(), resolve(), self() and project variable in the tab, with its resolved table or Unresolved — add mapping.
Detected Tables: plain table references in FROM/JOIN. Convert to Dataform ref rewrites one to ${ ref("…") } and saves the mapping.
Detected Values: string literals. Convert to Dataform variable replaces one with a project variable.
Table Mappings: ref and resolve keys → BigQuery tables. Remove unused drops mappings the current SQL doesn’t reference.
Variable Mappings: variable name → value.
Options: Self table, Incremental mode, Auto-apply saved mappings.

Mappings are global: set orders once and every tab resolves it. Detection is per tab.

Import dataform.json

The upload icon in the panel header opens Import Dataform Config. Upload or paste your project’s dataform.json; the preview counts declarations and variables, then Merge adds to your mappings or Replace All overwrites them. Declarations import as resolve mappings, and vars as variable mappings; ref mappings are yours to add.

Completions, hover, and diagnostics

Inside ${ } the completion list is the SQLX vocabulary; inside ref("…") and resolve("…") it is your saved mapping keys.

FROM ${

ref Reference a Dataform action

resolve Resolve a fully qualified table name

self Reference to current table

when Conditional SQL

incremental Check if running in incremental mode

dataform.projectConfig.vars Access project variables

Hover any expression to see what it resolves to. With Inlay Hints on (Settings → SQL Frameworks → Dataform), the resolved table is drawn right after the closing brace:

FROM ${ ref("orders") }

ref("orders")

Resolves to ace-analytics.warehouse.orders

Diagnostics you may see:

Squiggle	Meaning
Unresolved ref / resolve / variable	No mapping yet; quick fix available
self() used but no self table configured	Fill Self table in Options
Unknown SQLX function	Only `ref`, `resolve`, `self`, `when`, `incremental` are recognized
Unclosed `${...}` expression	Error; nothing after it is analyzed

Turning Dataform mode off

Enable Dataform Mode and its Inlay Hints are both on by default, under Settings → SQL Frameworks → Dataform (the full section is on the Settings page). To turn the mode off for one tab only, right-click the Dataform status-bar button → Deactivate Dataform mode; the button stays, dimmed, to reactivate.

A tab runs in either Dataform or dbt mode, never both; see dbt and Dataform in one file.