Dalam rekayasa analitik, dbt (data build tool) macro menyediakan cara yang kuat untuk menulis logika SQL dinamis yang dapat digunakan kembali melalui blok kode yang dapat dipakai ulang.
Dalam tutorial ini, kita akan membahas dasar-dasar dbt macro, cara membangunnya menggunakan Jinja, praktik terbaik untuk kemudahan pemeliharaan, serta penerapan di dunia nyata, semuanya dengan contoh kode.
Apa Itu dbt Macro?
dbt macro adalah blok kode yang dapat digunakan kembali dan ditulis menggunakan bahasa templating Jinja di dalam dbt, yang memungkinkan Anda menghasilkan SQL secara dinamis. Macro membantu mengurangi pengulangan dan memusatkan logika transformasi.
Macro bekerja seperti fungsi dalam bahasa pemrograman tradisional.
Sebagai contoh, jika Anda perlu menghitung metrik tertentu di banyak model, sebuah macro dapat mengenkapsulasi perhitungannya, sehingga lebih mudah dipelihara dan diperbarui.
Macro juga dapat disimpan dalam paket, seperti dbt-utils.
Mengapa Menggunakan dbt Macro?
Macro menghadirkan beberapa keuntungan utama:
Mengurangi redundansi: Anda dapat menulis satu blok logika dan menggunakannya kembali di mana pun.
Konsistensi: Menerapkan logika transformasi yang sama di berbagai model tanpa duplikasi manual.
Fleksibilitas: Macro mendukung parameter, sehingga dapat beradaptasi dengan berbagai input.
Berbagi lintas proyek: Macro yang dirancang dengan baik dapat dibagikan sebagai paket.
Keuntungan ini menghasilkan basis kode yang lebih bersih, mudah dipelihara, dan skalabel.
Konsep Dasar dbt Macro
Untuk membantu Anda memahami cara kerja macro di dbt, mari lihat beberapa konsep kunci.
1. Dapat digunakan kembali
Macro memungkinkan Anda mendefinisikan satu potong logika SQL dan menggunakannya kembali di berbagai model, pengujian, atau bahkan macro lain.
2. Mesin templating Jinja
Integrasi Jinja dengan dbt memungkinkan penyisipan variabel, penerapan kondisi, dan perulangan atas daftar, semuanya sebelum SQL Anda mencapai database. dbt mengompilasi template ini menjadi SQL mentah, sehingga macro tidak bergantung pada jenis database.
3. Pengenalan teknik pemrograman
Macro dapat mengubah SQL menjadi kerangka yang dapat diprogram. Macro memungkinkan logika, loop, dan kondisi—hal umum yang tidak dapat ditangani SQL standar sefleksibel itu.
Seperti fungsi, macro di dbt dapat menerima argumen (parameter) dan dapat dipanggil dengan input berbeda untuk menghasilkan output berbeda. Macro membantu menyederhanakan transformasi kompleks dengan memecahnya menjadi unit yang lebih kecil dan dapat digunakan kembali.
Membangun Macro dengan Jinja
Selanjutnya, mari kita lihat bagaimana kita dapat membangun beberapa macro sendiri.
Jinja adalah mesin templating yang menjalankan dbt macro, memungkinkan Anda memperlakukan SQL sebagai teks dinamis yang dapat diprogram.
Konstruk template dan delimiter
Untuk menggunakan Jinja, Anda perlu menggunakan konstruk template dan delimiter tertentu.
Berikut beberapa konstruk dan delimiter umum:
Ekspresi {{ }}: Menyisipkan ekspresi.
Pernyataan {% %}: Menjalankan pernyataan.
Komentar {# #}: Menambahkan komentar yang ingin Anda abaikan oleh dbt.
Dalam macro, {{ ... }} digunakan untuk ekspresi yang harus menghasilkan nilai (misalnya, nama kolom atau perhitungan), sedangkan {% ... %} digunakan untuk alur kontrol (loop, pernyataan if/else, definisi macro). Komentar Jinja menggunakan {# ... #} dan dihapus sepenuhnya saat kompilasi.
Berikut contoh sintaks untuk pernyataan yang digunakan dalam macro:
Kita akan menggunakan Python untuk menghasilkan dataset orders kecil untuk dimuat ke Postgres (atau gudang pilihan Anda).
import pandas as pd
import random
from datetime import datetime, timedelta
from sqlalchemy import create_engine
# Create sample orders dataframe
random.seed(42)
num_rows =20
start_date = datetime(2025,1,1)
data =[]for i inrange(1, num_rows +1):
order_date = start_date + timedelta(days=random.randint(0,30))
ship_date = order_date + timedelta(days=random.randint(1,10))
data.append({'order_id': i,'customer_id': random.randint(100,105),'order_date': order_date.date(),'ship_date': ship_date.date(),'status': random.choice(['pending','shipped','delivered']),'revenue':round(random.uniform(50,500),2),'cost':round(random.uniform(20,400),2)})
df = pd.DataFrame(data)# Load into Postgres
engine = create_engine('postgresql://user:password@localhost:5432/dbt_demo')
df.to_sql('orders', engine, if_exists='replace', index=False)Didukung oleh
Catatan: Perbarui string koneksi untuk database Anda.
4. Buat Sumber di dbt
Tambahkan berikut ini ke models/src_orders.yml:
version: 2
sources:
- name: public
schema: public
tables:
- name: ordersDidukung oleh
5. Uji Koneksi dan Sumber
dbt debug
dbt run-operation list_relations --args'{"schema_name": "public"}'Didukung oleh
Sekarang Anda siap mulai menulis macro yang beroperasi pada dataset ini.
Cara Menulis dan Menggunakan dbt Macro
Sekarang, mari kita coba menulis beberapa macro kita sendiri.
Mendefinisikan macro
Tempatkan definisi macro dalam file .sql di bawah direktori macros/.
Saat menamai macro, pastikan memberi nama deskriptif yang mencerminkan tujuannya, dan gunakan parameter agar fleksibel. Menambahkan komentar docstring singkat di bagian atas membantu rekan tim memahami maksudnya.
Anda memanggil macro di dalam model dengan {{ macro_name(arg1, arg2) }}. Macro dapat digunakan di klausa SELECT, filter WHERE, atau bahkan seluruh blok CTE, sehingga Anda dapat menyisipkan pola SQL yang dapat digunakan kembali di mana saja.
Berikut contoh:
-- models/my_model.sqlSELECT
order_id,
{{ cents_to_dollars('amount_in_cents') }} AS amount_in_dollars,
{{ cents_to_dollars('tax_in_cents',precision=4) }} AS tax_in_dollars
FROM {{ ref('raw_orders') }}Didukung oleh
Memanggil macro dari CLI
Untuk tugas operasional di luar build model, gunakan format/sintaks berikut:
dbt run-operation macro_name --args'{"param": "value"}'Didukung oleh
Ini memungkinkan Anda menjalankan SQL utilitas seperti pembuatan skema atau pembersihan data tanpa membangun model.
Berikut contoh perintahnya:
dbt run-operation greet --args'{"name": "Austin"}'Didukung oleh
Menggunakan macro dari paket
Macro juga dapat berasal dari paket di dbt, seperti dbt-utils.
Saat Anda memasang paket melalui packages.yml, macro-nya langsung tersedia. Untuk ini, Anda perlu menjalankan dbt deps.
Anda kemudian dapat memanggil macro yang baru ditambahkan dengan format: package_name.macro_name.
Organisasi file macro
Untuk organisasi yang lebih baik, urutkan dan pisahkan macro berdasarkan fungsionalitas untuk meningkatkan kemudahan pemeliharaan.
Cobalah mengelompokkan macro terkait ke dalam file terpisah (mis., date_utils.sql, string_utils.sql) demi kemudahan pemeliharaan. Ini memudahkan menemukan dan memperbarui logika seiring waktu.
Contoh dbt Macro dalam Praktik
Berikut beberapa contoh macro dalam kasus penggunaan yang lebih praktis:
Macro perbandingan tanggal
Misalkan Anda ingin membuat fungsi yang sering digunakan untuk membandingkan tanggal.
Dalam hal ini, Anda dapat menggunakan macro untuk menghitung selisih hari antara dua field tanggal sekaligus menangani perbedaan dialek SQL.
Mulailah dengan membuat file baru di sini: macros/date_utils.sql.
Sekarang, kita akan menggunakan macro days_between yang baru ini dalam sebuah model.
with src as(select*from {{ source('public','orders') }}
)select
order_id,
customer_id,
order_date,
ship_date,
{{ days_between('order_date','ship_date') }} as days_to_ship
from srcDidukung oleh
Kustomisasi macro generate_schema_name
Secara bawaan, dbt menggunakan macro default bernama generate_schema_name. Macro ini digunakan untuk menentukan nama skema tempat sebuah model harus dibangun.
Anda juga dapat menimpa bawaan dbt untuk mengontrol skema yang digunakan per lingkungan.
Anda dapat menyertakan file ini di lokasi: macros/generate_schema_name.sql.
Manfaatnya: Pada dev, model ditempatkan di lingkungan dev_analytics (isolasi). Pada prod, model ditempatkan di analytics. Ini menciptakan deployment yang prediktif dan bebas benturan.
Menjalankan SQL di luar model
Anda juga dapat menjalankan perintah SQL di luar model untuk operasi seperti pembersihan tabel atau pembaruan metadata tanpa membuat model.
Anda dapat menulis macro yang mengeksekusi SQL mentah lalu menjalankannya melalui dbt run-operation.
Ini berguna untuk DDL (drop/create tabel) atau pembaruan metadata yang tidak cocok dimasukkan ke dalam model.
Ini memungkinkan Anda menjalankan macro tanpa menyertakannya di dalam model.
Contoh macro berparameter
Kita juga dapat membuat macro yang sangat berparameter, seperti pada sebuah fungsi.
Dalam contoh ini, kita akan memfilter record berdasarkan status tertentu, yaitu saat nilai disediakan. Ini menggunakan pernyataan if dan do untuk membuat logika.
Sekarang kita terapkan macro ini dalam sebuah model:
with src as(select*from {{ ref('orders') }}
)select*from src
{{ where_orders(status='shipped', min_date='2025-01-05') }}Didukung oleh
Macro ini membangun logika saat sebuah argumen diabaikan; kriteria tersebut diabaikan. Ini menjaga logika opsional tetap rapi.
Praktik Terbaik untuk dbt Macro
Merancang macro yang baik bukan hanya tentang membuat SQL dapat dikompilasi. Macro terbaik itu mudah ditemukan, terdokumentasi dengan baik, prediktif, dapat diuji, dan mudah dihentikan atau diperluas.
Berikut beberapa praktik terbaik yang perlu diikuti:
1. Konvensi penamaan dan desain parameter
Mirip dengan SQL dan bahasa pemrograman, konvensi penamaan perlu diikuti untuk memastikan keterbacaan.
Berikut beberapa tips penamaan:
Jelas dan berorientasi aksi. Lebih suka kata kerja atau maksud yang jelas (mis., generate_select_list, where_orders) daripada nama samar seperti helper.
Jaga nama stabil dan huruf kecil. Gunakan snake_case dan prefiks stabil per domain, mis., date_*, string_*, test_*, admin_*.
2. Strategi dokumentasi
Anda perlu membiasakan diri mendokumentasikan apa yang Anda buat. Dokumentasi harus berada di tempat yang dicari developer.
Misalnya, gabungkan docstring inline + macros.yml (atau schema.yml) dengan deskripsi dan contoh.
Konten dokumentasi dapat mencakup:
Tujuan dan output yang diharapkan (1–2 kalimat)
Tabel parameter dengan nilai default dan nilai yang diizinkan
Contoh singkat pemanggilan di model dan dengan run-operation
Catatan perilaku lintas database
Contoh cuplikan file konfigurasi:
version:2macros:-name: days_between
description:|
Return day difference between two date expressions, normalized across warehouses.arguments:-name: start_col
type: string
description: Column/expression for the start date
-name: end_col
type: string
description: Column/expression for the end date
docs:show:trueDidukung oleh
3. Organisasi kode
Kode Anda juga perlu terorganisasi dengan baik, terutama saat harus mengelola banyak macro dalam direktori Anda.
Cobalah menstrukturkan berdasarkan domain agar mudah digunakan. Berikut beberapa contohnya:
macros/date_utils.sql
macros/string_utils.sql
macros/testing/ (pengujian kustom)
macros/admin/ (DDL, housekeeping)
macros/compat/ (shim gudang data)
4. Jaga macro tetap kecil dan berfokus satu tujuan
Sebuah macro sebaiknya melakukan satu hal dengan baik. Jika macro menjadi terlalu besar atau menangani logika yang tidak terkait, pecah menjadi macro yang lebih kecil. Ini meningkatkan kemampuan penggunaan ulang dan memudahkan pengujian.
5. Uji macro dengan data yang representatif
Gunakan model uji khusus atau lingkungan staging untuk memvalidasi perilaku macro.
Contohnya:
Buat dataset seed kecil yang mencakup kasus tepi.
Tulis model uji yang memanggil macro dengan parameter berbeda.
Gunakan dbt run dan periksa SQL terkompilasi untuk memastikan kebenaran.
Pro tip: Pasangkan macro dengan pengujian kustom dbt test untuk memverifikasi bahwa output memenuhi batasan yang diharapkan.
Kasus Penggunaan Umum dan Aplikasinya
dbt macro sangat serbaguna, dan penerapannya meluas ke banyak alur kerja rekayasa analitik sehari-hari.
Berikut beberapa contoh yang diperluas dan terperinci:
Standarisasi transformasi data: Macro dapat memastikan konvensi penamaan, trimming, penanganan null, dan casting tipe yang sama diterapkan ke banyak model. Misalnya, Anda dapat membuat macro standardize_customer_name untuk membersihkan dan memformat nama secara identik di semua mart.
Mendukung kueri lintas database: Gudang data memiliki perbedaan kecil pada dialek SQL. Macro dapat mengabstraksi perbedaan tersebut—seperti menggunakan DATEDIFF di Snowflake dan DATE_DIFF di BigQuery. Ini membuat model Anda portabel.
Mengotomatiskan pemeriksaan kualitas: Tulis macro yang dapat digunakan kembali untuk menghasilkan pengujian data, seperti memeriksa ID duplikat, kolom kritis bernilai null, atau nilai di luar rentang. Macro ini dapat dipanggil di banyak model uji.
Menyederhanakan pola SQL berulang: CTE umum, field terhitung, atau klausa filter dapat diparameterkan dalam macro. Misalnya, macro untuk membangun klausa WHERE dinamis berdasarkan filter opsional mencegah copy-paste logika kompleks.
Teknik Lanjutan dan Optimasi Kinerja
dbt macro juga dapat digunakan pada penerapan yang lebih lanjut. Mari lihat dua cara umum di bawah ini.
Pola rekursif dan meta-pemrograman
Macro dapat memanggil macro lain, melakukan loop melalui metadata, atau secara dinamis menghasilkan fragmen SQL berdasarkan inspeksi skema.
Ini memungkinkan Anda untuk:
Secara otomatis membuat model staging untuk setiap tabel sumber.
Menghasilkan kueri pivot/unpivot tanpa mengetik setiap kolom secara manual.
Membangun kueri yang peka lingkungan dengan melakukan loop pada variabel konfigurasi.
Strategi optimasi kinerja
Anda juga dapat melakukan optimasi lebih lanjut untuk membantu meningkatkan kinerja:
Minimalkan kompleksitas kueri dengan hanya menyertakan kolom atau join yang diperlukan.
Sesuaikan materialization atau strategi SQL berdasarkan jenis gudang data.
Integrasi dengan Ekosistem dbt
Macro dibuat untuk menjadi bagian dari ekosistem dbt, sehingga semakin kuat saat dipasangkan dengan paket, fitur cloud, dan alat eksternal.
Manajemen paket
Banyak paket komunitas dbt seperti dbt-utils, dbt-date, dan dbt-expectations pada dasarnya adalah kumpulan macro yang sangat dapat digunakan kembali.
Paket-paket ini menghadirkan transformasi, pengujian, dan helper siap pakai tanpa perlu membuat ulang dari nol.
Kompatibilitas dengan dbt Cloud dan alat pengembang
Macro berjalan mulus di lingkungan dbt Cloud, artinya logika SQL dinamis Anda berperilaku sama baiknya ketika dijalankan secara lokal maupun dalam pekerjaan terjadwal di cloud.
Macro juga terintegrasi baik dengan version control, pipeline CI/CD, dan proses code review, memastikan pembaruan macro diuji dan dideploy secara konsisten.
Strategi Implementasi di Dunia Nyata
Beralih dari skrip SQL tradisional ke alur kerja dbt berbasis macro memerlukan perubahan teknis dan adopsi budaya.
Migrasi dan manajemen perubahan
Saat bermigrasi, mulai dengan mengidentifikasi pola SQL berulang di berbagai model. Selanjutnya, refactor ini menjadi macro secara bertahap, sambil memvalidasi bahwa SQL terkompilasi cocok dengan logika lama.
Gunakan feature flag (var()) untuk menyalakan/mematikan logika macro baru selama peluncuran, meminimalkan gangguan. Yang terpenting, pastikan pemangku kepentingan Anda mendapat informasi tentang perubahan untuk menghindari terputusnya kueri hilir.
Tata kelola dan strategi deployment
Untuk tata kelola, mulailah dengan menetapkan konvensi penamaan yang jelas, standar parameter, dan persyaratan dokumentasi untuk semua macro.
Selanjutnya, tinjau perubahan macro dalam pull request seperti halnya pembaruan model, memastikan macro memenuhi standar kinerja dan kompatibilitas.
Di produksi, pantau log pekerjaan untuk kueri yang dihasilkan macro guna memastikan kueri berjalan seperti yang diharapkan. Untuk proyek yang banyak menggunakan macro, siapkan dasbor observabilitas untuk melacak waktu kompilasi dan kinerja kueri berdasarkan jenis macro.
Kesimpulan
dbt macro adalah bagian kunci dari produktivitas dan kemudahan pemeliharaan di tim rekayasa analitik modern. Menggunakan model dbt bersama macro dapat menghasilkan hasil yang lebih baik untuk operasi pembersihan data.
Bagaimana saya dapat mengoptimalkan kinerja dbt macro saya?⌄
Kuncinya adalah memastikan SQL yang dihasilkan macro Anda efisien. Hindari menggunakan loop untuk membangun SQL baris demi baris. Usahakan membiarkan database menangani dengan kueri berbasis set. Selain itu, fokuskan macro dan hindari menambahkan terlalu banyak lapisan logika yang menghasilkan SQL terlalu kompleks. Jika Anda sering mengulang perhitungan yang sama, pertimbangkan untuk melakukan caching di dalam macro atau memindahkannya ke model.
Apa saja jebakan umum saat menggunakan dbt macro?⌄
Kesalahan umum adalah membuat macro terlalu rumit sehingga sulit dipahami atau di-debug. Kesalahan lainnya adalah tidak mempertimbangkan perbedaan antar database. Terkadang Anda mungkin lupa meng-escape variabel, yang dapat menyebabkan error atau menghasilkan SQL yang sulit dibaca oleh rekan tim.
Bagaimana cara men-debug masalah pada dbt macro?⌄
Mulailah dengan melihat SQL terkompilasi di folder target/compiled. File ini menunjukkan tepatnya apa yang dihasilkan macro. Anda juga dapat menambahkan {{ log('message', info=True) }} di dalam macro untuk melihat apa yang terjadi saat runtime. Jika terjadi kegagalan, sederhanakan input dan uji dengan contoh yang lebih kecil menggunakan dbt run-operation hingga Anda menemukan masalahnya.
Apakah dbt macro dapat digunakan dengan alat atau kerangka kerja lain?⌄
Bisa, tetapi hanya melalui dbt itu sendiri. Misalnya, alat seperti Airflow atau Dagster dapat menjalankan perintah dbt yang memanggil macro Anda. Di dalam dbt, macro juga dapat dibagikan melalui paket seperti dbt-utils. Namun, Anda tidak dapat menjalankan dbt macro secara langsung di alat lain kecuali Anda membungkusnya dalam perintah dbt.
Apa praktik terbaik untuk mendokumentasikan dbt macro?⌄
Beberapa praktik terbaik adalah memperlakukan macro seperti fungsi kecil yang akan digunakan orang lain. Pertimbangkan juga untuk menulis deskripsi yang jelas tentang apa yang dilakukan, mencantumkan semua argumen (dengan default bila memungkinkan), dan menampilkan contoh singkat cara penggunaannya. Jika macro berperilaku berbeda di berbagai database, cantumkan pula. Dokumentasi yang baik memudahkan rekan tim mempercayai dan menggunakan ulang karya Anda.
Saya Austin, seorang blogger dan penulis teknologi dengan pengalaman bertahun-tahun sebagai data scientist dan analis data di bidang kesehatan. Memulai perjalanan teknologi dengan latar belakang biologi, kini saya membantu orang lain melakukan transisi yang sama melalui blog teknologi saya. Ketertarikan saya pada teknologi mendorong kontribusi tulisan saya untuk puluhan perusahaan SaaS, menginspirasi orang lain dan membagikan pengalaman saya.
Kuasai pertanyaan wawancara basis data, dari konsep SQL dasar hingga skenario desain sistem tingkat lanjut. Panduan mendalam ini mencakup semua yang Anda perlukan untuk sukses di wawancara DBMS dan meraih peran berikutnya.
Temukan alasan mengapa Anda sebaiknya (tidak) menggunakan spaghetti plot untuk menyampaikan ketidakpastian jalur prediksi badai serta dampaknya terhadap interpretasi.
Bangun pipa data yang andal dan skalabel dengan dbt Fundamentals, sebuah program praktis yang dirancang untuk analis data, insinyur data, dan insinyur analitik.
Dalam rekayasa analitik, dbt (data build tool) macro menyediakan cara yang kuat untuk menulis logika SQL dinamis yang dapat digunakan kembali melalui blok kode yang dapat dipakai ulang.
Dalam tutorial ini, kita akan membahas dasar-dasar dbt macro, cara membangunnya menggunakan Jinja, praktik terbaik untuk kemudahan pemeliharaan, serta penerapan di dunia nyata, semuanya dengan contoh kode.
Apa Itu dbt Macro?
dbt macro adalah blok kode yang dapat digunakan kembali dan ditulis menggunakan bahasa templating Jinja di dalam dbt, yang memungkinkan Anda menghasilkan SQL secara dinamis. Macro membantu mengurangi pengulangan dan memusatkan logika transformasi.
Macro bekerja seperti fungsi dalam bahasa pemrograman tradisional.
Sebagai contoh, jika Anda perlu menghitung metrik tertentu di banyak model, sebuah macro dapat mengenkapsulasi perhitungannya, sehingga lebih mudah dipelihara dan diperbarui.
Macro juga dapat disimpan dalam paket, seperti dbt-utils.
Mengapa Menggunakan dbt Macro?
Macro menghadirkan beberapa keuntungan utama:
Keuntungan ini menghasilkan basis kode yang lebih bersih, mudah dipelihara, dan skalabel.
Konsep Dasar dbt Macro
Untuk membantu Anda memahami cara kerja macro di dbt, mari lihat beberapa konsep kunci.
1. Dapat digunakan kembali
Macro memungkinkan Anda mendefinisikan satu potong logika SQL dan menggunakannya kembali di berbagai model, pengujian, atau bahkan macro lain.
2. Mesin templating Jinja
Integrasi Jinja dengan dbt memungkinkan penyisipan variabel, penerapan kondisi, dan perulangan atas daftar, semuanya sebelum SQL Anda mencapai database. dbt mengompilasi template ini menjadi SQL mentah, sehingga macro tidak bergantung pada jenis database.
3. Pengenalan teknik pemrograman
Macro dapat mengubah SQL menjadi kerangka yang dapat diprogram. Macro memungkinkan logika, loop, dan kondisi—hal umum yang tidak dapat ditangani SQL standar sefleksibel itu.
Seperti fungsi, macro di dbt dapat menerima argumen (parameter) dan dapat dipanggil dengan input berbeda untuk menghasilkan output berbeda. Macro membantu menyederhanakan transformasi kompleks dengan memecahnya menjadi unit yang lebih kecil dan dapat digunakan kembali.
Membangun Macro dengan Jinja
Selanjutnya, mari kita lihat bagaimana kita dapat membangun beberapa macro sendiri.
Jinja adalah mesin templating yang menjalankan dbt macro, memungkinkan Anda memperlakukan SQL sebagai teks dinamis yang dapat diprogram.
Konstruk template dan delimiter
Untuk menggunakan Jinja, Anda perlu menggunakan konstruk template dan delimiter tertentu.
Berikut beberapa konstruk dan delimiter umum:
{{ }}: Menyisipkan ekspresi.{% %}: Menjalankan pernyataan.{# #}: Menambahkan komentar yang ingin Anda abaikan oleh dbt.Dalam macro,
{{ ... }}digunakan untuk ekspresi yang harus menghasilkan nilai (misalnya, nama kolom atau perhitungan), sedangkan{% ... %}digunakan untuk alur kontrol (loop, pernyataan if/else, definisi macro). Komentar Jinja menggunakan{# ... #}dan dihapus sepenuhnya saat kompilasi.Berikut contoh sintaks untuk pernyataan yang digunakan dalam macro:
Berikut contoh cara menggunakan pernyataan untuk membuat sebuah macro:
Untuk menjalankan macro, gunakan ini:
Manajemen variabel
Anda dapat mengoper variabel ke dalam macro atau mendefinisikannya di dalam. Filter seperti
upperataulowerdapat mengubah nilai teks.Berikut implementasi fungsi
upperuntuk mengubah semua nilai teks menjadi huruf besar.Untuk menerapkannya, Anda harus memanggil/merujuk macro yang baru dibuat di model dbt Anda.
Berikut contoh kodenya:
Struktur kontrol
Selanjutnya, mirip dengan bahasa pemrograman, dbt macro dapat menyediakan hal berikut:
{% if %}/{% endif %}):{% for %}/{% endfor %})Struktur ini memungkinkan Anda membangun klausa SQL secara dinamis atau menghasilkan banyak ekspresi berdasarkan input.
Ini memudahkan macro menangani tugas pembuatan SQL yang kompleks.
Penanganan parameter dan manajemen error
Macro dapat memvalidasi input dan menimbulkan error saat kompilasi untuk mencegah masalah saat runtime.
Parameter didefinisikan di dalam deklarasi macro menggunakan tanda kurung
(), mirip definisi fungsi dalam bahasa pemrograman.Berikut contoh cara memasukkan 2 parameter:
Seperti yang terlihat, pada baris pertama, kita menyertakan
param1danparam2.Untuk memanggil macro di model dbt, Anda harus menggunakan kurung kurawal ganda {{ }}. Parameter diteruskan sebagai argumen di dalam tanda kurung.
Dalam kasus ini, kita menentukan
column_adancolumn_bsebagai parameter.Panduan Penyiapan untuk Bekerja dengan dbt Macro
Sebelum mulai membangun dan menggunakan macro, mari siapkan lingkungan kerja agar Anda dapat mengikuti contoh dalam tutorial ini.
Ini akan memastikan Anda telah memasang dbt, memuat dataset contoh, dan memiliki struktur folder yang tepat untuk membuat macro.
1. Pasang dbt Core
Anda perlu memasang dbt Core secara lokal. Jika Anda menggunakan Postgres dalam tutorial ini, pasang dengan perintah berikut:
Jika proyek Anda menggunakan gudang data, jalankan perintah berikut sesuai kebutuhan:
2. Buat Proyek dbt
Sebelum menjalankan perintah dbt apa pun, kita perlu menyiapkan lingkungan proyek.
Arahkan ke direktori proyek yang Anda inginkan.
Di sinilah Anda akan menyimpan file proyek dbt Anda. Dalam kasus ini, kita akan menyimpan semua file terkait di folder proyek dbt ini.
Untuk menginisialisasi proyek dbt, jalankan:
Buat struktur folder dengan format berikut:
3. Siapkan Dataset Contoh
Kita akan menggunakan Python untuk menghasilkan dataset orders kecil untuk dimuat ke Postgres (atau gudang pilihan Anda).
Catatan: Perbarui string koneksi untuk database Anda.
4. Buat Sumber di dbt
Tambahkan berikut ini ke
models/src_orders.yml:5. Uji Koneksi dan Sumber
Sekarang Anda siap mulai menulis macro yang beroperasi pada dataset ini.
Cara Menulis dan Menggunakan dbt Macro
Sekarang, mari kita coba menulis beberapa macro kita sendiri.
Mendefinisikan macro
Tempatkan definisi macro dalam file .sql di bawah direktori macros/.
Saat menamai macro, pastikan memberi nama deskriptif yang mencerminkan tujuannya, dan gunakan parameter agar fleksibel. Menambahkan komentar docstring singkat di bagian atas membantu rekan tim memahami maksudnya.
Berikut contohnya:
Memanggil macro dalam model
Anda memanggil macro di dalam model dengan {{ macro_name(arg1, arg2) }}. Macro dapat digunakan di klausa SELECT, filter WHERE, atau bahkan seluruh blok CTE, sehingga Anda dapat menyisipkan pola SQL yang dapat digunakan kembali di mana saja.
Berikut contoh:
Memanggil macro dari CLI
Untuk tugas operasional di luar build model, gunakan format/sintaks berikut:
Ini memungkinkan Anda menjalankan SQL utilitas seperti pembuatan skema atau pembersihan data tanpa membangun model.
Berikut contoh perintahnya:
Menggunakan macro dari paket
Macro juga dapat berasal dari paket di dbt, seperti dbt-utils.
Saat Anda memasang paket melalui
packages.yml, macro-nya langsung tersedia. Untuk ini, Anda perlu menjalankandbt deps.Anda kemudian dapat memanggil macro yang baru ditambahkan dengan format:
package_name.macro_name.Organisasi file macro
Untuk organisasi yang lebih baik, urutkan dan pisahkan macro berdasarkan fungsionalitas untuk meningkatkan kemudahan pemeliharaan.
Cobalah mengelompokkan macro terkait ke dalam file terpisah (mis., date_utils.sql, string_utils.sql) demi kemudahan pemeliharaan. Ini memudahkan menemukan dan memperbarui logika seiring waktu.
Contoh dbt Macro dalam Praktik
Berikut beberapa contoh macro dalam kasus penggunaan yang lebih praktis:
Macro perbandingan tanggal
Misalkan Anda ingin membuat fungsi yang sering digunakan untuk membandingkan tanggal.
Dalam hal ini, Anda dapat menggunakan macro untuk menghitung selisih hari antara dua field tanggal sekaligus menangani perbedaan dialek SQL.
Mulailah dengan membuat file baru di sini:
macros/date_utils.sql.Selanjutnya, gunakan kode berikut:
Sekarang, kita akan menggunakan macro
days_betweenyang baru ini dalam sebuah model.Kustomisasi macro
generate_schema_nameSecara bawaan, dbt menggunakan macro default bernama
generate_schema_name. Macro ini digunakan untuk menentukan nama skema tempat sebuah model harus dibangun.Anda juga dapat menimpa bawaan dbt untuk mengontrol skema yang digunakan per lingkungan.
Anda dapat menyertakan file ini di lokasi:
macros/generate_schema_name.sql.Manfaatnya: Pada
dev, model ditempatkan di lingkungandev_analytics(isolasi). Padaprod, model ditempatkan dianalytics. Ini menciptakan deployment yang prediktif dan bebas benturan.Menjalankan SQL di luar model
Anda juga dapat menjalankan perintah SQL di luar model untuk operasi seperti pembersihan tabel atau pembaruan metadata tanpa membuat model.
Anda dapat menulis macro yang mengeksekusi SQL mentah lalu menjalankannya melalui
dbt run-operation.Ini berguna untuk DDL (drop/create tabel) atau pembaruan metadata yang tidak cocok dimasukkan ke dalam model.
Berikut macro-nya:
Selanjutnya, jalankan operasi ini di terminal:
Ini memungkinkan Anda menjalankan macro tanpa menyertakannya di dalam model.
Contoh macro berparameter
Kita juga dapat membuat macro yang sangat berparameter, seperti pada sebuah fungsi.
Dalam contoh ini, kita akan memfilter record berdasarkan status tertentu, yaitu saat nilai disediakan. Ini menggunakan pernyataan
ifdandountuk membuat logika.Sekarang kita terapkan macro ini dalam sebuah model:
Macro ini membangun logika saat sebuah argumen diabaikan; kriteria tersebut diabaikan. Ini menjaga logika opsional tetap rapi.
Praktik Terbaik untuk dbt Macro
Merancang macro yang baik bukan hanya tentang membuat SQL dapat dikompilasi. Macro terbaik itu mudah ditemukan, terdokumentasi dengan baik, prediktif, dapat diuji, dan mudah dihentikan atau diperluas.
Berikut beberapa praktik terbaik yang perlu diikuti:
1. Konvensi penamaan dan desain parameter
Mirip dengan SQL dan bahasa pemrograman, konvensi penamaan perlu diikuti untuk memastikan keterbacaan.
Berikut beberapa tips penamaan:
generate_select_list,where_orders) daripada nama samar sepertihelper.date_*,string_*,test_*,admin_*.2. Strategi dokumentasi
Anda perlu membiasakan diri mendokumentasikan apa yang Anda buat. Dokumentasi harus berada di tempat yang dicari developer.
Misalnya, gabungkan docstring inline +
macros.yml(atauschema.yml) dengan deskripsi dan contoh.Konten dokumentasi dapat mencakup:
run-operationContoh cuplikan file konfigurasi:
3. Organisasi kode
Kode Anda juga perlu terorganisasi dengan baik, terutama saat harus mengelola banyak macro dalam direktori Anda.
Cobalah menstrukturkan berdasarkan domain agar mudah digunakan. Berikut beberapa contohnya:
macros/date_utils.sqlmacros/string_utils.sqlmacros/testing/(pengujian kustom)macros/admin/(DDL, housekeeping)macros/compat/(shim gudang data)4. Jaga macro tetap kecil dan berfokus satu tujuan
Sebuah macro sebaiknya melakukan satu hal dengan baik. Jika macro menjadi terlalu besar atau menangani logika yang tidak terkait, pecah menjadi macro yang lebih kecil. Ini meningkatkan kemampuan penggunaan ulang dan memudahkan pengujian.
5. Uji macro dengan data yang representatif
Gunakan model uji khusus atau lingkungan staging untuk memvalidasi perilaku macro.
Contohnya:
dbt rundan periksa SQL terkompilasi untuk memastikan kebenaran.Pro tip: Pasangkan macro dengan pengujian kustom
dbt testuntuk memverifikasi bahwa output memenuhi batasan yang diharapkan.Kasus Penggunaan Umum dan Aplikasinya
dbt macro sangat serbaguna, dan penerapannya meluas ke banyak alur kerja rekayasa analitik sehari-hari.
Berikut beberapa contoh yang diperluas dan terperinci:
standardize_customer_nameuntuk membersihkan dan memformat nama secara identik di semua mart.DATEDIFFdi Snowflake danDATE_DIFFdi BigQuery. Ini membuat model Anda portabel.WHEREdinamis berdasarkan filter opsional mencegah copy-paste logika kompleks.Teknik Lanjutan dan Optimasi Kinerja
dbt macro juga dapat digunakan pada penerapan yang lebih lanjut. Mari lihat dua cara umum di bawah ini.
Pola rekursif dan meta-pemrograman
Macro dapat memanggil macro lain, melakukan loop melalui metadata, atau secara dinamis menghasilkan fragmen SQL berdasarkan inspeksi skema.
Ini memungkinkan Anda untuk:
Strategi optimasi kinerja
Anda juga dapat melakukan optimasi lebih lanjut untuk membantu meningkatkan kinerja:
Integrasi dengan Ekosistem dbt
Macro dibuat untuk menjadi bagian dari ekosistem dbt, sehingga semakin kuat saat dipasangkan dengan paket, fitur cloud, dan alat eksternal.
Manajemen paket
Banyak paket komunitas dbt seperti
dbt-utils,dbt-date, dandbt-expectationspada dasarnya adalah kumpulan macro yang sangat dapat digunakan kembali.Paket-paket ini menghadirkan transformasi, pengujian, dan helper siap pakai tanpa perlu membuat ulang dari nol.
Kompatibilitas dengan dbt Cloud dan alat pengembang
Macro berjalan mulus di lingkungan dbt Cloud, artinya logika SQL dinamis Anda berperilaku sama baiknya ketika dijalankan secara lokal maupun dalam pekerjaan terjadwal di cloud.
Macro juga terintegrasi baik dengan version control, pipeline CI/CD, dan proses code review, memastikan pembaruan macro diuji dan dideploy secara konsisten.
Strategi Implementasi di Dunia Nyata
Beralih dari skrip SQL tradisional ke alur kerja dbt berbasis macro memerlukan perubahan teknis dan adopsi budaya.
Migrasi dan manajemen perubahan
Saat bermigrasi, mulai dengan mengidentifikasi pola SQL berulang di berbagai model. Selanjutnya, refactor ini menjadi macro secara bertahap, sambil memvalidasi bahwa SQL terkompilasi cocok dengan logika lama.
Gunakan feature flag (
var()) untuk menyalakan/mematikan logika macro baru selama peluncuran, meminimalkan gangguan. Yang terpenting, pastikan pemangku kepentingan Anda mendapat informasi tentang perubahan untuk menghindari terputusnya kueri hilir.Tata kelola dan strategi deployment
Untuk tata kelola, mulailah dengan menetapkan konvensi penamaan yang jelas, standar parameter, dan persyaratan dokumentasi untuk semua macro.
Selanjutnya, tinjau perubahan macro dalam pull request seperti halnya pembaruan model, memastikan macro memenuhi standar kinerja dan kompatibilitas.
Di produksi, pantau log pekerjaan untuk kueri yang dihasilkan macro guna memastikan kueri berjalan seperti yang diharapkan. Untuk proyek yang banyak menggunakan macro, siapkan dasbor observabilitas untuk melacak waktu kompilasi dan kinerja kueri berdasarkan jenis macro.
Kesimpulan
dbt macro adalah bagian kunci dari produktivitas dan kemudahan pemeliharaan di tim rekayasa analitik modern. Menggunakan model dbt bersama macro dapat menghasilkan hasil yang lebih baik untuk operasi pembersihan data.
Ingin mempelajari lebih lanjut tentang dbt? Introduction to dbt dan dbt Tutorial dari kami mungkin bermanfaat untuk Anda.