Skip to main content

Node Type V2

Node Type V2 is a SQL-first authoring experience. You write a SQL SELECT in the Coalesce editor, in an IDE, or with an AI assistant. Coalesce infers columns, data types, and upstream dependencies. Per-Node options such as truncate-before-insert, Pre-SQL, and insert strategy are expressed as inline annotations in the SQL file.

Node types still use a YAML definition plus Create and Run templates. You declare which annotations a type supports in the definition, wire them in templates, then set values in each Node's SQL, or in Options when the definition exposes toggles and fields. See How V2 Annotations Reach Deployed SQL.

When V2 Fits Your Workflow​

The mapping grid still works well for visual, low-code modeling. Choose V2 when SQL is the natural starting point:

  • Migrating SQL into Coalesce - Bring existing SQL, dbt models, or stored procedure logic without splitting it into per-column mappings.
  • CTE-heavy logic - Represent CTEs inside a single Node, which the mapping grid does not support.
  • AI-generated SQL - Check in full SELECT statements and keep lineage and governance in Coalesce.
  • Code-first workflows - Version transformations as plain .sql files next to the rest of your code.
V2 Node open in the Build editor with the SQL panel active instead of the mapping grid.

How V1 and V2 Differ​

Use this table to compare authoring and storage. Execution, templates, and pipeline behavior are covered in the next section.

V1 Node TypeNode Type V2
AuthoringMapping gridSQL editor
File format.yml.sql
Column definitionManually mapped in the gridInferred from your SELECT clause; the column list is read-only in the UI
Source dependenciesSelected in the UIDeclared with {{ ref() }} in SQL
Per-Node configurationConfig panel on each NodeInline SQL annotations and Options; see SQL Annotations Reference
CTE supportNot available inside a single NodeSupported natively
Node type specsConfig items in the YAML definitionConfig items in the YAML definition declare which annotations the type supports; templates consume them

V1 and V2 coexist in the same Workspace and pipeline. You choose the version per Node type, and {{ ref() }} works the same whether the upstream Node is V1 or V2.

V1 inputMode SQL setting is deprecated

The older inputMode: 'sql' setting on V1 Node type definitions is deprecated and will be removed in a future release. Node types that use it show a deprecation warning in the Coalesce App. See Upgrading from V1 to V2 Node Types to migrate.

How V2 Annotations Reach Deployed SQL​

An annotation in Node SQL does not change warehouse behavior by itself. Work through these layers for every option you want to use, for example @truncateBefore, @preSQL, @insertStrategy, or column flags such as @isBusinessKey:

  1. Node type definition - Declare the option as a config item in the YAML definition so Coalesce registers the annotation, applies defaults, and can show Options controls. Match attributeName to the annotation name, for example truncateBefore for @truncateBefore, or any name you define, such as myLoadMode for @myLoadMode. See Node Config Options and Getting Started with Node Type V2.
  2. Create and Run templates - Read the hydrated metadata in Jinja, for example config.truncateBefore, config.preSQL.parameters, or column.isBusinessKey, and emit the matching DDL or load stages.
  3. Node SQL - Set the annotation on the Node, or use Options when the definition exposes the field.

If any layer is missing, the annotation may parse but the compiled plan can omit the stage you expect. That can surface as a successful run with no error, for example insert-only loads when truncate was intended.

What Stays the Same in Your Pipeline​

Templates (Create, Run, Join, Macro), deployment, execution, DAG and column-level lineage, testing, and governance policies work the same as for other Node types.

Data Platform Support​

Node Type V2 is supported on Snowflake.

What's Next?​