Limitations of sql_header

[dbeatty10]

Contributions

• I have read the contribution docs, and understand what's expected of me.

Link to the page on docs.getdbt.com requiring updates

https://docs.getdbt.com/reference/resource-configs/sql_header

What part(s) of the page would you like to see updated?

We should document a few known limitations of sql_header.

This Stack Overflow post points out that you can't safely use {{ ref() }} or {{ source() }} in the sql_header.

And {{ this }} also doesn't work in a sql_header when using a custom generate_alias_name.

Additional information

Since sql_header is often used by users dbt-bigquery to DECLARE variables, it would be nice to show an example similar to (but not exactly like) this:

{% call set_sql_header(config) %}
DECLARE myDate VARCHAR DEFAULT '2021-01-01';
{% endcall %}

with order_bis as (

    select
        order_id

    from
        order
    where
        customer_date > myDate

)

select * from order_bis