query-comment

query-comment

dbt가 데이터베이스에 대해 실행하는 각 쿼리에 주입할 문자열을 지정하는 설정이에요. 이 주석은 SQL 문을 모델·테스트 같은 특정 dbt 리소스로 귀속시켜요. 문자열 또는 딕셔너리 형태로 지정할 수 있고, 문자열을 반환하는 매크로도 호출할 수 있어요.

출처: 문서

본문

dbt_project.yml:

query-comment: string

query-comment 설정은 딕셔너리 입력도 받아요:

dbt_project.yml:

models:
  my_dbt_project:
    +materialized: table
query-comment:
  comment: string
  append: true | false
  job-label: true | false
  # BigQuery only

정의 (Definition)

dbt가 데이터베이스에 대해 실행하는 각 쿼리에 주입할 문자열이에요. 이 주석은 SQL 문을 모델, 테스트 같은 특정 dbt 리소스로 귀속시킬 수 있어요.

query-comment 설정은 문자열을 반환하는 매크로도 호출할 수 있어요.

기본값 (Default)

기본적으로 dbt는 실행하는 각 쿼리에 JSON 주석을 자동으로 삽입해요. 이 주석에는 dbt 버전, 프로필·타겟 이름, 쿼리를 생성하는 리소스의 노드 ID 같은 메타데이터가 포함돼요.

  • Snowflake의 경우 주석은 쿼리 끝에 나타나요. 이렇게 해서 처리 중에 주석이 제거되는 것을 막아요.
  • 다른 어댑터의 경우 주석은 쿼리 시작 부분에 나타나요. 예시: /* {"app": "dbt", "dbt_version": "1.10.0rc2", "profile_name": "debug", "target_name": "dev", "node_id": "model.dbt2.my_model"} */ create view analytics.analytics.orders as ( select ... );

딕셔너리 문법 사용 (Using the dictionary syntax)

딕셔너리 문법에는 다음 키가 포함돼요:

  • comment (선택 사항, 자세한 내용은 default 섹션 참고): 쿼리에 주석으로 주입할 문자열.
  • append (선택 사항, 기본값 false): 주석을 쿼리 아래(쿼리 바닥에 추가)에 추가할지 여부. 기본적으로 주석은 쿼리 위에 추가돼요(즉 append: false).
  • job-label (선택 사항, 기본값 false): 쿼리 주석 항목을 실행하는 쿼리의 작업 레이블로 포함할지 여부. BigQuery 전용.

이 문법은 Snowflake처럼 선행 SQL 주석을 제거하는 데이터베이스에서 유용해요.

예시 (Examples)

정적 주석 앞에 추가하기 (Prepend a static comment)

다음 예시는 dbt가 실행하는 SQL 쿼리의 헤더에 /* executed by dbt */라는 주석을 주입해요.

dbt_project.yml:

query-comment: "executed by dbt"

예시 출력:

/* executed by dbt */
select ...

쿼리 주석 비활성화 (Disable query comments)

dbt_project.yml:

query-comment:

또는:

dbt_project.yml:

query-comment: null

동적 주석 앞에 추가하기 (Prepend a dynamic comment)

다음 예시는 활성 dbt 타겟에 지정된 사용자에 따라 달라지는 주석을 주입해요.

dbt_project.yml:

query-comment: "run by {{ target.user }} in dbt"

예시 출력:

/* run by drew in dbt */
select ...

기본 주석 뒤에 추가하기 (Append the default comment)

다음 예시는 딕셔너리 문법으로 기본 주석을 앞에 추가하는 대신 뒤(append)에 추가해요.

주석 기본값을 추가하도록 허용하려면 comment: 필드를 생략한다는 점을 참고하세요.

dbt_project.yml:

query-comment:
  append: True

예시 출력:

select ...
/* {"app": "dbt", "dbt_version": "1.6.0rc2", "profile_name": "debug", "target_name": "dev", "node_id": "model.dbt2.my_model"} */
;

