merica-dlh/merica
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
851be0cda70d98a6150239d28e0af5bf1f39a7dd
merica/docs/user_guide.md
T

11 KiB
Raw Blame History

🎨 Panduan Penggunaan Pengguna (User Guide) — MERICA

Navigasi Cepat: 🏠 Pusat Dokumentasi | 🏛️ Arsitektur Platform | 📦 Panduan Deployment | 📘 Integrasi Airflow External

Panduan komprehensif bagi Data Engineer, Analytics Engineer, dan Data Architect dalam menggunakan antarmuka grafis MERICA Canvas untuk merancang, mengonfigurasi, menguji (Shift-Left Testing), dan menyusun task DAG Apache Airflow 3 secara deklaratif.

Note

Fokus Peran MERICA: MERICA dirancang murni sebagai Visual Low-Code DAG Builder untuk mempercepat rancang bangun pipeline data lakehouse modern tanpa menulis boilerplate Python manual. MERICA bukan dashboard monitoring runtime; pemantauan eksekusi, log task, retry, dan alerting tetap didelegasikan sepenuhnya ke antarmuka resmi Apache Airflow 3.

🖥️ 1. Mengakses Antarmuka Web MERICA Canvas

Buka peramban (web browser) modern (Google Chrome, Mozilla Firefox, Microsoft Edge) dan akses URL:

http://<ip-server-merica>:14000
  • Kredensial Default:
    • Username: admin
    • Password: admin

Tampilan Awal: Pipelines Explorer (Anti-Blank Canvas)

Setelah masuk, Anda akan langsung disajikan halaman Pipelines Explorer. MERICA dilengkapi fitur Anti-Blank Canvas dengan 3 pipeline produksi siap pakai:

  1. e2e_modernized_ingestion_flow: Pipeline ingestion modern yang menggabungkan Database CDC Sling, Google Spreadsheet Auto-Cleansing, dan dlt REST API.
  2. e2e_medallion_permits_flow: Pipeline perizinan Medallion (Bronze Parquet \to Silver Iceberg \to Gold dbt Mart).
  3. e2e_orders_master_medallion_flow: Pipeline master order e-commerce dengan deduplikasi DuckDB dan quality gate Great Expectations.

Anda dapat langsung mengklik salah satu pipeline untuk membukanya di Canvas, atau mengklik tombol + New Pipeline di kanan atas untuk membuat pipeline baru dari awal.

🧩 2. Katalog Komponen & Operator Lakehouse

Panel kiri kanvas (Component Catalog) menyediakan pustaka node terstandarisasi untuk arsitektur Medallion Lakehouse:

graph LR
    subgraph SOURCES ["1. Ingestion Sources (Bronze)"]
        N_DB["Database CDC (Sling)"]
        N_GWS["Google Workspace (Drive/Sheet)"]
        N_REST["REST API (dlt Ingestor)"]
    end

    subgraph SINK ["2. Lakehouse Storage (Silver)"]
        N_BRONZE["Bronze S3 Parquet"]
        N_SILVER["Silver Iceberg + DuckDB Dedup"]
    end

    subgraph TRANS ["3. Transformation (Gold)"]
        N_DBT["dbt Medallion Model (Cosmos)"]
        N_GE["Great Expectations Quality Gate"]
    end

    SOURCES --> SINK --> TRANS

A. Database Ingestor (Sling CDC + Introspection & Safe Preview)

Digunakan untuk mengekstraksi data transaksional dari PostgreSQL, MySQL, SQL Server, atau Oracle:

  • Log-Based CDC: Ekstraksi berbasis log transaksi untuk meminimalkan beban CPU pada database produksi.
  • Database Introspection Otomatis: Saat memilih koneksi dan tabel target, MERICA secara otomatis menginspeksi metadata skema tabel dari PostgreSQL.
  • Auto-Detect Primary Key & Watermark: Kolom kunci utama (Primary Key) dan kolom jejak waktu (timestamp watermark) terdeteksi otomatis untuk kebutuhan inkremental.
  • Safe 10-Row Data Preview: Tombol Preview Data menampilkan 10 baris data sampel secara aman (dengan statement timeout terkendali) langsung di panel konfigurasi tanpa mengunci tabel produksi.

B. Google Workspace Ingestor (Drive Folder Explorer & Header Auto-Cleansing)

