Variabel konteks

Setiap task yang dijalankan Airflow selalu dibekali metadata. Pada saat eksekusi, Airflow menyuntikkan metadata itu ke dalam task, misalnya tanggal run, batas data interval, dan pengenal run. Topik ini membahas konteks task yang terbentuk dari metadata tersebut, kunci yang paling sering digunakan, serta dua cara membacanya dari dalam kode task. Bagian akhir memuat DAG latihan yang benar-benar dieksekusi melalui CLI.

Konteks task sebagai kamus metadata#

Konteks task adalah kamus metadata yang disuntikkan Airflow ke dalam task pada saat task dieksekusi. Isinya menjelaskan posisi sebuah eksekusi di dalam DAG, misalnya logical date, batas data interval, dan pengenal run. Sebuah dag run, yaitu satu kali eksekusi DAG, memiliki satu konteks yang sama untuk semua task di dalamnya. Nilai konteks tersebut ditentukan Airflow, bukan diisi oleh kode task.

Konteks dapat dibaca dengan dua cara. Cara pertama, Airflow mengisi parameter fungsi task yang namanya cocok dengan kunci konteks, misalnya parameter ds otomatis berisi tanggal run. Cara kedua, fungsi get_current_context() dari airflow.sdk mengembalikan seluruh kamus konteks, sehingga kunci mana pun dapat dibaca seperti membaca kamus Python biasa. Kedua cara membaca sumber yang sama, sehingga pemilihan caranya semata-mata soal gaya penulisan.

Untuk task yang membutuhkan konteks secara utuh, tersedia pola **kwargs, yaitu parameter yang menampung semua argumen bernama (keyword argument) dalam satu kamus. Pola ini cocok untuk fungsi bantu generik yang meneruskan konteks ke fungsi lain. Pada task biasa, parameter yang dinyatakan satu per satu lebih eksplisit. Daftar lengkap kunci konteks untuk Airflow 3 tersedia pada halaman Templates reference di dokumentasi resmi.

Kunci konteks yang sering digunakan#

Dokumentasi resmi mencantumkan daftar lengkap variabel konteks, sedangkan kebutuhan sehari-hari biasanya berhenti pada beberapa kunci yang muncul berulang kali. Tabel berikut merangkum kunci tersebut beserta bentuk nilainya. Nilai aktual bergantung pada run yang sedang berlangsung, misalnya ds selalu mengikuti logical date dari dag run tempat task tersebut berjalan.

Kunci bertanggal seperti ds dan ds_nodash hanya tersedia pada dag run yang memiliki logical date, misalnya DAG berjadwal atau run yang dipicu dengan tanggal tertentu. DAG yang dipicu oleh asset, yaitu data yang diproduksi satu DAG dan dikonsumsi DAG lain, tidak menyediakan kunci-kunci tersebut karena tidak memiliki logical date. Adapun task_instance_key_str menjadi pengenal unik satu task instance, yaitu salinan task pada satu dag run, dalam bentuk string yang mudah dibaca.

Pasangan data_interval_start dan data_interval_end menyatakan rentang data yang diproses oleh run tersebut, sehingga keduanya sering digunakan untuk menyusun path partisi. Isi konteks juga dapat dilihat secara utuh dengan mencetak kamus konteks ke log, misalnya print(konteks) pada task mana pun. Dengan begitu, kunci yang belum dikenal dapat diperiksa langsung saat run berlangsung.

DAG latihan dengan dua cara akses#

DAG berikut berisi dua task yang tidak saling bergantung, dan masing-masing membaca konteks dengan cara berbeda. Task laporan_konteks menyatakan kunci konteks sebagai parameter fungsi, sedangkan task tampilkan_konteks memanggil get_current_context() lalu membaca beberapa kunci dari kamus tersebut satu per satu. Keduanya hanya mencetak hasil pembacaan ke log, sehingga isi konteks pada saat eksekusi dapat dibandingkan dari keluaran run.

