Skip to main content

Troubleshooting and FAQ for Node Type V2

Use this page when a V2 Node does not parse, columns look wrong, lineage, or DAG edges are missing, or you need the current limits and answers to common questions.

Troubleshooting​

Columns Not Appearing After Saving​

You save your SQL but the Columns tab shows no columns, or fewer columns than you expect. Work through these causes:

  • Missing aliases on expressions - Coalesce infers column names from your SELECT clause. Complex expressions without an alias, for example L_EXTENDEDPRICE * (1 - L_DISCOUNT), can produce an unexpected name or fail to parse. Add an explicit alias: L_EXTENDEDPRICE * (1 - L_DISCOUNT) AS discounted_price.
  • Parse error earlier in the file - A syntax error above your final projection can stop the parser from reading downstream columns. Look for an error indicator in the editor, fix the issue, and save again.
  • SELECT * from a CTE or upstream Node - SELECT * records Node-level lineage and does not populate the column grid with named columns the way explicit projections do. List column names when you need column-level lineage in the grid.

Column Data Type Shows as UNKNOWN​

The Columns tab shows UNKNOWN as the data type for one or more columns when Coalesce cannot infer a type from a complex expression. Add an explicit cast in your SQL:

value::TIMESTAMP_NTZ
CAST(value AS DECIMAL(12,2))

Ref Helper Not Appearing as a DAG Dependency​

An upstream Node you reference with {{ ref() }} does not show as a connected dependency in the DAG view, even though the warehouse runs the SQL.

{{ ref() }} calls inside deeply nested subqueries do not always register as DAG dependencies. The warehouse still runs the SQL, but the Coalesce parser does not detect the reference.

Restructure the query so the ref sits in a top-level CTE:

-- Harder for the parser to detect:
SELECT *
FROM (
    SELECT order_id FROM {{ ref('STAGING', 'STG_ORDERS') }}
) sub

-- Easier for the parser to detect:
WITH orders AS (
    SELECT order_id FROM {{ ref('STAGING', 'STG_ORDERS') }}
)
SELECT * FROM orders

Parse Error on Save​

Coalesce shows an error with a line and column number when you save. Your SQL stays in the editor, and a parse error does not roll back previously compiled output or the deployed table. Fix the issue and save again.

Common causes include mismatched parentheses, an unclosed CTE block, or Jinja outside the supported ref pattern. For what is supported today, read Jinja Templates Beyond Ref in Known Limitations.

Annotations Not Taking Effect​

You added an annotation but the Node does not behave the way you expect, for example @insertStrategy("MERGE") without MERGE behavior in the compiled SQL.

Custom annotations have no built-in behavior unless your Create or Run template reads them. Parsing writes values into the Node's metadata. The template decides what SQL to emit.

Open the Node type's Run template and confirm it branches on the annotation. A MERGE path typically checks something like config.insertStrategy.parameters[0] == 'MERGE' before emitting MERGE SQL. See the SQL Annotations Reference for template examples.

Lineage Missing Through Subqueries​

Column-level lineage is incomplete or missing for columns that flow through a subquery.

Use CTEs instead of deeply nested subqueries. The parser traces lineage through CTE steps and does not always follow lineage through nested subqueries. A CTE chain usually restores column-level lineage.

Known Limitations​

Entries marked By design are intentional. Entries marked Planned are on the roadmap but not shipped yet.

Jinja Templates Beyond Ref​

Planned. The SQL editor supports {{ ref() }} for upstream references. General Jinja, including custom macros, package macros, environment variables, and conditional blocks, is not supported. If you rely on patterns such as {{ env.database }}, use a mapping-grid Node type for those Nodes.

Column Propagation From Upstream Nodes​

By design. When columns are added to an upstream Node, they do not automatically flow into downstream V2 Nodes. Your SQL is the source of truth. Add the new columns to your SELECT, or use SELECT * for broader propagation with the trade-off of limited column-level lineage in the grid.

Lineage and Refs Inside Subqueries​

Known limitation. {{ ref() }} inside subqueries can fail to register as DAG dependencies, so upstream Nodes might not show as connected in lineage views even though execution succeeds. Prefer CTEs so refs resolve and lineage stays consistent.

Copilot Integration​

Planned. Copilot does not support creating or editing V2 Nodes.

Platform Support​

Snowflake. Node Type V2 is supported on Snowflake. Databricks and BigQuery are not supported for V2.

No Mapping To SQL Conversion​

By design. There is no automated conversion from a mapping-grid V1 Node to a V2 Node. Add a new Node that uses a V2 Node type and rewrite the transformation in SQL. See Upgrading from V1 to V2 Node Types.

FAQ​

Can You Mix V1 and V2 Nodes in the Same Pipeline?​

Yes. Node Type V2 is additive. It does not remove mapping-grid Node types. Both run in the same Workspace and pipeline. You pick the version per Node type. V1 and V2 Nodes connect through {{ ref() }} like any other Nodes.

Do You Lose Lineage When Using V2 Nodes?​

No. Coalesce parses {{ ref() }} to maintain DAG lineage, including column-level lineage for explicitly named columns. SELECT * records Node-level lineage only.

Can You Convert an Existing Mapping-Grid Node to V2?​

Not automatically. Create a new Node on a V2 Node type and rewrite the transformation in SQL. Follow Upgrading from V1 to V2 Node Types.

What Happens on a Parse Error?​

Coalesce shows an error with line and column information when it is available. Your SQL stays in the editor. Parse errors do not change previously compiled output or the deployed table on their own. Fix the error and save again.

Do You Need to Use the Ref Helper?​

Yes. {{ ref('STORAGE_LOCATION', 'NODE_NAME') }} is how Coalesce tracks dependencies and builds the DAG. Hard-coded table names do not create edges in the graph, and Job ordering does not treat them as declared dependencies.

How Do Annotations Work?​

In V2, annotations are how you set Node configuration. There is no mapping-grid config sidebar for those options. Parsed annotations populate the Node metadata. Removing an annotation falls back to the Node type default. See the SQL Annotations Reference.

Is There a Query Size Limit?​

There is no fixed character cap. Very large queries with hundreds of columns can take longer to parse.

How Is V2 Different From Override Create SQL?​

The V2 SQL editor replaces the mapping grid. You write a SELECT and Coalesce derives columns from it. Override Create SQL replaces the generated CREATE DDL and applies to views in that workflow. V2 is for authoring transformations. Override Create SQL is for customizing DDL output.

Can You Use V2 With Custom Node Types?​

Yes. Create a V2 Node type from the Create Node Type menu under Build Settings > Node Types, or duplicate an existing V2 type. If you use custom templates, add {{ source.cteString }} to the Run template when you need CTE text passed through.

What SQL Constructs Are Supported?​

CTEs, JOINs, window functions, aggregations, CASE expressions, UNION, subqueries, casting, and most standard Snowflake SQL you would run in a SELECT pipeline are supported.

What About the inputMode SQL Setting?​

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

Can You Use Stored Procedures?​

The main body of the file must be a SELECT. You can run procedure calls from a @preSQL annotation, for example @preSQL("CALL my_schema.my_proc()"). If the Node must deploy procedure DDL, handle that in custom templates.

What's Next?​