dbt run-operation 명령어

dbt run-operation 명령어는 매크로를 호출하거나 SQL·Jinja 문자열을 target 데이터베이스에 직접 실행해요. 매크로 기반 작업과 --sql 플래그를 통한 일회성 임시 실행을 지원해요.

출처: 문서

본문

개요

dbt run-operation 명령어는 매크로를 호출하거나 SQL·Jinja 문자열을 target 데이터베이스에 직접 실행하는 데 사용해요. 매크로 기반 작업의 사용법은 operations를 참고하세요.

(dbt v1.12 이상 적용) 매크로를 dbt run-operation으로 호출하면 dbt는 모델 접근·그룹 제어를 강제하지 않아서, ref()로 모든 모델(private·protected 포함)을 참조할 수 있어요. 예를 들어 매크로가 private 모델을 참조할 수 있어요:

{% macro example_macro() %}
  {{ ref('my_private_model') }}
{% endmacro %}

그다음 dbt run-operation으로 그 매크로를 실행할 수 있어요:

dbt run-operation example_macro

사용법

$ dbt run-operation [macro] --args '{args}'
$ dbt run-operation --sql '{sql}'

[macro]: 호출할 매크로를 지정해요. dbt는 이 매크로를 제공된 인자로 호출한 다음 종료해요. --sql이 제공되지 않으면 필수예요. --sql과 함께 쓸 수 없어요.
--args ARGS: 매크로에 인자를 제공해요. 이 사전(dictionary)은 선택된 매크로에 정의된 키워드 인자에 매핑돼요. 이 인자는 YAML 문자열이어야 해요. 예: '{my_variable: my_value}'. --sql과 함께 쓸 수 없어요.
--sql SQL: 매크로 정의 없이 SQL 또는 Jinja 문자열을 target 데이터베이스에 직접 실행해요. 매크로 이름이나 --args와 결합할 수 없어요. dbt v1.12+에서 사용 가능해요.

`--sql` 플래그 사용

dbt v1.12부터 --sql 플래그를 사용해 매크로를 정의하지 않고 웨어하우스에 임시(ad hoc) 데이터베이스 문장을 직접 실행할 수 있어요. 이 플래그는 테이블 drop·alter, grant 적용, 데이터 수정(data fix) 같은 일회성 작업에 유용해요. 문장은 전체 Jinja 컴파일 파이프라인을 거치므로 ref(), source(), var(), target 및 다른 모든 컨텍스트 변수에 접근할 수 있어요. SQL에 Jinja가 없으면 dbt는 manifest 컴파일을 완전히 건너뛰어 실행이 더 빨라져요.

예를 들어:

# Drop a table in the warehouse
dbt run-operation --sql "DROP TABLE IF EXISTS my_schema.old_table"

# Use Jinja context variables in the statement
dbt run-operation --sql "GRANT SELECT ON {{ target.schema }}.my_table TO reporter"

dbt는 작업이 실행되면서 터미널에 상태 줄을 출력해요:

1 of 1 START executing inline_query ........... [RUN]
1 of 1 OK executed inline_query ............... [SELECT 1 in 0.05s]

작업은 로그에서 inline_query라는 이름으로 표시돼요. 작업이 실패하면 상태 줄은 OK 대신 ERROR를 보여줘요. --sql 플래그는 매크로 이름이나 --args와 결합할 수 없어요.

매크로 대신 `--sql`을 쓸 때

--sql은 매크로 파일이 필요 없는 빠른 일회성 작업(예: 권한 부여, 테이블 drop, 데이터 수정)에 유용해요. 작업을 여러 환경에서 재사용하거나 팀과 공유해야 한다면 매크로로 작성해서 버전 관리와 테스트가 가능하게 하세요.

커맨드라인 예시

매크로 호출:

# Pass a single argument to a macro
dbt run-operation grant_select --args '{role: reporter}'

# Pass multiple arguments to a macro
dbt run-operation clean_stale_models --args '{days: 7, dry_run: True}'

--sql 플래그 사용:

# Execute DDL
dbt run-operation --sql "CREATE TABLE my_schema.my_table (id int)"

# Grant select on a dbt model using ref()
dbt run-operation --sql "GRANT SELECT ON {{ ref('my_model') }} TO reporter"

dbt run-operation 명령어