sql_header

sql_header

sql_header는 dbt가 모델과 스냅샷을 만들 때 실행하는 create table as / create view as 문 위에 SQL을 주입하는 선택적 설정이에요. 주로 UDF 생성, BigQuery 스크립트 변수 설정, Snowflake 임시 세션 파라미터 설정에 쓰여요.

sql_header는 ref, source 같은 매크로나 {{ this }} 같은 참조를 지원하지 않아요. pre-hook과 달리 Jinja나 매크로를 쓸 수 없다는 점에 주의하세요.

출처: 문서

본문

set_sql_header의 주요 기능은 꽤 제한적이에요. 용도는 다음과 같아요.

  • UDF 생성
  • 스크립트 변수 설정 (BigQuery)
  • 임시 세션 파라미터 설정 (Snowflake)

models/.sql

{{ config(
  sql_header="<sql-statement>"
) }}

select ...

dbt_project.yml

config-version: 2

models:
  <resource-path>:
    +sql_header: <sql-statement>

이 config는 시드(seeds)에는 구현되지 않아요.

snapshots/.sql

{% snapshot snapshot_name %}

{{ config(
  sql_header="<sql-statement>"
) }}

select ...

{% endsnapshot %}

dbt_project.yml

snapshots:
  <resource-path>:
    +sql_header: <sql-statement>

generic 데이터 테스트의 config에 sql_header를 설정하는 건 dbt v1.12부터 가능해요. generic 데이터 테스트에서 properties.yml의 sql_header를 쓰려면 require_sql_header_in_test_configs 플래그를 활성화하세요.

모델 레벨 구성 예시:

models/properties.yml

models:
  - name: orders
    data_tests:
      - unique:
          name: unique_orders_order_id
          arguments:
            column_name: order_id
          config:
            sql_header: "-- SQL_HEADER_TEST_MARKER"

컬럼 레벨 데이터 테스트에서도 sql_header를 쓸 수 있어요.

models/properties.yml

models:
  - name: orders
    columns:
      - name: order_id
        data_tests:
          - not_null:
              name: not_null_orders_order_id
              config:
                sql_header: "-- SQL_HEADER_TEST_MARKER"

Definition

sql_header는 dbt가 모델과 스냅샷을 만들 때 실행하는 create table as / create view as 문 위에 주입할 SQL을 정하는 선택적 설정이에요.

sql_header는 config로 설정하거나, set_sql_header 매크로를 call-ing 해서 설정할 수 있어요(아래 예시).

(dbt v1.12 이상 적용)

properties.yml 파일에서 model/column 레벨 generic 데이터 테스트의 config에도 sql_header를 설정할 수 있어요. 테스트가 실행되기 전에 실행할 SQL(예: 임시 함수 생성, 세션 파라미터 설정, 테스트 쿼리에 필요한 변수 선언)을 정의할 때 써요. dbt는 테스트를 실행하기 전에 이 SQL을 실행해요.

데이터 테스트에 sql_header를 쓰려면 require_sql_header_in_test_configs 플래그를 활성화하세요. 자세한 내용은 Data test configurations를 참고하세요.

pre-hook과의 비교

Pre-hook도 모델 생성 전에 SQL을 실행할 기회를 제공하지만, 앞선 별도의 쿼리로 실행돼요. 반면 sql_header의 SQL은 create table|view as 문과 같은 쿼리에서 실행돼요.

그래서 Snowflake 세션 파라미터와 BigQuery Temporary UDF에 더 유용해요.

Examples

특정 모델에 Snowflake 세션 파라미터 설정하기

config 블록 문법을 사용한 예시예요.

models/my_model.sql

{{ config(
  sql_header="alter session set timezone = 'Australia/Sydney';"
) }}

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

모든 모델에 Snowflake 세션 파라미터 설정하기

dbt_project.yml

config-version: 2

models:
  +sql_header: "alter session set timezone = 'Australia/Sydney';"

BigQuery Temporary UDF 만들기

이 예시는 set_sql_header 매크로를 호출해요. 주입할 SQL이 여러 줄일 때 쓰기 편한 래퍼 매크로로, 이 경우 sql_header config 키를 쓸 필요는 없어요.

models/my_model.sql

-- Supply a SQL header:
{% call set_sql_header(config) %}
  CREATE TEMPORARY FUNCTION yes_no_to_boolean(answer STRING)
  RETURNS BOOLEAN AS (
    CASE
    WHEN LOWER(answer) = 'yes' THEN True
    WHEN LOWER(answer) = 'no' THEN False
    ELSE NULL
    END
  );
{%- endcall %}

-- Supply your model code:

select yes_no_to_boolean(yes_no) from {{ ref('other_model') }}

더 알아보기 (Learn more)