템플릿 참조

템플릿 참조 (Templates reference)

Airflow 템플릿에는 Variables, Macros, Filters를 사용할 수 있어요. 이 문서는 실행 시 컨텍스트에서 제공되는 모든 변수와, 템플릿에서 쓸 수 있는 매크로·필터를 자세히 정리해 드려요.

출처: 문서

본문

템플릿에는 변수(Variables), 매크로(macros), 필터(filters)를 사용할 수 있어요(Jinja Templating 섹션 참고).

Asset-triggered DAG

Apache Airflow 3의 Asset-triggered DAG은 제공하는 템플릿 컨텍스트가 시간 기반 DAG과 달라요.

Asset-triggered DAG은 logical date가 없으므로 logical_date, ds, ds_nodash 같은 시간 기반 컨텍스트 변수나 그것에서 파생된 값을 제공하지 않아요.

Asset-triggered DAG의 경우, 트리거한 run 관련 정보는 dag_run을 통해 접근할 수 있어요. 예를 들어 dag_run.run_id로 asset 이벤트에 의해 트리거된 DAG run을 고유하게 식별할 수 있어요.

버전 3.0.0에 추가됨.

이 페이지에 나열된 변수들은 Airflow의 실행 시 컨텍스트(execution-time context)를 통해 제공돼요.

Task SDK를 사용할 때 같은 실행 시 컨텍스트는 airflow.sdk.Context 객체를 통해 프로그래밍 방식으로도 사용할 수 있어요.

다음 항목들은 Airflow와 함께 기본으로 제공돼요. 추가 커스텀 매크로는 플러그인을 통해 전역적으로, 또는 DAG.user_defined_macros 인자를 통해 DAG 수준에서 추가할 수 있어요.

Variables

Airflow 엔진은 모든 템플릿에서 접근 가능한 몇 가지 변수를 기본으로 전달해요.

Variable Type Description
{{ data_interval_start }} pendulum.DateTime 데이터 구간의 시작. 버전 2.2에 추가.
{{ data_interval_end }} pendulum.DateTime 데이터 구간의 끝. 버전 2.2에 추가.
{{ logical_date }} pendulum.DateTime 현재 DAG run을 논리적으로 식별하는 날짜-시간. 이 값은 의미를 담고 있지 않고 단순히 식별용 값이에요. 타임스탬프 기반으로 데이터베이스에서 행 조각을 가져오는 것처럼 실제 의미를 가진 값이 필요하면 data_interval_start와 data_interval_end를 사용하세요.
{{ exception }} None str
{{ prev_data_interval_start_success }} pendulum.DateTime None
{{ prev_data_interval_end_success }} pendulum.DateTime None
{{ prev_start_date_success }} pendulum.DateTime None
{{ prev_end_date_success }} pendulum.DateTime None
{{ inlets }} list Task에 선언된 inlet 목록.
{{ inlet_events }} dict[str, …] inlet asset의 과거 이벤트 접근. Assets 참고. 버전 2.10에 추가.
{{ outlets }} list Task에 선언된 outlet 목록.
{{ outlet_events }} dict[str, …] 현재 Task가 방출할 asset 이벤트에 정보를 붙이는 접근자. Assets 참고. 버전 2.10에 추가.
{{ dag }} DAG 현재 실행 중인 DAG. DAG에 대한 자세한 내용은 Dags에서 읽을 수 있어요.
{{ task }} BaseOperator 현재 실행 중인 BaseOperator. Task에 대한 자세한 내용은 Operators에서 읽을 수 있어요.
{{ task_reschedule_count }} int 현재 Task가 몇 번 재스케줄되었는지. mode="reschedule" sensor에 관련됨.
{{ macros }} macros 패키지에 대한 참조. 아래 Macros 참고.
{{ task_instance }} TaskInstance 현재 실행 중인 TaskInstance.
{{ ti }} TaskInstance {{ task_instance }}와 동일.
{{ params }} dict[str, Any] 사용자 정의 params. airflow.cfg에서 dag_run_conf_overrides_params가 활성화되어 있으면 trigger_dag -c로 전달된 매핑에 의해 재정의될 수 있음.
{{ partition_key }} str None
{{ partition_date }} datetime None
{{ var.value }} Airflow variables. 아래 템플릿의 Airflow Variables 참고.
{{ var.json }} Airflow variables. 아래 템플릿의 Airflow Variables 참고.
{{ conn }} Airflow connections. 아래 템플릿의 Airflow Connections 참고.
{{ task_instance_key_str }} str Task 인스턴스에 대한 사람이 읽을 수 있는 키. 시간 기반 DAG의 경우 형식은 {dag_id}__{task_id}__{ds_nodash}. asset-triggered DAG의 경우 DAG run 식별자를 대신 사용: {dag_id}__{task_id}__{dag_run.run_id}.
{{ run_id }} str 현재 실행 중인 DagRun의 run ID.
{{ dag_run }} DagRun 현재 실행 중인 DagRun.
{{ test_mode }} bool Task 인스턴스가 airflow test CLI로 실행되었는지 여부.
{{ map_index_template }} None str
{{ expanded_ti_count }} int None
{{ triggering_asset_events }} dict[str, list[AssetEvent]] Asset 스케줄 DAG에 있다면, Asset URI에서 트리거하는 AssetEvent 목록으로의 맵 (빈도가 다른 여러 Asset이 있으면 하나 이상일 수 있음). 더 읽어보기: Assets. 버전 2.4에 추가.

