Comments

{# … #} Jinja comments, and how they attach to the code above and below them.

Each pair below is a real, passing case from dfmt's test corpus (suites/dfmt-jinja/cases/comments/): the template as written, then the same template after dfmt — every Jinja tag reproduced exactly, the SQL laid out around it. 48 examples.

A block comment holding tags stays verbatim

Before

{% set start_date = '2021-01-01' %}
with a as (
    select x from t
),
/*
b as (
    select y
    from u
    {% if is_incremental() %}
    where evt_block_time >= date_trunc('day', now() - interval '1 week')
    {% endif %}
    {% if not is_incremental() %}
    where evt_block_time >= '{{start_date}}'
    {% endif %}
),
*/
c as (
    select z from v
)
select * from a

After

{% set start_date = '2021-01-01' %}

with
    a as (select x from t),

    /*
        b as (
            select y
            from u
            {% if is_incremental() %}
            where evt_block_time >= date_trunc('day', now() - interval '1 week')
            {% endif %}
            {% if not is_incremental() %}
            where evt_block_time >= '{{start_date}}'
            {% endif %}
        ),
    */
    c as (select z from v)
select *
from a

A branch body with no comment formats the sql after it

dialect snowflake

Before

{% if flag %}
    {% set d = "a" %}
{% endif %}

select   1   as x

After

{% if flag %}
    {% set d = "a" %}
{% endif %}

select 1 as x

A comment above a cte stays on its own line

Before

with
    {# Historical subscriptions from legacy models #}
    legacy_mapping as (select title_code from a),

    {# Subscriptions in the vendor system right now #}
    vendor_mapping as (select title_code from b)

select * from legacy_mapping

After

with
    {# Historical subscriptions from legacy models #}
    legacy_mapping as (select title_code from a),

    {# Subscriptions in the vendor system right now #}
    vendor_mapping as (select title_code from b)

select *
from legacy_mapping

A comment above a glue guard stays above it

Before

-- a plain note

{% if var('never', false) -%}
    {% set results = ['a', 'b'] %}
{% endif -%}

select
    ticket_id,
    valid_starting_at
from enriched

After

-- a plain note

{% if var('never', false) -%}
    {% set results = ['a', 'b'] %}
{% endif -%}

select ticket_id, valid_starting_at
from enriched

A comment above a guard between ctes stays out of its else

Before

with emails as (
    select * from a
),
-- note
{% if var('x', False) %}
    o as (select * from b),
{% else %}
    {% set w = 1 %}
    o as (select * from c),
{% endif %}
d as (select * from o)
select * from d

After

with
    emails as (select * from a),

    -- note
    {% if var('x', False) %}
        o as (select * from b),
    {% else %}
        {% set w = 1 %}
        o as (select * from c),
    {% endif %}

    d as (select * from o)
select *
from d

A comment above a guard does not ride the next set

Left unchanged — already in dfmt's shape:

-- c
{% if x %}
    {% set d = "a" %}
{% endif %}

{% set ps = ["p1"] %}

select a
from t

A comment above a right trimmed loop stays above it

Left unchanged — already in dfmt's shape:

select
    a,
    -- a note
    {% for c in cols -%}
        {{ c }},
    {% endfor %}
    b
from t

A comment above a vanished guard survives

Before

-- period definition
{% if true %}
    {% set x = 1 %}
{% else %}
    {% set x = 2 %}
{% endif %}

select    {{ x }} as a
from t

After

-- period definition
{% if true %}
    {% set x = 1 %}
{% else %}
    {% set x = 2 %}
{% endif %}

select {{ x }} as a
from t

A comment above an if else of sets survives

Before

-- nota
{% if flag %}
    {% set d = "a" %}
{% else %}
    {% set d = "b" %}
{% endif %}
select  *  from t

After

-- nota
{% if flag %}
    {% set d = "a" %}
{% else %}
    {% set d = "b" %}
{% endif %}
select *
from t

A comment above an untaken guard ships once

Before

select
  d.play_id,
  d.media_identifier

  -- passthrough fields
  {%- if var('cols', []) -%}
    {%- for col in var('cols', []) %}
      , d.{{col}}
    {%- endfor -%}
  {%- endif %}

from dedupe as d

After

select
    d.play_id,
    d.media_identifier

    -- passthrough fields
    {%- if var('cols', []) -%}
        {%- for col in var('cols', []) %}
            , d.{{col}}
        {%- endfor -%}
    {%- endif %}

from dedupe as d

A comment after a construct stays after it

Before

{% macro is_run_with_new_events(x) -%}
true
{%- endmacro %}
{% macro filter_bots() -%}
and useragent not like '%bot%'
{%- endmacro %}
select a
from t
where event_name in ('cmp_visible', 'consent_preferences')

and {{ is_run_with_new_events('snowplow_unified') }} --returns false if run doesn't contain new events.

{% if var("snowplow__ua_bot_filter", true) %}
    {{ filter_bots() }}
{% endif %}

After

{% macro is_run_with_new_events(x) -%}
    true
{%- endmacro %}

{% macro filter_bots() -%}
    and useragent not like '%bot%'
{%- endmacro %}

select a
from t
where
    event_name in ('cmp_visible', 'consent_preferences')

    and {{ is_run_with_new_events('snowplow_unified') }} --returns false if run doesn't contain new events.

    {% if var("snowplow__ua_bot_filter", true) %}
        {{ filter_bots() }}
    {% endif %}

A comment alone in a branch body stays inside it

dialect snowflake

Before

{% if flag %}
    {# note #}
{% endif %}

select   1   as x

After

{% if flag %}
    {# note #}
{% endif %}

select 1 as x

A comment in a cte does not cost the with its blank lines

dialect ansi · config keywordCase = upper, identifierCase = upper, functionCase = upper, dataTypeCase = upper, indentWidth = 2, maxLineWidth = 80, blankLineBetweenCtes = true, collapseShortStatements = false

Before

with first_cte as (
    select a, -- a note about this column
    b from t where a is not null and a > {{ 1 + 1 }}
),
second_cte as (
    select c from u where c is not null
)
select * from first_cte

After

WITH
  FIRST_CTE AS (
    SELECT
      A, -- a note about this column
      B
    FROM T
    WHERE A IS NOT NULL AND A > {{ 1 + 1 }}
  ),

  SECOND_CTE AS (
    SELECT C
    FROM U
    WHERE C IS NOT NULL
  )
SELECT *
FROM FIRST_CTE

A comment outside any block stays where it is

dialect snowflake

Before

{# note #}

select   1   as x

After

{# note #}

select 1 as x

A comment trailing a set run loses no tag

Before

{%- set a = 1 -%} --> first comment
{%- set b = 2 -%}
{%- set c = 3 -%} --> second comment
select 1    as x

After

{%- set a = 1 -%} --> first comment
{%- set b = 2 -%}
{%- set c = 3 -%} --> second comment
select 1 as x

A comment trailing a taken branch ships once

Before

{%- if flag %}
    {%- set x = 1 %}
{%- else %}
    {%- set should_run = true %} -- c
{%- endif %}
select * from t

After

{%- if flag %}
    {%- set x = 1 %}
{%- else %}
    {%- set should_run = true %} -- c
{%- endif %}
select *
from t

A comment welded to a loops first output survives

Left unchanged — already in dfmt's shape:

select
    a,
    -- a note
    {%- for c in cols -%}
        {{ c }},
    {% endfor %}
    b
from t

A commented out column stays above its comma

Before

select
    aa
    ,bb
    {# ,cc #}
    ,dd
from t

After

select
    aa,
    bb
    {# ,cc #}
    , dd
from t

A commented out guard stays in its comment

Before

select  a
from t
/*LEFT JOIN {{ source('base', 'u') }} u ON u.id = t.id
    {% if flag %}
    AND u.ts >= now()
    {% endif %}*/
{% if flag %}
where t.ts >= now()
{% endif %}

After

select a from t
/*LEFT JOIN {{ source('base', 'u') }} u ON u.id = t.id
    {% if flag %}
    AND u.ts >= now()
    {% endif %}*/
{% if flag %}
where t.ts >= now()
{% endif %}

A delimited comment is not a line comment

dialect postgres

Left unchanged — already in dfmt's shape:

select a, {# mid #} b from t

A depends on comment above a glue guard keeps its tag

Before

-- depends_on: {{ ref('stg_ticket_field_history') }}

{% if var('never', false) -%}
    {% set results = ['a', 'b'] %}
{% endif -%}

select
    ticket_id,
    valid_starting_at
from enriched

After

-- depends_on: {{ ref('stg_ticket_field_history') }}

{% if var('never', false) -%}
    {% set results = ['a', 'b'] %}
{% endif -%}

select ticket_id, valid_starting_at
from enriched

A depends on comment after the last statement

Before

select employee_number, worker_id, department_name, terminated_at from {{ ref('stg_workers') }} where terminated_at is null and department_name is not null

-- depends_on: {{ ref('stg_archive') }}
-- depends_on: {{ source("people", "src_numbers") }}

After

select employee_number, worker_id, department_name, terminated_at
from {{ ref('stg_workers') }}
where terminated_at is null and department_name is not null

-- depends_on: {{ ref('stg_archive') }}
-- depends_on: {{ source("people", "src_numbers") }}

A hash dialect keeps the comment on its own line

dialect bigquery

Before

select a, {# mid #} b from t

After

select
    a,
    {# mid #}
    b
from t

A jinja comment after an untaken guard stays after it

Left unchanged — already in dfmt's shape:

with
    {% if flag %}
        existing as (select * from u),
    {% endif %}

    {# Historical rows from legacy models #}
    legacy as (select a, b from t)

select distinct a, b
from legacy

A jinja comment glues to the statement below it

dialect ansi

Before

{{ config(materialized='table') }}
{# jinja note #}
select a from t

After

{{ config(materialized = 'table') }}

{# jinja note #}
select a
from t

A jinja comment on its own line keeps it

Before

select *
from {{ ref("spined") }}
{#
    on the live data view.
#}
-- noqa: disable=LT02
{% if is_incremental() -%}
where
    materialized_at > now()
{%- endif %}

After

select *
from {{ ref("spined") }}
{#
    on the live data view.
#}
-- noqa: disable=LT02
{% if is_incremental() -%}
    where materialized_at > now()
{%- endif %}

A line commented block stays commented

Before

select a
from t

-- {% if is_incremental() %}
--   where run_date > x
-- {% endif %}

After

select a from t

-- {% if is_incremental() %}
--   where run_date > x
-- {% endif %}

A line commented block with a resident ships once

Before

select    *
from {{ ref('user_data_department') }}

-- {% if is_incremental() %}

--   where run_date > (select max(run_date) from {{ this }})

-- {% endif %}

After

select * from {{ ref('user_data_department') }}

-- {% if is_incremental() %}

--   where run_date > (select max(run_date) from {{ this }})

-- {% endif %}

A loop tail trailing comment does not swallow what follows

dialect trino

Before

select
    case
        {%- for r in reasons %}
            when x = '{{ r }}'
                then 'a: {{ r }}'  -- noqa: LT05
        {%- endfor %}
        else 'b'
    end as c
from t

After

select
    case
        {%- for r in reasons %}
            when x = '{{ r }}' then 'a: {{ r }}' -- noqa: LT05
        {%- endfor %}
        else 'b'
    end as c
from t

A macros comment lines are not the authors

Before

{% macro base_accounts() -%}
select a, b
from t
where a is not null
--qualify dense_rank() over(
--    partition by a.effective_date
--) = 1
{%- endmacro %}
{{ base_accounts() }}

After

{% macro base_accounts() -%}
    select a, b
    from t
    where a is not null
    --qualify dense_rank() over(
    --    partition by a.effective_date
    --) = 1
{%- endmacro %}

{{ base_accounts() }}

A macros own comment is not the authors

Before

{% macro account_master() -%}
select a, b
from t
where a is not null --ignore header and tail records
{%- endmacro %}
{{ account_master() }}

After

{% macro account_master() -%}
    select a, b
    from t
    where a is not null --ignore header and tail records
{%- endmacro %}

{{ account_master() }}

A macros trailing comment stays inside its call

Before

{% macro count_tokens(col) %}
  length({{ col }}) / 4 -- 1 token is approximately 4 characters
{% endmacro %}
select
    *,
    {{ count_tokens("ticket_markdown") }} as ticket_tokens
from final

After

{% macro count_tokens(col) %}
    length({{ col }}) / 4 -- 1 token is approximately 4 characters
{% endmacro %}

select *, {{ count_tokens("ticket_markdown") }} as ticket_tokens
from final

A multiline jinja comment reanchors with its opener

Before

with source as (

    {#-
    Normally we would select from the table here, but we are using seeds
    #}
    select * from raw_customers

),

renamed as (
    select id from source
)

select * from renamed

After

with
    source as (
        {#-
            Normally we would select from the table here, but we are using seeds
        #}
        select *
        from raw_customers

    ),

    renamed as (select id from source)

select *
from renamed

A nested block comment in glue frames on its own close

dialect ansi

Before

{%- macro type_string() -%}
  {{ return(x) }}
{%- endmacro -%}

{%- macro type_float() -%}
  {{ return(y) }}
{%- endmacro -%}

/*
POSTGRES
/* Snowflake: this inner opener has no close of its own
*/

After

{%- macro type_string() -%}
    {{ return(x) }}
{%- endmacro -%}

{%- macro type_float() -%}
    {{ return(y) }}
{%- endmacro -%}
/*
    POSTGRES
    /* Snowflake: this inner opener has no close of its own
*/

A separator glued to a rendering construct stays glued

Before

{% macro fields(t) %}
    {{ t }}.p as p
{% endmacro %}
select
    a,
    -- c
    {{- fields("d") }},
    b
from t

After

{% macro fields(t) %}
    {{ t }}.p as p
{% endmacro %}

select
    a,
    -- c
    {{- fields("d") }},
    b
from t

A separator under comments joins its item

Before

select
    ct.contact_id as contact_id
    , cu.advisor as advisor_udf
    {# , coalesce(cu.advisor , ct.full_name) as advisor #} -- results ambiguous column down stream
    , cu2.field_value as preferred_pms
from t

After

select
    ct.contact_id as contact_id,
    cu.advisor as advisor_udf
    {# , coalesce(cu.advisor , ct.full_name) as advisor #}
    -- results ambiguous column down stream
    , cu2.field_value as preferred_pms
from t

A set block glued into a comment by trim keeps its own lines

Before

-- the first list drives feature usage
{%- set include_columns = [
    "actual_user_id", "context_feature_name",
] -%}

-- the second list appears in most tables
{% set extra_columns = [
    "plugin_version", "plugin_build",
] %}
select  id
from t

After

-- the first list drives feature usage
{%- set include_columns = [
    "actual_user_id", "context_feature_name",
] -%}

-- the second list appears in most tables
{% set extra_columns = ["plugin_version", "plugin_build",] %}

select id
from t

A tag inside a line comment stays in its comment

Before

select  *  from   t

-- {% if is_incremental() %}

--   where run_date > (select max(run_date) from s)

-- {% endif %}

After

select * from t

-- {% if is_incremental() %}

--   where run_date > (select max(run_date) from s)

-- {% endif %}

A trailing comment before a construct item survives

Before

{% macro translate_enum(k, col) -%}
case {{ col }} when 1 then 'yes' end
{%- endmacro %}
select
    i.dxc_appliedweight as appliedweight
    , i.dxc_maximumweight as maximumweight
    , i.dxc_storagecondition as storagecondition -- [appliedweight_name]
    , {{ translate_enum('isc', 'i.dxc_storagecondition') }} as storagecondition_name
    , i.dxc_legacyitemcode as legacyitemcode
    , i.dxc_legacyitemcode2 as legacyitemcode2
from t as i

After

{% macro translate_enum(k, col) -%}
    case {{ col }} when 1 then 'yes' end
{%- endmacro %}

select
    i.dxc_appliedweight as appliedweight,
    i.dxc_maximumweight as maximumweight,
    i.dxc_storagecondition as storagecondition, -- [appliedweight_name]
    {{ translate_enum('isc', 'i.dxc_storagecondition') }} as storagecondition_name,
    i.dxc_legacyitemcode as legacyitemcode,
    i.dxc_legacyitemcode2 as legacyitemcode2
from t as i

A trimmed comment above a set in a guard keeps its tag

Before

select   a
from t
{% if var('inc', false) %}
    {#- guard -#}
    {% set cols = 1 %}
    {% if cols %}
    where x = 1
    {% endif %}
{% endif %}

After

select a
from t
{% if var('inc', false) %}
    {#- guard -#}
    {% set cols = 1 %}
    {% if cols %}
        where x = 1
    {% endif %}
{% endif %}

A welded comment keeps both authors halves

Before

{%- set should_run = true %} -- If full_refresh, always run

{%- if should_run %} -- Run the query

SELECT 1    AS a

{%- endif %}

After

{%- set should_run = true %} -- If full_refresh, always run

{%- if should_run %}
    -- Run the query

    SELECT 1 AS a

{%- endif %}

An apostrophe in a jinja comment is not a quote

Before

{#
    why this model is incremental:
    we're not executing a recursive statement
#}
select  a
from t

After

{#
    why this model is incremental:
    we're not executing a recursive statement
#}
select a
from t

An arms trailing comment stays out of the loop below

Before

select
    case
        when a = 1 then 2 -- keep me
        {% for i in range(2, 4) %}
        when a = {{ i }} then {{ i }}
        {% endfor %}
        else 0
    end as v
from t

After

select
    case
        when a = 1 then 2 -- keep me
        {% for i in range(2, 4) %}
            when a = {{ i }} then {{ i }}
        {% endfor %}
        else 0
    end as v
from t

An end of file comment past a construct ships once

dialect ansi

Before

{{ config(materialized='table') }}
select a from {{ ref('m') }} -- note

After

{{ config(materialized = 'table') }}

select a
from {{ ref('m') }} -- note

Jinja comment owns its line end

Left unchanged — already in dfmt's shape:

select
    sum(
        {# TODO: exclude credits if current year Y1 is stored #}
        if(y1_letter_grade_adjusted not in ('F', 'F*'), potential_credit_hours, null)
    ) as projected_credits
from t

Own line comments after the last item stand with the next clause

Left unchanged — already in dfmt's shape:

select a
from {{ ref('bills') }} as b
where
    -- bills generated when practifi was the crm, defer to compass model post date
    b.billing_date < '2024-10-01'
    and b.is_head = 1
-- uncomment if "billing_frequency" or "revenue_category" is not hardcoded.
{# left join {{ ref('aux__stg_financials_fee_type') }} as ovrd_fee_type
    on bb.system_key = ovrd_fee_type.system_key #}
order by system_key, revenue_period_end_date

Trailing comments around construct items survive

Before

{% macro listagg(measure, delimiter_text, order_by_clause) -%}
string_agg({{ measure }}, {{ delimiter_text }} {{ order_by_clause }})
{%- endmacro %}
select
    i.source_code_type
    , i.source_code
    , sum(i.item_count) as item_count
    , {{ listagg(measure="distinct i.domain", delimiter_text="', '", order_by_clause="order by i.domain" )}} as domains -- noqa
    , {{ listagg(measure="distinct i.data_source", delimiter_text="', '", order_by_clause="order by i.data_source" )}} as data_sources -- noqa
    , cast(null as string) as normalized_code_type
from agg_cte i
group by i.source_code_type, i.source_code

After

{% macro listagg(measure, delimiter_text, order_by_clause) -%}
    string_agg({{ measure }}, {{ delimiter_text }} {{ order_by_clause }})
{%- endmacro %}

select
    i.source_code_type,
    i.source_code,
    sum(i.item_count) as item_count,
    {{ listagg(measure = "distinct i.domain", delimiter_text = "', '", order_by_clause = "order by i.domain") }}
        as domains, -- noqa
    {{
        listagg(measure = "distinct i.data_source", delimiter_text = "', '", order_by_clause = "order by i.data_source")
    }} as data_sources, -- noqa
    cast(null as string) as normalized_code_type
from agg_cte i
group by i.source_code_type, i.source_code

Two guards comments weld across a vanished seam

Before

{%- if is_incremental() %}
    {%- set should_run = true %} -- If full_refresh, always run
{%- else %}
    {%- set should_run = false %}
{%- endif %}

{%- if should_run %} -- Run the query if the shoud_run condition is TRUE

SELECT 1    AS a

{%- endif %}

After

{%- if is_incremental() %}
    {%- set should_run = true %} -- If full_refresh, always run
{%- else %}
    {%- set should_run = false %}
{%- endif %}

{%- if should_run %}
    -- Run the query if the shoud_run condition is TRUE

    SELECT 1 AS a

{%- endif %}