from airflow.sdk import dag, task, get_current_context


@dag(
    dag_id="dag_konteks",
    schedule=None,
    description="DAG latihan: membaca variabel konteks dengan dua cara akses.",
)
def dag_konteks():
    @task
    def laporan_konteks(ds=None, ds_nodash=None, run_id=None) -> dict:
        """Membaca konteks lewat parameter yang namanya cocok dengan kunci konteks."""
        ringkasan = {"ds": ds, "ds_nodash": ds_nodash, "run_id": run_id}
        print(f"Konteks via parameter: {ringkasan}")
        return ringkasan

    @task
    def tampilkan_konteks() -> None:
        """Membaca konteks lewat get_current_context lalu menampilkan sebagian isinya."""
        konteks = get_current_context()
        print(f"logical_date: {konteks['logical_date']}")
        print(f"data_interval_start: {konteks['data_interval_start']}")
        print(f"data_interval_end: {konteks['data_interval_end']}")
        print(f"task_instance_key_str: {konteks['task_instance_key_str']}")

    laporan_konteks()
    tampilkan_konteks()


dag_konteks()

Parameter ds, ds_nodash, dan run_id pada laporan_konteks tidak diisi manual, karena Airflow mengisi ketiganya dengan nilai konteks saat task dieksekusi. Pada tampilkan_konteks, pemanggilan get_current_context() mengembalikan kamus yang sama dengan yang disuntikkan ke parameter, sehingga kedua task menampilkan data yang konsisten. Argumen schedule=None membuat DAG tanpa jadwal. DAG semacam ini hanya berjalan ketika dipicu manual, seperti pada eksekusi uji di bagian berikutnya.

Memeriksa struktur DAG dan menyiapkan lingkungan#

Langkah pertama adalah memastikan berkas DAG dapat diparse tanpa keluaran apa pun. Pesan error akan tampil apabila terdapat sintaks atau impor yang keliru, sedangkan berkas yang valid selesai tanpa mencetak apa pun. Strukturnya kemudian diperiksa dengan memuat modul DAG melalui Python untuk mencetak dag_id beserta seluruh task_id dalam urutan alfabetis.

# uji bahwa berkas DAG dapat diparse tanpa keluaran apa pun
python3 dag_konteks.py

# muat modul DAG lalu cetak dag_id dan seluruh task_id
python3 -c "import dag_konteks; d = dag_konteks.dag_konteks(); print(d.dag_id); print(sorted(t.task_id for t in d.tasks))"

dag_konteks
['laporan_konteks', 'tampilkan_konteks']

Keluaran menegaskan bahwa dag_id sesuai dengan argumen decorator dan dua task sesuai dengan nama fungsinya. Selanjutnya lingkungan latihan disiapkan. CLI Airflow membaca lokasi kerja dari variabel lingkungan AIRFLOW_HOME, yaitu folder yang memuat konfigurasi, basis data metadata, dan folder dags. Latihan pada topik ini menggunakan folder terpisah di /tmp/ra-variabel-konteks agar tidak bercampur dengan instalasi lain, sedangkan contoh DAG bawaan dimatikan supaya daftar DAG benar-benar kosong.

# lingkungan latihan terpisah agar tidak bercampur dengan instalasi lain
export AIRFLOW_HOME=/tmp/ra-variabel-konteks
# contoh DAG bawaan dimatikan supaya daftar DAG benar-benar kosong
export AIRFLOW__CORE__LOAD_EXAMPLES=False

# salin DAG ke folder dags yang dibaca CLI
mkdir -p "$AIRFLOW_HOME/dags"
cp dag_konteks.py "$AIRFLOW_HOME/dags/"

Berkas DAG disalin ke folder dags karena CLI membaca DAG dari folder tersebut, bukan dari direktori kerja. Dengan langkah ini, seluruh prasyarat eksekusi sudah siap, yaitu berkas yang valid, struktur yang terverifikasi, dan lingkungan yang terisolasi.