BigQuery: 쿼리 주석 항목을 작업 레이블로 포함

query-comment.job-label이 true로 설정되면 dbt는 쿼리 주석 항목이(딕셔너리라면) 또는 주석 문자열을 실행하는 쿼리의 작업 레이블(job label)로 포함해요. 이는 BigQuery별 config에 지정된 라벨에 추가로 포함돼요.

dbt_project.yml:

query-comment:
  job-label: True

사용자 정의 주석 뒤에 추가하기 (Append a custom comment)

다음 예시는 활성 dbt 타겟에 지정된 사용자에 따라 달라지는 주석을 앞이 아닌 뒤(append)에 추가해요.

dbt_project.yml:

query-comment:
  comment: "run by {{ target.user }} in dbt"
  append: True

예시 출력:

select ...
/* run by drew in dbt */
;

중급: 매크로로 주석 생성하기 (Use a macro to generate a comment)

query-comment 설정은 dbt 프로젝트의 매크로를 참조할 수 있어요. macros 디렉터리에 임의의 이름(이름은 query_comment가 좋은 시작이에요!)의 매크로를 만들면 돼요:

macros/query_comment.sql:

{% macro query_comment() %}
  dbt {{ dbt_version }}: running {{ node.unique_id }} for target {{ target.name }}
{% endmacro %}

그런 다음 dbt_project.yml 파일에서 매크로를 호출해요. YAML 파서가 {를 딕셔너리 시작으로 해석하려 하지 않도록 매크로를 꼭 따옴표로 감싸세요.

dbt_project.yml:

query-comment: "{{ query_comment() }}"

고급: 매크로로 주석 생성하기 (Use a macro to generate a comment)

다음 예시는 dbt 프로젝트의 성능 특성을 이해하기 위해 파싱할 수 있는 JSON 쿼리 주석을 보여줘요.

macros/query_comment.sql:

{% macro query_comment(node) %}
    {%- set comment_dict = {} -%}
    {%- do comment_dict.update(
        app='dbt',
        dbt_version=dbt_version,
        profile_name=target.get('profile_name'),
        target_name=target.get('target_name'),
    ) -%}
    {%- if node is not none -%}
      {%- do comment_dict.update(
        file=node.original_file_path,
        node_id=node.unique_id,
        node_name=node.name,
        resource_type=node.resource_type,
        package_name=node.package_name,
        relation={
            "database": node.database,
            "schema": node.schema,
            "identifier": node.identifier
        }
      ) -%}
    {% else %}
      {%- do comment_dict.update(node_id='internal') -%}
    {%- endif -%}
    {% do return(tojson(comment_dict)) %}
{% endmacro %}

위와 같이 이 매크로를 다음과 같이 호출해요:

dbt_project.yml:

query-comment: "{{ query_comment(node) }}"

컴파일 컨텍스트 (Compilation context)

쿼리 주석을 생성할 때 다음 컨텍스트 변수를 사용할 수 있어요:

Context Variable Description
dbt_version 사용 중인 dbt 버전. 릴리스 버전 관리에 대한 자세한 내용은 Versioning 참고.
env_var env_var 참고
modules modules 참고
run_started_at dbt 호출이 시작된 시점
invocation_id dbt 호출을 위한 고유 ID
fromjson fromjson 참고
tojson tojson 참고
log log 참고
var var 참고
target target 참고
connection_name 커넥션의 내부 이름을 나타내는 문자열. dbt가 생성해요.
node 파싱된 노드 객체의 딕셔너리 표현. node.unique_id, node.database, node.schema 등을 사용해요.

참고: query-comment 매크로의 var() 함수는 CLI의 --vars 인자를 통해 전달된 변수만 접근할 수 있어요. dbt_project.yml의 vars 블록에 정의된 변수는 쿼리 주석을 생성할 때 접근할 수 없어요.

더 알아보기 (Learn more)