Skip to main content

dbt Support

Querylab.io natively supports dbt Jinja SQL. Write and test dbt models directly in the editor with full completions, diagnostics, compiled preview, and mapping management — no dbt CLI required.

Getting Started​

dbt mode activates automatically when Querylab.io detects Jinja patterns in your SQL:

  • {{ ... }} Jinja expressions
  • {% ... %} Jinja blocks
  • {# ... #} Jinja comments
  • -- dbt:* directive comments

Paste any dbt model SQL into the editor and the dbt panel appears automatically.

Enable/Disable​

dbt mode is enabled by default. To toggle it:

Settings > SQL Frameworks > Enable dbt Mode

See Settings for all dbt-related settings.

The dbt Panel​

When dbt mode activates, a dbt button appears in the status bar at the bottom of the editor. Click it to open the dbt panel on the right side.

  • Left-click the status bar button to toggle the panel
  • Right-click the button to deactivate dbt mode for this tab

The panel has six sections:

Active Directives​

Lists all dbt directives found in your SQL. Each shows the directive call and its resolution status:

  • Resolved: Shows the mapped BigQuery table (e.g., project.dataset.users)
  • Unresolved: Shows "Unresolved — add mapping" — click to add a mapping

Hover over a directive to edit or delete it.

Detected Tables​

Tables from your FROM and JOIN clauses that are not yet converted to dbt refs. Click Convert to dbt ref to replace the table reference with {{ ref('model_name') }}.

Detected Values​

String literal values in your SQL that could be extracted as dbt variables. Click Convert to dbt var to replace the value with {{ var('variable_name') }}.

Table Mappings​

Manage your ref() and source() mappings. Each mapping connects a dbt model or source name to its BigQuery table.

  • Add new mappings with the Add new mapping form
  • Search mappings when you have 5 or more
  • Remove unused clears mappings not referenced in the current SQL

Mappings are saved globally and reused across tabs.

Variable Mappings​

Manage your var() mappings. Each maps a variable name to its resolved value.

Options​

OptionDescription
Incremental modeWhen enabled, {% if is_incremental() %} blocks are kept during preprocessing. When disabled, they are stripped.
Auto-apply saved mappingsAutomatically resolve {{ ref() }} and {{ var() }} using your saved mappings.

Directives​

Directives are SQL comments that configure dbt mappings inline. They travel with your SQL and are the primary way to define mappings.

-- dbt:ref('users') = my_project.analytics.users
-- dbt:ref('orders') = my_project.analytics.orders
-- dbt:source('raw', 'events') = my_project.raw_data.events
-- dbt:var('start_date') = 2024-01-01
-- dbt:project = my_project
-- dbt:dataset = analytics
-- dbt:model = daily_users

SELECT *
FROM {{ ref('users') }} u
JOIN {{ ref('orders') }} o ON u.id = o.user_id
WHERE o.created_at >= '{{ var("start_date") }}'

Directive Types​

DirectivePurpose
-- dbt:ref('name')Declare a ref (unresolved)
-- dbt:ref('name') = project.dataset.tableDeclare a ref with resolution
-- dbt:source('schema', 'table')Declare a source
-- dbt:source('schema', 'table') = project.dataset.tableDeclare a source with resolution
-- dbt:var('name')Declare a variable (unresolved)
-- dbt:var('name') = valueDeclare a variable with value
-- dbt:project = nameSet project for {{ this }} resolution
-- dbt:dataset = nameSet dataset for {{ this }} resolution
-- dbt:model = nameSet model name for {{ this }} resolution

Inline directive resolutions (with =) take precedence over global mappings.

Compiled View​

Click View compiled SQL in the panel header to preview the fully resolved BigQuery SQL.

The compiled view:

  1. Resolves all {{ ref() }}, {{ source() }}, and {{ var() }} to their mapped values
  2. Handles {% if is_incremental() %} blocks based on the incremental mode toggle
  3. Strips Jinja comments ({# ... #})
  4. Shows the final SQL that would run against BigQuery

The editor becomes read-only in compiled view. Click View source SQL to switch back.

Inlay Hints​

When enabled, resolved values appear inline after Jinja expressions as faded annotations:

SELECT *
FROM {{ ref('users') }}         -- → my_project.analytics.users
WHERE date >= '{{ var("start_date") }}'  -- → 2024-01-01

Toggle in Settings > SQL Frameworks > dbt > Inlay Hints.

Completions​

Inside Jinja expressions, Querylab.io provides context-aware completions:

  • Inside {{ }}: Suggests ref, source, var, config, this, is_incremental
  • Inside {{ ref(' }}: Suggests known model names from your mappings
  • Inside {{ source('schema', ' }}: Suggests table names for that source
  • Inside {% %}: Suggests Jinja keywords (if, endif, for, endfor, etc.)

Diagnostics​

Querylab.io flags dbt issues with editor squiggles:

  • Unresolved ref: {{ ref('unknown_model') }} — warning with quick fix to add mapping
  • Unresolved source: {{ source('unknown', 'table') }} — warning
  • Unresolved var: {{ var('unknown') }} — warning
  • Malformed patterns: {{ ref( }} — error

Click the lightbulb or press Cmd/Ctrl+. to access quick fixes.

Import Manifest​

Bulk-import mappings from your dbt project's manifest.json:

  1. Click the Import button (upload icon) in the panel header
  2. Paste the contents of your target/manifest.json file
  3. Review the preview showing counts of models, sources, and variables
  4. Choose Merge (add to existing mappings) or Replace (overwrite all)

Export dbt Model​

Generate a dbt model from your current SQL:

  1. Click Export dbt Model in the panel footer
  2. Set the model name (auto-filled from tab name)
  3. Choose materialization: view, table, incremental, or ephemeral
  4. Download the generated .sql file and schema.yml with inferred column types

Context Menu​

Right-click in the editor when dbt mode is active for additional actions:

  • Convert to dbt ref — Replace selected table name with {{ ref('...') }}
  • Convert to dbt var — Replace selected value with {{ var('...') }}

Keyboard Shortcuts​

ActionShortcut
Toggle dbt panelCmd/Ctrl+Shift+B