# Dataform

> Paste a Dataform SQLX file and the editor treats it as SQL. Completions, checks, 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.

Source: https://docs.querylab.io/writing-sql/dataform-support/

**daily_orders.sqlx · Dataform**

```sql
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 and the tab switches to SQLX highlighting. The file resolves to plain BigQuery SQL the same way a [dbt model](https://docs.querylab.io/writing-sql/dbt-support/#how-jinja-becomes-sql) does:

| 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                                        |

An unresolved reference has no columns, so completions and checks go quiet for it.

## 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:

```sql
SELECT *
FROM \${ ref("«warn: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**. `${self()}` keeps its warning; the query still runs.

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 checks

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

```sql
FROM \${
```

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:

```sql
FROM \${ ref("«hl:orders»") }
```

Warnings 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 checked                                  |

## 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](https://docs.querylab.io/settings/#sql-frameworks) 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](https://docs.querylab.io/writing-sql/dbt-support/#dbt-and-dataform-in-one-file).