Skip to main content

Documentation index: llms.txt. This page is also available as markdown: append .md to this URL or send Accept: text/markdown.

Choosing Between YAML and SQL Node Types

Coalesce supports two kinds of Node Type. Both are fully supported, run in the same Workspace, and connect in the same DAG. You choose YAML or SQL per Node Type, based on the kind of work each layer of your pipeline does.

  • A YAML Node Type is pattern-first. You configure each Node through the mapping grid and a structured config panel, and the Node Type's templates apply a proven pattern such as a Dimension or Fact.
  • A SQL Node Type is SQL-first. You author each Node as a SQL SELECT, and configure it with inline annotations. Columns and dependencies are inferred from your SQL.

This is not a case of one replacing the other. Each is the better tool for a different part of your pipeline.

Formerly Node Type V1 and V2

Earlier releases called these Node Type V1 (mapping-grid authored) and Node Type V2 (SQL authored). The Coalesce app still labels the choice Node V1 and Node V2 under Build Settings > Node Types, and its Version column shows V1 or V2. YAML Node Types are V1; SQL Node Types are V2.

The Short Answer​

LayerUseWhy
Persistent, curated layers such as Dimensions and FactsYAMLHardened, battle-tested patterns for history tracking, merges, and schema evolution
Staging, work, and other transformation-heavy layersSQLFreeform SQL, CTEs, and code-first iteration fit layers that are rebuilt freely

When YAML Nodes Fit​

Choose YAML Nodes where the table persists and the pattern matters more than the SQL:

  • Dimensions, Facts, and other history-keeping Nodes. Coalesce's YAML packages implement patterns such as Type 2 slowly changing dimensions that have been hardened and proven in production over years.
  • In-place schema evolution. YAML Nodes keep a stable column identity, so renaming a column renames it in the warehouse and keeps the data. SQL Nodes treat the column name in your SELECT as its identity, so a rename deploys as a new column.
  • Structured, repeatable configuration. Business keys, change tracking, and merge strategies are selected in the config panel and applied consistently by the template.

When SQL Nodes Fit​

Choose SQL Nodes where SQL is the natural starting point and tables are freely rebuilt:

  • Heavy transformation logic. Complex joins, CTEs, and window functions live in one readable SELECT instead of being split across per-column mappings.
  • Migrating SQL into Coalesce. Bring existing SQL, dbt models, or stored procedure logic in with minimal refactor.
  • Code-first and AI-assisted workflows. Each Node is a plain .sql file you can author in the Coalesce editor, an IDE, or with an AI assistant, and version in Git like any other code.
  • Staging-style materialization. Tables that are truncated and reloaded, or dropped and recreated, on every run.
Why the layer guidance works

Staging tables are rebuilt constantly, so a SQL Node's flexible, code-first authoring is an advantage and column identity rarely matters. Persistent tables carry history across runs, so a YAML Node's stable column identity and curated merge patterns protect your data. Match the kind of Node to how the table lives, and both do what they are best at.

Using Both in One Pipeline​

Most pipelines should use both. A typical shape:

  1. Stage with SQL Nodes. Author your transformation logic as SQL, one .sql file per Node.
  2. Model with YAML Nodes. Build Dimensions and Facts on YAML Node Types from Coalesce packages.
  3. Wire the DAG with {{ ref() }}. References work identically whether the upstream Node is YAML or SQL, and lineage spans both.

Moving Between YAML and SQL​

There is no automatic conversion between YAML and SQL Nodes. They store configuration differently by design, so pick the right kind when you create a Node Type rather than planning to convert later.

  • If a table's role changes, rebuild the Node on the other kind where it makes sense, and keep {{ ref() }} references pointing at the same Node name.
  • If you used the deprecated inputMode: 'sql' setting on YAML Node Types, re-create those Nodes on a SQL Node Type; the Troubleshooting and FAQ covers the deprecation.

Guidance for broader YAML-to-SQL moves will expand as SQL Node capabilities grow.

Data Platform Support​

SQL Node Types are supported on Snowflake and BigQuery. YAML Node Types are supported on all Coalesce data platforms.

What's Next​