다음 변수들은 DagRun에 logical_date가 있을 때만 사용할 수 있어요:

Variable Type Description
{{ ds }} str DAG run의 logical date를 YYYY-MM-DD로. {{ logical_date | ds }}와 동일.
{{ ds_nodash }} str {{ logical_date | ds_nodash }}와 동일.
{{ ts }} str {{ logical_date | ts }}와 동일. 예: 2018-01-01T00:00:00+00:00.
{{ ts_nodash_with_tz }} str {{ logical_date | ts_nodash_with_tz }}와 동일. 예: 20180101T000000+0000.
{{ ts_nodash }} str {{ logical_date | ts_nodash }}와 동일. 예: 20180101T000000.

Note

DAG run의 logical date와 그에서 파생된 ds, ts 같은 값은 DAG에서 고유한 것으로 간주해서는 안 돼요. 대신 run_id를 사용하세요.

TaskFlow Task에서 Airflow 컨텍스트 변수 접근하기

@task 데코레이터가 붙은 Task는 인자로 전달된 jinja 템플릿 렌더링을 지원하지 않지만, 위에 나열된 모든 변수는 Task에서 직접 접근할 수 있어요. 다음 코드 블록은 Task에서 task_instance 객체에 접근하는 예시예요:

from airflow.sdk import TaskInstance
from airflow.sdk.types import DagRunProtocol


@task
def print_ti_info(task_instance: TaskInstance, dag_run: DagRunProtocol):
    print(f"Run ID: {task_instance.run_id}")  # Run ID: scheduled__2023-08-09T00:00:00+00:00
    print(f"Task start date: {task_instance.start_date}")  # 2023-08-10 00:00:01+00:00
    print(f"Dag Run logical date: {dag_run.logical_date}")  # 2023-08-09 00:00:00+00:00

간단한 점(dot) 표기법으로 객체의 속성과 메서드에 접근할 수 있다는 점을 기억하세요. 가능한 것들의 예시: {{ task.owner }}, {{ task.task_id }}, {{ ti.hostname }}, … 객체의 속성과 메서드에 대한 자세한 내용은 모델 문서를 참고하세요.

템플릿의 Airflow Variables

var 템플릿 변수로 Airflow Variables에 접근할 수 있어요. 평문 또는 JSON으로 접근할 수 있어요. JSON을 사용하면 {{ var.json.my_dict_var.key1 }}처럼 딕셔너리 같은 중첩 구조도 탐색할 수 있어요.

필요하다면 문자열로 변수를 가져올 수도 있어요 (예: 변수 키에 점이 포함된 경우) {{ var.value.get('my.var', 'fallback') }} 또는 {{ var.json.get('my.dict.var', {'key1': 'val1'}) }}처럼요. 변수가 없을 경우를 대비해 기본값을 제공할 수 있어요.

템플릿의 Airflow Connections

마찬가지로 Airflow Connections 데이터도 conn 템플릿 변수로 접근할 수 있어요. 예를 들어 템플릿에서 {{ conn.my_conn_id.login }}, {{ conn.my_conn_id.password }} 같은 표현식을 사용할 수 있어요.

var와 마찬가지로 문자열로 connection을 가져올 수 있고(예: {{ conn.get('my_conn_id_'+index).host }}) 기본값을 제공할 수도 있어요(예: {{ conn.get('my_conn_id', {"host": "host1", "login": "user1"}).host }}).

추가로 connection의 extras 필드는 extra_dejson 필드로 Python Dictionary처럼 가져올 수 있어요. 예를 들어 conn.my_aws_conn_id.extra_dejson.region_name은 extras에서 region_name을 가져와요. 이 방식으로 extras의 기본값도 제공할 수 있어요(예: {{ conn.my_aws_conn_id.extra_dejson.get('region_name', 'Europe (Frankfurt)') }}).

Filters

