> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/analytics/id/iot-query/schema-overview/transformation-layer/transformation-builder.md).

# Transformation Builder

Buat transformasi IoT Query kustom dengan editor alur kerja visual. Konfigurasikan node SQL, pratinjau hasil, validasi alur kerja, dan jadwalkan eksekusi

{% hint style="info" %}

#### Segera hadir!

Penyusun transformasi saat ini sedang dalam pengembangan. Deskripsi fitur di halaman ini mencerminkan fungsionalitas yang direncanakan. Rincian implementasi dapat berubah sebelum rilis final. Jika Anda tertarik pada akses awal atau memiliki pertanyaan, hubungi <iotquery@navixy.com>.
{% endhint %}

## Apa itu Penyusun transformasi

**Penyusun transformasi** adalah alat visual untuk merancang alur kerja transformasi data tanpa perlu mengembangkan dan memelihara rangkaian pemrosesan data yang kompleks. Anda menyusun logika pemrosesan sebagai graf, di mana setiap langkah diwakili oleh blok terpisah (simpul), dan alat ini mengompilasi graf Anda menjadi SQL yang dapat dieksekusi.

Penyusun transformasi dirancang untuk analis, spesialis BI, dan siapa pun dengan pengetahuan SQL dasar yang ingin mengendalikan logika persiapan data secara mandiri. Alat ini membantu Anda menjawab pertanyaan kunci dalam persiapan data: dari mana data berasal, bagaimana data digabungkan, filter dan transformasi apa yang diterapkan, bagaimana deret waktu diagregasi, dan dalam bentuk apa data harus muncul di [Lapisan transformasi](https://navixy.com/docs/analytics/id/iot-query/schema-overview/transformation-layer.md).

Penyusun transformasi bukan orkestrator ETL penuh atau platform data. Ini adalah perancang alur kerja yang terfokus yang mengompilasi graf simpul Anda menjadi kueri SQL dan fungsi basis data terjadwal. Templat alur kerja siap pakai untuk transformasi umum Navixy tersedia di [Templat](https://navixy.com/docs/analytics/id/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md) halaman.

## Cara kerjanya

Sebuah alur kerja dalam Penyusun transformasi adalah graf berarah dari simpul yang disusun dari sumber data hingga keluaran:

<figure><img src="https://1696125515-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoFNFEIINiGFbhi3Px3dE%2Fuploads%2Fgit-blob-a74268228ff712c9e4192afa5d2ad87fb5f93d50%2FBasic-flow-example.png?alt=media" alt="workflow graph example showing sources, transformations, and output"><figcaption><p align="center"><strong>Sumber data mentah → simpul transformasi → Keluaran</strong></p></figcaption></figure>

Setiap simpul sesuai dengan satu langkah pemrosesan logis. Anda dapat menggabungkan beberapa sumber ke dalam satu simpul transformasi, dan hasil dari satu simpul dapat menjadi masukan bagi beberapa simpul hilir. Graf ini memberi Anda representasi visual yang jelas atas seluruh jalur data dari tabel sumber hingga entitas analitis target.

Penyusun mengompilasi graf Anda menjadi satu kueri SQL menggunakan Ekspresi Tabel Umum (CTE). Setiap simpul menjadi CTE dalam kueri akhir. Pendekatan kompilasi ini berarti Penyusun tidak menulis data langsung ke basis data. Sebaliknya, ia menghasilkan konfigurasi yang menjalankan pemrosesan data sebenarnya berdasarkan jadwal.

{% hint style="warning" %}
Data dalam graf harus mengalir hanya dalam satu arah. Siklus tidak diizinkan. Jika Penyusun mendeteksi siklus, ia mengembalikan galat validasi.
{% endhint %}

### Menghubungkan ke basis data

Sebelum Anda mulai membangun alur kerja, Anda perlu terhubung ke basis data PostgreSQL Anda. Tanpa koneksi aktif, pratinjau data dan penemuan tabel tidak tersedia.

Panel koneksi memungkinkan Anda menentukan [URL koneksi](https://navixy.com/docs/analytics/id/iot-query/connection-setup.md#connection-string-format), menyambungkan atau memutuskan sambungan, dan melihat jumlah tabel yang ditemukan dalam setiap kategori. Penyusun menggunakan dua skema dalam basis data Anda:

* `raw_telematics_data` untuk data telematika dan sensor perangkat
* `raw_business_data` untuk data referensi bisnis (kendaraan, karyawan, geofence, dan entitas serupa)

Setelah terhubung, Penyusun secara otomatis menemukan tabel dan kolom yang tersedia, yang kemudian dapat Anda pilih saat mengonfigurasi simpul sumber data.

<figure><img src="https://1696125515-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoFNFEIINiGFbhi3Px3dE%2Fuploads%2Fgit-blob-d059f27250d15460203d3ffe972d7e4be190f9d9%2FConnection-url.png?alt=media" alt="connection panel showing URL input and discovered table counts"><figcaption></figcaption></figure>

### Simpul Sumber Data

Simpul sumber data menentukan dari mana alur kerja Anda membaca data. Setiap simpul sumber data sesuai dengan satu tabel di lapisan data mentah.

<details>

<summary>Data mentah: Telematika</summary>

Simpul ini memuat data deret waktu dari `raw_telematics_data` skema.

| Parameter               | Deskripsi                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Nama tabel**          | Pilih dari daftar tabel yang ditemukan saat Anda terhubung ke basis data.                                       |
| **Kolom waktu**         | Kolom stempel waktu yang digunakan untuk pengurutan dan filter berbasis waktu. Secara default `device_time`.    |
| **Kolom**               | Daftar kolom tertentu untuk disertakan, atau `*` untuk memilih semua kolom.                                     |
| **Kondisi filter**      | SQL opsional `WHERE` kondisi yang diterapkan langsung pada kueri sumber.                                        |
| **Menit jendela waktu** | Batas waktu opsional (dalam menit) untuk membatasi jendela data dalam SQL. Biarkan kosong jika tidak ada batas. |

Setiap simpul Data mentah: Telematika membaca dari tepat satu tabel. Untuk menggunakan data dari beberapa tabel, tambahkan simpul terpisah untuk setiap tabel.

</details>

<details>

<summary>Data mentah: Bisnis</summary>

Simpul ini memuat data referensi dari `raw_business_data` skema. Tabel umum meliputi `objects`, `kendaraan`, `perangkat`, dan `deskripsi sensor`.

| Parameter       | Deskripsi                                                                   |
| --------------- | --------------------------------------------------------------------------- |
| **Nama tabel**  | Pilih dari daftar tabel bisnis yang ditemukan.                              |
| **Kolom kunci** | Kolom kunci untuk tabel ini (misalnya, `object_id` atau `sensor_id`).       |
| **Kolom**       | Daftar kolom tertentu untuk disertakan, atau `*` untuk memilih semua kolom. |

Data mentah: Node bisnis terutama digunakan sebagai input kedua untuk node SQL Transform, sehingga Anda dapat menggabungkan data referensi dengan deret waktu telematika.

</details>

### Node transformasi

Node transformasi menentukan apa yang terjadi pada data Anda setelah data dimuat dari sumber. Setiap jenis transformasi menangani pola pemrosesan tertentu.

<details>

<summary>Transformasi SQL</summary>

Menggabungkan data dari tepat dua node sumber menggunakan SQL `JOIN` operasi.

| Parameter        | Deskripsi                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Jenis join**   | Jenis join: `INNER`, `LEFT`, `RIGHT`, atau `PENUH` (gabungan luar penuh).                                                                  |
| **Kondisi join** | Kondisi untuk mencocokkan baris antara dua input (misalnya, cocokkan pada `device_id`).                                                    |
| **Pilih kolom**  | Daftar kolom yang akan disertakan dalam output. Mendukung notasi prefiks seperti `source.*` untuk memilih semua kolom dari input tertentu. |

SQL Transform memerlukan tepat dua input. Input dapat berupa kombinasi apa pun dari node Sumber Data atau keluaran dari node transformasi lainnya.

</details>

<details>

<summary>Filter</summary>

Memfilter data berdasarkan rentang waktu dan kondisi kustom. Semua kondisi dijalankan di basis data sebagai bagian dari `WHERE` klausa (penyaringan pushdown).

| Parameter                      | Deskripsi                                                                                                       |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Kolom waktu**                | Kolom timestamp yang digunakan untuk penyaringan berbasis waktu. Secara bawaan `device_time`.                   |
| **Awal / akhir rentang waktu** | Batas awal dan akhir untuk filter waktu.                                                                        |
| **Kondisi dinamis**            | Daftar kondisi SQL yang digabungkan dengan `AND`. Gunakan ini untuk pemfilteran tambahan di luar rentang waktu. |

</details>

<details>

<summary>Penyampelan ulang</summary>

Mengagregasikan data deret waktu ke dalam interval waktu tetap. Ini berguna untuk mengonversi titik data berfrekuensi tinggi menjadi statistik ringkasan selama periode reguler.

| Parameter                | Deskripsi                                                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Kolom waktu**          | Kolom cap waktu yang digunakan untuk pengelompokan interval. Secara bawaan menggunakan `device_time`.                                                          |
| **Interval**             | Interval agregasi: `1 menit`, `5 menit`, `15 menit`, `1 jam`, atau `1 hari`.                                                                                   |
| **Kelompok berdasarkan** | Kolom tambahan untuk pengelompokan berdasarkan (selain interval waktu).                                                                                        |
| **Agregasi**             | Daftar pasangan kolom-metode yang menentukan bagaimana setiap kolom diagregasikan. Metode yang tersedia: `avg`, `sum`, `min`, `max`, `first`, `last`, `count`. |

</details>

<details>

<summary>Aritmetika</summary>

Menambahkan atau mengganti kolom menggunakan ekspresi SQL. Gunakan node ini untuk membuat kolom terhitung berdasarkan data yang sudah ada.

| Parameter    | Deskripsi                                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------------------------- |
| **Ekspresi** | Daftar definisi ekspresi. Setiap entri mencakup kolom sumber opsional, ekspresi SQL, dan alias keluaran yang wajib. |

Sebagai contoh, untuk mengonversi nilai kecepatan, Anda dapat menetapkan kolom sumber ke `speed`, ekspresi menjadi `speed * 1.2`, dan alias menjadi `speed_adjusted`. Alias wajib untuk setiap ekspresi.

</details>

<details>

<summary>SQL kustom</summary>

Menyediakan input SQL bebas bentuk untuk logika kompleks yang tidak dapat diekspresikan oleh jenis node lain. Gunakan ini saat Anda memerlukan kendali penuh atas kueri.

| Parameter      | Deskripsi                                                                   |
| -------------- | --------------------------------------------------------------------------- |
| **SQL kustom** | Sebuah `SELECT` kueri tempat node hulu dapat diakses melalui alias CTE-nya. |

Alias node sumber mengikuti pola `a_<node_id>` (misalnya, `a_node_1`, `a_filter_1`). Pengidentifikasi node disanitasi menjadi pengidentifikasi SQL yang valid, dengan spasi dan karakter khusus diganti dengan garis bawah.

Node SQL kustom menerima satu atau dua input. Kueri Anda dapat mereferensikan CTE yang bersesuaian melalui aliasnya.

</details>

### Konfigurasi output

<details>

<summary>Keluaran</summary>

Node **Keluaran** menentukan bagaimana hasil transformasi Anda harus ditulis ke lapisan Transformasi. Ini menentukan metadata tabel target yang digunakan runtime eksternal untuk menyimpan data yang telah diproses.

| Parameter               | Deskripsi                                                                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Nama tabel**          | Nama tabel target di `processed_custom_data` skema.                                                                                                                            |
| **Kolom waktu**         | Kolom timestamp dalam data keluaran (misalnya, `device_time`).                                                                                                                 |
| **Partisi berdasarkan** | Ekspresi partisi untuk mengatur data yang disimpan (misalnya, `DATE(device_time)`).                                                                                            |
| **Kunci utama**         | Daftar kolom yang secara unik mengidentifikasi setiap baris (misalnya, `[device_id, device_time]`).                                                                            |
| **Mode penulisan**      | Cara data ditulis ke tabel target: `tambahkan` (menambahkan baris baru), `timpa` (mengganti data yang ada), atau `upsert` (memperbarui baris yang ada, menyisipkan yang baru). |

</details>

## Membangun alur kerja

Alur kerja tipikal mengikuti langkah-langkah berikut:

{% stepper %}
{% step %}
**Buka Transformation Builder**

Luncurkan antarmuka Transformation Builder.
{% endstep %}

{% step %}
**Hubungkan ke basis data Anda**

Masukkan URL koneksi PostgreSQL Anda dan buat koneksinya. Builder secara otomatis menemukan tabel dan kolom yang tersedia.
{% endstep %}

{% step %}
**Tambahkan node sumber data**

Tambahkan sebuah [**Data mentah: Telematika**](#raw-data-telematics) node dan pilih tabel dan kolom yang ingin Anda gunakan. Jika Anda memerlukan data referensi (misalnya, detail kendaraan atau deskripsi sensor), tambahkan sebuah [**Data mentah: Bisnis**](#raw-data-business) node juga.
{% endstep %}

{% step %}
**Tambahkan node transformasi**

Sisipkan node transformasi yang diperlukan alur kerja Anda:

* [**Transformasi SQL**](#sql-transform) untuk menggabungkan data
* [**Filter**](#filter) untuk mempersempit hasil
* [**Penyampelan ulang**](#resampling) untuk mengagregasi deret waktu
* [**Aritmetika**](#arithmetic) untuk menambahkan kolom terhitung
* [**SQL kustom**](#custom-sql) untuk logika kompleks.
  {% endstep %}

{% step %}
**Konfigurasikan node Output**

Tambahkan [Keluaran](#output) node dan atur nama tabel target, kolom kunci utama, dan mode penulisan untuk entitas analitis Anda.
{% endstep %}

{% step %}
**Hubungkan node**

Tarik edge di antara node untuk mendefinisikan aliran data. Hubungkan node sumber ke node transformasi, dan node transformasi ke node Output. Aliran data bergerak dari kiri ke kanan, dari sumber ke output.
{% endstep %}

{% step %}
**Tinjau dan perbaiki galat**

Periksa petunjuk validasi untuk setiap masalah konfigurasi. Perbaiki galat pada parameter node atau struktur graf sesuai kebutuhan.
{% endstep %}

{% step %}
**Pratinjau hasil**

Klik **Jalankan** untuk menjalankan pratinjau alur kerja Anda. Builder menyusun graf menjadi SQL dan menjalankannya terhadap basis data Anda, mengembalikan hingga 100 baris agar Anda dapat memverifikasi output.

{% hint style="info" %}
**Ekspor**

Anda dapat mengekspor alur kerja yang selesai sebagai file YAML untuk eksekusi saat runtime atau untuk dibagikan kepada rekan kerja. Lihat [referensi YAML alur kerja](https://navixy.com/docs/analytics/id/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md) untuk detail format.
{% endhint %}
{% endstep %}

{% step %}

#### Jadwalkan eksekusi

Klik **Jadwalkan** untuk membuka dialog konfigurasi, tempat Anda dapat menentukan waktu dan frekuensi pasti eksekusi alur kerja. Pada waktu yang ditetapkan, sebuah fungsi di basis data akan memicu alur kerja dan menyimpan hasilnya ke lapisan transformasi.
{% endstep %}
{% endstepper %}

<figure><img src="https://1696125515-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoFNFEIINiGFbhi3Px3dE%2Fuploads%2Fgit-blob-284bc5a571d1f159214d822c840d6be699ccac98%2FComplete-flow-example.png?alt=media" alt="completed workflow graph with all node types connected"><figcaption><p>Contoh lengkap aliran transformasi</p></figcaption></figure>

### Pratinjau hasil

Setelah Anda mengklik **Jalankan** di toolbar, Builder menyusun graf alur kerja Anda menjadi satu kueri SQL dengan CTE dan menjalankannya terhadap basis data PostgreSQL yang tersambung. Hasilnya muncul di panel bawah.

**Jika eksekusi berhasil**, panel menampilkan:

* Tabel hasil yang menampilkan hingga 100 baris data output
* Kueri SQL yang dieksekusi (seluruh kueri CTE yang dihasilkan oleh kompiler)
* Jumlah baris, jumlah kolom, dan waktu eksekusi
* Opsi untuk mengekspor hasil ke CSV

**Saat terjadi galat eksekusi**, panel menampilkan:

* Pesan galat yang menjelaskan apa yang salah
* Kueri SQL yang dieksekusi (jika kompilasi berhasil)
* Rincian galat basis data (jika galat terjadi selama eksekusi kueri)

{% hint style="warning" %}
Pratinjau hasil memerlukan koneksi PostgreSQL yang aktif. Tanpa koneksi, pratinjau mengembalikan hasil kosong tanpa SQL dieksekusi. Pratinjau selalu menggunakan data asli dari basis data Anda, bukan data tiruan.
{% endhint %}

<figure><img src="https://1696125515-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoFNFEIINiGFbhi3Px3dE%2Fuploads%2Fgit-blob-d16d21dd58df9cea2fe996abeb4873df4e438da9%2FExecuted-flow-result.png?alt=media" alt="Results preview panel showing successful execution with result table and SQL"><figcaption><p>Hasil aliran yang dieksekusi</p></figcaption></figure>

## Validasi dan kompilasi

Builder memvalidasi alur kerja Anda pada dua tingkat.

1. **Validasi graf** memeriksa struktur keseluruhan alur kerja Anda. Graf harus berupa graf asiklik berarah (DAG) yang valid, artinya data mengalir dalam satu arah tanpa siklus. Jika Builder mendeteksi siklus, Builder mengembalikan galat dan menyorot simpul yang terdampak.
2. **Validasi simpul** memeriksa konfigurasi setiap simpul secara individual. Builder memverifikasi bahwa kolom yang diperlukan telah diisi, bahwa kolom yang dirujuk ada dalam keluaran simpul hulu, dan bahwa parameter simpul konsisten dengan jenisnya (misalnya, SQL Transform harus memiliki tepat dua masukan).

Selama kompilasi, Builder mengonversi graf Anda menjadi satu kueri SQL. Setiap simpul menjadi CTE dengan alias `a_<node_id>`. Simpul diatur dalam urutan topologis sehingga setiap CTE dapat mereferensikan keluaran simpul pendahulunya. Jika kompilasi gagal karena galat konfigurasi atau struktur graf yang tidak valid, Builder mengembalikan rincian galat beserta SQL parsial yang berhasil dihasilkannya.

## Ekspor

### Ekspor dan impor YAML

Anda dapat mengekspor alur kerja yang telah selesai sebagai berkas YAML menggunakan **Ekspor** tombol di bilah alat. Berkas yang diekspor berisi definisi alur kerja lengkap dalam format versi 2, termasuk semua konfigurasi simpul, sisi graf, dan posisi tata letak.

Untuk memuat alur kerja yang disimpan sebelumnya, gunakan **Impor** fungsi dan pilih sebuah `.yaml` atau `.yml` berkas. Untuk dokumentasi format lengkap, lihat [referensi YAML alur kerja](https://navixy.com/docs/analytics/id/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md).

## Keterbatasan saat ini

Transformation Builder saat ini berada dalam rilis awal, dan beberapa batasan berlaku:

* **Pratinjau memerlukan koneksi PostgreSQL yang aktif.** Tanpa koneksi, Anda tidak dapat mempratinjau hasil. Pratinjau dibatasi hingga 100 baris.
* **Graf harus bebas siklus.** Data mengalir hanya dalam satu arah, dari sumber ke keluaran.
* **Tidak ada mesin eksekusi bawaan.** Builder menghasilkan konfigurasi dan SQL untuk eksekusi runtime eksternal. Builder tidak memproses atau menyimpan data sendiri.
* **Hanya pemrosesan batch.** Pemrosesan data streaming tidak didukung.

## Langkah berikutnya

* [**Templat**](https://navixy.com/docs/analytics/id/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md): Konfigurasi alur kerja siap pakai yang dapat Anda impor dan sesuaikan di Transformation Builder.
* [**Lapisan transformasi**](https://navixy.com/docs/analytics/id/iot-query/schema-overview/transformation-layer.md): Pelajari bagaimana lapisan Transformation mengorganisasi data yang telah diproses ke dalam skema dan cara membuat kueri terhadapnya.
* [**referensi YAML alur kerja**](https://navixy.com/docs/analytics/id/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md): Tinjau spesifikasi lengkap untuk format ekspor dan impor YAML.
* [**Lapisan data mentah**](https://navixy.com/docs/analytics/id/iot-query/schema-overview/bronze-layer.md): Jelajahi skema sumber (`raw_telematics_data` dan `raw_business_data`) yang menyediakan data masukan untuk alur kerja Anda.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://navixy.com/docs/analytics/id/iot-query/schema-overview/transformation-layer/transformation-builder.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