Menjalankan DAG dan membaca isi konteksnya#

Perintah dags test menjalankan satu dag run secara lokal tanpa memerlukan scheduler maupun worker terpisah. Sebelum perintah itu dipanggil, skema basis data metadata disiapkan terlebih dahulu melalui db migrate, dan log migrasinya tidak ditampilkan karena hanya berisi stempel waktu. Tanggal yang diberikan pada argumen perintah menjadi logical date dari dag run yang dihasilkan.

# siapkan skema basis data metadata
# log migrasi berisi stempel waktu, sehingga tidak ditampilkan
airflow db migrate > /dev/null 2>&1

# jalankan seluruh task DAG sekali secara lokal dengan logical date tetap
# log panjang dan bertanda waktu, sehingga diarahkan ke berkas
airflow dags test dag_konteks 2026-11-04 > "$AIRFLOW_HOME/dags-test.log" 2>&1

Keluaran perintah ini panjang dan bertanda waktu, sehingga diarahkan ke berkas. Pada bagian akhir log, kedua task berstatus success dan dag run ditutup dengan status yang sama. Status tersebut sekaligus menegaskan bahwa kedua cara akses konteks berjalan tanpa hambatan, dan buktinya diambil dari berkas log.

# ambil bukti status dan gabungan kunci task dari berkas log
export AIRFLOW_HOME=/tmp/ra-variabel-konteks
grep -c "new_state=success" "$AIRFLOW_HOME/dags-test.log"
grep -o "dag_konteks__tampilkan_konteks__20261104" "$AIRFLOW_HOME/dags-test.log"

2
dag_konteks__tampilkan_konteks__20261104

Isi konteksnya terbaca dari log masing-masing task. Task laporan_konteks mencetak kamus yang berisi ds bernilai 2026-11-04, ds_nodash bernilai 20261104, dan run_id yang diawali manual__ lalu diikuti waktu pemicuan run. Task tampilkan_konteks mencetak logical_date bernilai 2026-11-04 00:00:00+00:00 sesuai tanggal pada argumen CLI. Nilai data_interval_start dan data_interval_end sama dengan logical date karena DAG tanpa jadwal memiliki data interval selebar nol. Terakhir, task_instance_key_str muncul sebagai gabungan dag_id, task_id, dan ds_nodash, dan baris dag_konteks__tampilkan_konteks__20261104 pada keluaran di atas memperlihatkan nilai tersebut untuk task kedua.

Dibandingkan secara berdampingan, kedua cara akses menunjukkan nilai yang sama untuk kunci yang sama. Perbedaannya hanya pada bentuk aksesnya, yaitu kunci konteks yang dinyatakan sebagai parameter fungsi berbanding akses kamus di dalam badan fungsi. Pada DAG nyata pilihannya bebas, tetapi parameter eksplisit membuat task lebih mudah diuji karena dependensinya terbaca langsung dari daftar parameternya.

Ringkasan#

• Konteks task adalah kamus metadata yang disuntikkan Airflow saat task dieksekusi dan berlaku sama untuk semua task pada satu dag run.
• Konteks dibaca melalui parameter fungsi yang namanya cocok dengan kunci konteks, atau seluruhnya melalui get_current_context().
• Kunci seperti ds, ds_nodash, dan task_instance_key_str diturunkan dari logical date, sedangkan run_id menyatakan pengenal unik run, sehingga nilai aktualnya bergantung pada run yang sedang berjalan.
• Kunci execution_date dari versi lama telah digantikan logical_date pada Airflow 3.

Referensi#

• Templates reference — Apache Airflow — Daftar lengkap variabel konteks pada Airflow 3 beserta tipe dan bentuk nilainya.
• TaskFlow Tutorial — Apache Airflow — Akses konteks secara programatik menggunakan get_current_context() dari airflow.sdk.