Airflow는 값을 포맷팅하는 데 사용할 수 있는 몇 가지 Jinja 필터를 정의해요.

예를 들어 {{ logical_date | ds }}를 사용하면 logical_date가 YYYY-MM-DD 형식으로 출력돼요.

Filter Operates on Description
ds datetime datetime을 YYYY-MM-DD로 포맷
ds_nodash datetime datetime을 YYYYMMDD로 포맷
ts datetime .isoformat()과 동일, 예: 2018-01-01T00:00:00+00:00
ts_nodash datetime -, : 또는 TimeZone 정보 없이 ts 필터와 동일. 예: 20180101T000000
ts_nodash_with_tz datetime -나 : 없이 ts 필터로. 예: 20180101T000000+0000

Macros

Macros는 템플릿에 객체를 노출하는 방법이며 템플릿의 macros 네임스페이스 아래에 있어요.

몇 가지 자주 사용되는 라이브러리와 메서드가 제공돼요.

Variable Description
macros.datetime 표준 라이브러리의 datetime.datetime. 참고: utcnow()는 Python 3.12+에서 폐지됨; 대신 now(macros.dateutil.tz.UTC) 사용.
macros.timedelta 표준 라이브러리의 datetime.timedelta
macros.dateutil dateutil 패키지에 대한 참조
macros.time 표준 라이브러리의 time
macros.uuid 표준 라이브러리의 uuid
macros.random 표준 라이브러리의 random.random

Airflow 고유의 매크로도 정의되어 있어요:

airflow.sdk.execution_time.macros.datetime_diff_for_humans(dt, since=None)[source] : datetime 사이의 사람이 읽을 수 있는/근사한 차이를 반환해요.

하나의 datetime만 제공되면 비교 기준은 now가 돼요.

파라미터:
:   - **dt** (*Any*) – 차이를 표시할 datetime
    - **since** (*DateTime* *|* *None*) – 날짜를 표시할 기준 시점. `None`이면 `dt`와 now 사이의 차이.

airflow.sdk.execution_time.macros.ds_add(ds, days)[source] : YYYY-MM-DD에 일수(days)를 더하거나 뺍니다.

파라미터:
:   - **ds** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.14)")) – 더할 기준 날짜를 `YYYY-MM-DD` 형식으로
    - **days** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.14)")) – ds에 더할 일수, 음수도 사용 가능

```
>>> ds_add("2015-01-01", 5)
'2015-01-06'
>>> ds_add("2015-01-06", -5)
'2015-01-01'
```

airflow.sdk.execution_time.macros.ds_format(ds, input_format, output_format)[source] : 주어진 형식으로 datetime 문자열을 출력해요.

파라미터:
:   - **ds** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.14)")) – 날짜가 포함된 입력 문자열.
    - **input_format** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.14)")) – 입력 문자열 형식 (예: '%Y-%m-%d').
    - **output_format** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.14)")) – 출력 문자열 형식 (예: '%Y-%m-%d').

```
>>> ds_format("2015-01-01", "%Y-%m-%d", "%m-%d-%y")
'01-01-15'
>>> ds_format("1/5/2015", "%m/%d/%Y", "%Y-%m-%d")
'2015-01-05'
>>> ds_format("12/07/2024", "%d/%m/%Y", "%A %d %B %Y", "en_US")
'Friday 12 July 2024'
```

airflow.sdk.execution_time.macros.ds_format_locale(ds, input_format, output_format, locale=None)[source] : 주어진 Babel 형식으로 지역화된 datetime 문자열을 출력해요.

파라미터:
:   - **ds** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.14)")) – 날짜가 포함된 입력 문자열.
    - **input_format** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.14)")) – 입력 문자열 형식 (예: '%Y-%m-%d').
    - **output_format** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.14)")) – 출력 문자열 Babel 형식 (예: yyyy-MM-dd).
    - **locale** (*Locale* *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.14)") *|* *None*) – 출력 문자열을 포맷하는 데 사용되는 로캘 (예: 'en_US'). 로캘을 지정하지 않으면 기본 LC_TIME이 사용되고, 그것도 없으면 'en_US'가 사용돼요.

```
>>> ds_format("2015-01-01", "%Y-%m-%d", "MM-dd-yy")
'01-01-15'
>>> ds_format("1/5/2015", "%m/%d/%Y", "yyyy-MM-dd")
'2015-01-05'
>>> ds_format("12/07/2024", "%d/%m/%Y", "EEEE dd MMMM yyyy", "en_US")
'Friday 12 July 2024'
```

버전 2.10.0에 추가됨.

airflow.sdk.execution_time.macros.random() → x in the interval [0, 1).

더 알아보기 (Learn more)