Digunakan untuk mengonsumsi spreadsheet Google Sheets dari Google Drive organisasi:

  • Drive Folder Explorer: Antarmuka visual untuk menelusuri folder dan memilih berkas Spreadsheet secara interaktif (/api/v1/discovery/gws/folders).
  • Dynamic Tab Resolution: Mendukung pemilihan tab berbasis indeks (sheet_index: 0) atau pencocokan nama regex dinamis.
  • Header Row Suggestion: Menganalisis baris-baris awal spreadsheet dan merekomendasikan baris mana yang merupakan baris nama kolom aktual (Header Row).
  • Auto-Cleansing Engine:
    • Otomatis mengubah nama kolom menjadi format snake_case dan membuang spasi tersembunyi.
    • Mengeliminasi sufiks unit teks pada data numerik (misal: "1.500.000 (Rp)" \to 1500000).
    • Menerapkan pengisian sel yang digabungkan (Forward-Fill merged cells / ffill).

C. REST API Ingestor (dlt Framework)

Digunakan untuk mengambil data dari sensor IoT (seperti sensor udara SPKU) atau REST API pihak ketiga:

  • Declarative Pagination: Mendukung strategi paginasi standar: Page Number, Offset/Limit, dan Cursor/Next-URL Link.
  • Automated Flattening & Unnesting: Respon JSON bertingkat (nested payloads) otomatis diurai (unnested) menjadi skema tabel tabular relasional di Bronze S3 Parquet.
  • Sliding Lookback Window: Mendukung jendela pengambilan mundur (misal now() - 3 hours s/d now()) untuk mencegah data gap akibat keterlambatan transmisi sensor.

D. Silver Lakehouse Sink (Apache Iceberg + DuckDB Deduplication)

  • ACID Iceberg Table: Menulis data ke partisi Silver menggunakan format Apache Iceberg dengan metadata snapshot time-travel.
  • Idempotent Deduplication via DuckDB: Mencegah duplikasi data pada proses incremental reload menggunakan formula SQL terstandarisasi: 
    ROW_NUMBER() OVER (PARTITION BY primary_key ORDER BY updated_at DESC) = 1

E. dbt Medallion Transformator (Astronomer Cosmos + Shift-Left Testing)

Digunakan untuk menyusun transformasi bisnis dari Silver ke Gold Mart:

  • Otomasi Model SQL: Menulis query transformasi bisnis (misal: aggregasi bulanan, join master data) langsung di editor SQL kanvas.
  • Smart DDL Data Type Inference: Engine MERICA secara otomatis menginferensi tipe data kolom target (INTEGER, DECIMAL(18,2), TIMESTAMP, VARCHAR) berdasarkan ekspresi SQL yang ditulis.
  • Shift-Left Quality Testing: Anda dapat menentukan aturan validasi langsung di kanvas:
    • contract: enforced: Menjamin struktur kolom tabel tidak boleh melenceng dari skema yang disepakati.
    • Constraint kolom bawaan: unique, not_null, dan accepted_values: [...].
  • Astronomer Cosmos Granular TaskGroup: Di Airflow 3, model dbt tidak dieksekusi sebagai satu task raksasa buram (black-box), melainkan dipecah menjadi task granular:
    • model_name.run: Menjalankan kompilasi dan pembuatan tabel SQL.
    • model_name.test: Menjalankan pengujian kualitas data segera setelah model selesai (TestBehavior.AFTER_EACH).

F. Great Expectations Quality Gate

Node validasi batasan fisik data (Data Sanity Rules):

  • Menguji batas kewajaran data (misal: konsentrasi PM2.5 sensor harus berada pada rentang 0 \le x \le 500; jika di luar rentang, ditandai atau dikonversi menjadi NULL).
  • Menguji persentase ambang batas nilai kosong (Null Percentage Threshold).

🛠️ 3. Alur Kerja Perancangan Pipeline di Canvas (Langkah-demi-Langkah)

flowchart TD
    S1["1. Tarik Node dari Katalog ke Kanvas\n(Drag & Drop)"] --> S2["2. Hubungkan Output Port ke Input Port\n(Edge Linking)"]
    S2 --> S3["3. Konfigurasi Parameter di Panel Kanan\n(Drawer Configuration)"]
    S3 --> S4["4. Validasi Pra-Kompilasi\n(Shift-Left Pre-Flight Check: #val)"]
    S4 --> S5["5. Deploy Pipeline ke Airflow 3\n(GitOps Hot-Reload dalam 30 Detik)"]

Langkah 1: Drag & Drop Node

