Dataform DAG Explorer for VS Code

Dataform DAG Explorer is an unofficial community extension. It is not affiliated with or endorsed by Google.

This project is based on the MIT-licensed dataform-dag project by cadamsmith and includes substantial additional functionality for compiled graphs, compiled SQL preview, filtering, navigation and diagnostics.

Explore a local Dataform project's dependency graph directly inside VS Code.

The extension supports both a fast .sqlx parser and an optional high-fidelity graph based on:

dataform compile --json

A BigQuery connection is not required for graph rendering or local SQL compilation.

Local Dataform compilation does not execute SQL, perform a BigQuery dry run, or validate warehouse tables/columns.

Features

Parsed and Compiled graph modes

Use the Graph selector in the top bar.

Parsed

• Default mode.
• Parses .sqlx files locally.
• Fast.
• Works while the Dataform project has compilation errors.
• Does not require the Dataform CLI.

Compiled

• Uses the resolved output of dataform compile --json.
• Includes higher-fidelity dependencies.
• Includes generated actions such as inline assertions.
• Resolves dependencies produced through JavaScript/includes more accurately.
• Reuses the same cached compilation output used by Compiled SQL.

Compiled SQL inside the graph

Select a node and choose Compiled SQL.

The detail panel expands to show locally resolved SQL, including where available:

• standard query SQL,
• operation query arrays,
• full/initial incremental query,
• incremental query,
• pre_operations,
• post_operations,
• incremental pre/post-operation variants.

Controls:

• Copy — copy the full preview.
• Hide — collapse the SQL preview.

The extension resolves Dataform constructs such as variables, ${...}, ref(), self(), includes and JavaScript through the local Dataform compiler.

Compilation cache and status

The extension shows compilation state in the node detail UI:

• Compiling…
• ✓ Compiled
• compilation failure

Compilation output is cached and warmed in the background.

Rapid file changes are debounced, and the extension avoids running multiple Dataform compilations concurrently.

Relevant changes invalidate the cache, including:

• .sqlx,
• .js,
• .mjs,
• .cjs,
• workflow_settings.yaml,
• workflow_settings.yml,
• dataform.json.

Tag filtering

Open the Tags picker to select one or more tags.

Examples:

silver + gold

orders + finance

The extension does not assign meaning to tags; they remain generic Dataform metadata.

The picker supports:

• search,
• multi-selection,
• scroll for large tag sets,
• Clear all,
• persistence per VS Code workspace.

A node is visible if it contains at least one selected tag.

Dependency context

When a tag filter is active, enable Context to show one direct upstream/downstream boundary around matching nodes.

Example:

raw_source        context
    │
    ▼
silver_orders     matched
    │
    ▼
silver_clean      matched
    │
    ▼
gold_sales        context

Context is intentionally one hop only.

Node search

Use Search nodes... to find a node by target name.

Selecting a result:

• selects the node,
• opens its detail panel,
• centers the graph on it.

Search operates on the currently visible graph.

Graph diagnostics

The extension can report structural issues while still rendering the DAG:

• unresolved references/dependencies,
• duplicate node IDs.

In Parsed mode, unresolved references should be treated as advisory because some dependencies may be generated by JavaScript and only become visible in Compiled mode.

Live updates

Saving Dataform project files automatically refreshes the relevant graph/compile state.

Parsed mode remains responsive and tolerant; Compiled mode refreshes through the debounced compilation pipeline.

VS Code theme integration

The graph UI follows VS Code light/dark theme colors for:

• backgrounds,
• text,
• buttons,
• dropdowns,
• search,
• graph controls and edges,
• diagnostics,
• SQL preview.

Node-type accent colors remain semantic and intentionally distinct.

Getting started

1. Open the extension for development

Open this folder in VS Code:

apps/extension

Press:

F5

This opens an Extension Development Host.

2. Open a Dataform project

In the Extension Development Host, open the root Dataform project folder.

Typical structure:

project/
├── definitions/
│   ├── customers.sqlx
│   └── orders.sqlx
├── includes/
└── workflow_settings.yaml

3. Open the graph

Open the Command Palette:

Ctrl+Shift+P

or on macOS:

Cmd+Shift+P

Run:

Dataform DAG Explorer: Show Graph

Requirements

Parsed graph

• VS Code 1.90.0 or newer.
• A Dataform project with .sqlx definitions.

Compiled graph / Compiled SQL

Additionally:

• Dataform CLI installed.
• dataform available on the extension host's PATH.
• The project must compile locally for the requested compiled result.

Example check from the project root:

dataform compile --json

If that command fails, Parsed mode can still remain useful.

What "Compiled SQL" means

The extension performs:

Dataform project
      ↓
dataform compile --json
      ↓
resolved SQL preview

It does not perform:

BigQuery execution
BigQuery dry run
warehouse metadata validation
table existence checks
column/type validation

Those operations require BigQuery and are outside the local preview feature.

Node identity

Nodes are keyed by Dataform target name:

config.name ?? filename-without-.sqlx

For example:

config {
  type: "operations",
  name: "publish_customers",
  dependencies: ["customers_incremental"]
}

The graph node ID is:

publish_customers

not the .sqlx filename.

Parsed-mode boundaries

Parsed mode intentionally uses lightweight source parsing.

Compared with Compiled mode:

• generated assertions may not appear as separate nodes,
• JavaScript-generated refs/actions may be incomplete,
• a dependency that looks unresolved to the parser can be valid after compilation.

Use Compiled mode when you need Dataform's resolved graph.

Commands

Dataform DAG Explorer: Show Graph

Opens or reveals the DAG panel.

Dataform DAG Explorer: Show Compiled SQL

Compiles the active .sqlx action locally and opens its compiled SQL using the extension command workflow.

The graph's Compiled SQL button instead shows the preview inline in the node detail panel.

Development

From the repository root:

npm install
npm run build:core
npm run typecheck
npm test

If exported core types changed, npm run build:core is required before consumer typechecking because package type declarations are emitted under packages/core/dist.

Package the VS Code extension

From this directory:

npm run package

The project bundles the extension and webview before creating the .vsix.

After packaging, manually smoke-test:

• installation,
• Parsed graph,
• Compiled graph,
• Compiled SQL,
• node/file navigation,
• tag persistence,
• Context,
• search,
• diagnostics,
• light/dark themes.

Architecture notes

The extension is one host for the shared packages/ui application.

Communication occurs through the shared HostBridge protocol.

Important constraints:

• Keep the webview bundle compatible with the current CSP/nonced-script model.
• Do not make UI runtime code depend on Node-only core modules.
• Reuse the compilation cache for both Compiled graph and Compiled SQL.
• Do not run concurrent Dataform compilations.
• Preserve generation checks so stale compile results cannot replace current output.
• Parsed mode must remain usable without successful Dataform compilation.

Source

Repository:

https://github.com/JaimeLapaz/dataform-dag