Pilih komponen sumber dari panel katalog kiri (misal: Database CDC), lalu tarik (drag) ke kanvas tengah. Tambahkan node pemrosesan (misal: Silver Iceberg Sink) dan node transformasi (dbt Medallion Model).

Langkah 2: Menghubungkan Port (Edge Linking)

Klik titik lingkaran (handle port) output pada node sumber, lalu tarik garis konektor ke titik input pada node tujuan. Hubungan antar-node ini akan diterjemahkan menjadi dependensi upstream/downstream (>>) pada DAG Airflow.

Langkah 3: Konfigurasi Parameter (Drawer Panel)

Klik pada node di kanvas untuk membuka laci konfigurasi di sebelah kanan:

  • Pada Database CDC: Pilih koneksi database, klik nama tabel, amati deteksi otomatis Primary Key, dan klik Preview Data untuk memverifikasi 10 baris sampel.
  • Pada Google Workspace: Jelajahi folder Google Drive, pilih sheet, dan periksa saran baris header.
  • Pada dbt Model: Tulis query SQL, tambahkan aturan contract quality (unique, not_null).

Langkah 4: Validasi Pra-Kompilasi (Shift-Left Pre-Flight Check)

Klik tombol Validate Pipeline di toolbar atas. Backend FastAPI akan memverifikasi:

  • Ketiadaan siklus (cycle detection / validasi DAG acyclic).
  • Kesesuaian tipe data dan parameter wajib pada setiap node.
  • Validitas model dbt dan kesiapan kontrak schema YAML. Jika terdapat kesalahan konfigurasi, pesan perbaikan spesifik akan langsung muncul di kanvas sebelum pipeline sempat di-deploy ke server.

Langkah 5: Simpan & Deploy Pipeline (Zero Downtime GitOps)

Klik tombol Deploy Pipeline:

  1. MERICA mengompilasi desain kanvas ke dalam berkas kontrak deklaratif YAML (configs/<pipeline_id>.yaml) dan model SQL dbt (dbt/models/...).
  2. Berkas disimpan langsung ke repositori pipeline SSOT (merica-pipelines.git atau direktori ter-mount ./pipelines/).
  3. Apache Airflow 3 AIP-66 Git DAG Processor mendeteksi pembaruan dan secara otomatis memuat ulang DAG ke Airflow MetaDB dalam waktu \le 30 detik tanpa perlu restart Airflow.

⚙️ 4. Pemantauan & Eksekusi di Apache Airflow 3

Setelah pipeline di-deploy dari MERICA Canvas:

  1. Akses dashboard resmi Apache Airflow 3 pada URL: 
    http://<ip-server-airflow>:14080
  2. Temukan DAG yang bersangkutan pada daftar DAG (nama DAG sesuai dengan ID yang Anda tentukan di kanvas).
  3. Tampilan Granular Astronomer Cosmos:
    • Buka tampilan Graph View atau Grid View.
    • Anda dapat melihat TaskGroup dbt terbagi rapi menjadi task .run dan task .test.
    • Jika ada uji kontrak kolom yang gagal, task .test akan berwarna merah (Failed), menghentikan pipeline sebelum data rusak masuk ke Gold layer (Data Quality Circuit Breaker).
  4. Klik pada task untuk membaca log eksekusi, melihat waktu eksekusi task, atau memicu eksekusi ulang (Clear / Retry).

🏛️ 5. Integrasi Tata Kelola Data OpenMetadata 2.0

Setiap kali Anda menekan tombol Deploy Pipeline di MERICA Canvas, sistem secara otomatis menyinkronkan aset ke portal OpenMetadata 2.0:

  • Pipeline Entity: Pipeline terdaftar di bawah dlh_airflow_service lengkap dengan deskripsi, jadwal cron, dan daftar task.
  • Schema & Real Column Types: Struktur kolom dari Bronze, Silver, dan Gold terdaftar di katalog data dengan tipe data presisi.
  • Sample Data 5 Baris: Sampel baris aktual dari PostgreSQL tersimpan pada tab Sample Data OpenMetadata.
  • SQL Query Lineage: Query transformasi dbt disematkan pada tab Queries tabel yang bersangkutan.
  • Data Quality Assertions: Seluruh rule Great Expectations terhubung langsung ke tab Data Quality OpenMetadata, menampilkan riwayat persentase kelulusan data dari waktu ke waktu.

🧭 Navigasi Dokumen Terkait

Reference in New Issue View Git Blame Copy Permalink