> 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/workflow-yaml-reference.md). # Referensi YAML alur kerja Format YAML alur kerja menangkap graf node, parameter, dan tepi Transformation Builder untuk ekspor, impor, dan berbagi antarlingkungan Halaman ini mendokumentasikan format YAML yang digunakan Transformation Builder untuk menyimpan dan memuat\ konfigurasi alur kerja. YAML adalah representasi internal Builder atas rancangan alur kerja: YAML menangkap graf node, parameter, dan edge sehingga alur kerja dapat diekspor,\ disimpan, dibagikan, atau diimpor ulang ke Builder. Saat Anda menjadwalkan alur kerja, Builder mengompilasi graf node menjadi satu kueri SQL\ dan mendaftarkannya sebagai fungsi basis data terjadwal. Kueri SQL tersebut dan tugas pg\_cron-nya adalah\ yang dieksekusi di basis data Anda. YAML tidak terlibat saat runtime. Jika Anda ingin membangun\ atau menjalankan transformasi secara independen dari Builder, tulis dan jadwalkan SQL secara langsung\ di basis data Anda tanpa menggunakan format ini. Format ini memiliki dua versi. **Versi 2** adalah format saat ini yang dihasilkan Transformation Builder saat ekspor. Format ini mengorganisasi node sebagai array datar dalam urutan topologis (`cte_nodes`) dengan `edges` array terpisah untuk koneksi. **Versi 1** adalah format lama yang menggunakan `nodes` kunci dengan referensi inline `depends_on` untuk koneksi. Transformation Builder dapat mengimpor kedua versi, tetapi selalu mengekspor versi 2. {% columns %} {% column %} #### **Ekspor** Menghasilkan file YAML dalam format versi 2. Anda dapat memicu ekspor dari **Ekspor** tombol di toolbar Transformation Builder, atau melalui API. File yang diekspor dapat disimpan di repositori, dibagikan dengan rekan kerja, atau diimpor ulang\ ke Transformation Builder di lingkungan lain. {% endcolumn %} {% column %} #### **Impor** Menerima versi 2 (format saat ini) dan versi 1 (format sebelumnya dengan `depends_on`koneksi berbasis **Impor** fungsi di Builder dan pilih sebuah `.yaml` atau `.yml` file. {% endcolumn %} {% endcolumns %} ## Cara ekspor dibentuk Generator ekspor membangun file YAML melalui empat langkah: 1. **Pengurutan topologis node.** Graf node dan edge diurutkan sehingga node sumber muncul terlebih dahulu, diikuti node transformasi menurut urutan dependensi, dan terakhir node Output. Jika graf mengandung siklus, digunakan urutan cadangan (berdasarkan posisi daftar node). 2. **Daftar sumber per node.** Untuk setiap node, generator mengumpulkan daftar terurut ID node pendahulu dari edge tempat `target` sama dengan ID node saat ini. Sebagai contoh, node SQL Transform dengan dua input akan memiliki `sources` daftar yang berisi tepat dua ID dalam urutan yang benar. 3. **array cte\_nodes.** Setiap node ditulis sebagai record dalam `cte_nodes` array, dalam urutan topologis. Lihat [struktur cte\_nodes](#cte_nodes-structure) di bawah untuk rincian field. 4. **Penyusunan YAML tingkat atas.** Generator menggabungkan `cte_nodes` array dengan daftar edges, metadata alur kerja, dan field opsional (viewport, schedule) ke dalam dokumen akhir. ### Kunci tingkat atas Akar file YAML versi 2 berisi kunci berikut: | Kunci | Keberadaan | Deskripsi | | ---------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- | | `version` | Selalu | Nomor versi format. Selalu `2` untuk ekspor saat ini. | | `nama` | Selalu | Nama alur kerja. | | `description` | Selalu | Deskripsi alur kerja. Dapat berupa string kosong. | | `cte_nodes` | Selalu | Array record node dalam urutan topologis. Lihat [struktur cte\_nodes](#cte_nodes-structure). | | `edges` | Selalu | Array objek edge. Lihat [struktur edges](#edges-structure). | | `output_node_id` | Jika node Output ada | ID node Output dalam alur kerja. | | `viewport` | Jika disetel dalam alur kerja | Posisi kanvas dan tingkat zoom: `{ x, y, zoom }`. Digunakan untuk memulihkan tata letak visual saat impor. | | `jadwal` | Jika schedule diaktifkan | Jadwal eksekusi: `{ cron, timezone }`. cron bawaan adalah `0 0 * * *`, zona waktu bawaan adalah `UTC`. | ### struktur cte\_nodes Setiap entri dalam `cte_nodes` array mewakili satu node dalam graf alur kerja. | Bidang | Deskripsi | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Pengidentifikasi node unik (string). | | `tipe` | Jenis node. Salah satu dari: `telematics`, `business`, `filter`, `resample`, `sql`, `arithmetic`, `custom`, `output`. | | `label` | Nama tampilan yang ditampilkan di kanvas. Jika tidak disetel, digunakan ID node. | | `description` | Deskripsi node. Dapat berupa string kosong. | | `position` | Koordinat kanvas sebagai `{ x, y }`. | | `sources` | Daftar terurut ID node pendahulu, yang diturunkan dari edge graf. Kosong untuk node sumber. | | `parameter` | Parameter konfigurasi node. Field spesifik bergantung pada jenis node. Lihat [Builder transformasi](/docs/analytics/id/iot-query/schema-overview/transformation-layer/transformation-builder.md) dokumentasi untuk rincian parameter per jenis node. | | `width`, `height` | Opsional. Dimensi kanvas untuk node, disertakan hanya saat disetel secara eksplisit. | **Pembersihan params.** Ini `available_tables` dan `available_columns` field dihapus dari `parameter` selama ekspor. Field ini diisi saat runtime ketika Builder terhubung ke basis data dan tidak boleh disimpan dalam YAML. **Tipe SQL dengan beberapa sumber.** Ketika node bertipe `sql` memiliki dua atau lebih sumber, ekspor menambahkan sebuah `join_spec` field ke record. Ini adalah array dengan satu elemen yang berisi konfigurasi join: ```yaml join_spec: - type: "left" # jenis join (huruf kecil): left, inner, right, full on_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id" ``` Ini `tipe` nilai diambil dari `join_type` parameter (dikonversi ke huruf kecil), dan `on_condition` diambil dari `join_condition`. Untuk node SQL dengan dua sumber, informasi join muncul di kedua `parameter` dan `join_spec`. ### struktur edges Ini `edges` array mendefinisikan koneksi antara node dalam graf alur kerja. ```yaml edges: - source: "node-telematics-1" target: "node-sql-1" - source: "node-business-1" target: "node-sql-1" ``` Setiap edge adalah objek dengan dua field: | Bidang | Deskripsi | | -------- | ----------------------------- | | `source` | ID node tempat edge berasal. | | `target` | ID node tempat edge berakhir. | ID edge dari antarmuka Builder tidak dipertahankan dalam ekspor. Saat impor, ID edge baru dihasilkan secara otomatis. ## Impor ### Deteksi versi Builder menentukan versi format YAML menggunakan logika berikut: * Jika root berisi `version: 2` atau kunci `cte_nodes`, file diproses sebagai **versi 2**. * Jika tidak, **versi 1** diharapkan. ### Impor versi 2 Builder melakukan iterasi pada `cte_nodes` array secara berurutan. Untuk setiap record: * Ini `id` dan `tipe` dibaca. Jenisnya dikonversi ke huruf kecil. Node dengan tipe `python` dilewati tanpa menimbulkan galat. * Parameter dibaca dari `parameter` kunci (atau `config` sebagai cadangan). Untuk `sql`-type node, jika sebuah `join_spec` field ada dalam record, field tersebut ditetapkan ke konfigurasi join node. * Ini `edges` array diurai menjadi pasangan source-target, dan ID edge baru dihasilkan. * Ini `viewport` dan `jadwal` field dipertahankan jika ada dalam YAML. ### Impor versi 1 (kompatibilitas mundur) File versi 1 menggunakan `nodes` kunci (array atau dictionary) dan secara opsional sebuah `edges` array atau `depends_on` field di dalam setiap node. Builder memproses file versi 1 sebagai berikut: * Jenis node yang didukung sama dengan versi 2: `telematics`, `business`, `filter`, `resample`, `sql`, `arithmetic`, `custom`, `output`. * Koneksi antara node dapat didefinisikan dengan dua cara: sebuah `edges` array tingkat atas, atau sebuah `depends_on` daftar di dalam setiap node. * Ini `inputs` dan `outputs` field pada setiap node dinormalisasi menjadi objek dengan `{ name, type }` struktur. * Jika edge menyertakan `sourceHandle` atau `targetHandle` pengidentifikasi port, impor menyesuaikan port node sesuai kebutuhan agar ditampilkan dengan benar di antarmuka Builder. ## Templat struktur YAML Templat berikut menunjukkan struktur lengkap file YAML versi 2 beserta anotasi: {% code expandable="true" %} ```yaml version: 2 name: "workflow_name" description: "Deskripsi alur kerja" cte_nodes: - id: "node-id-1" type: telematics # telematics | business | filter | resample | # sql | arithmetic | custom | output label: "Nama tampilan node" description: "" position: { x: 100, y: 100 } sources: [] # kosong untuk node sumber params: table_name: "tracking_data_core" time_column: "device_time" columns: [device_id, device_time, speed] filter_condition: "" time_window_minutes: "" - id: "node-id-2" type: sql label: "Transformasi SQL" description: "" position: { x: 400, y: 160 } sources: ["node-id-1", "node-id-3"] # ID pendahulu terurut params: join_type: LEFT join_condition: "a_node_id_1.device_id = a_node_id_3.device_id" select_columns: ["a_node_id_1.*", "a_node_id_3.sensor_label"] join_spec: # ditambahkan untuk node sql dengan 2+ sumber - type: "left" on_condition: "a_node_id_1.device_id = a_node_id_3.device_id" # field opsional per node: # width: 250 # height: 400 edges: - source: "node-id-1" target: "node-id-2" - source: "node-id-3" target: "node-id-2" # field opsional tingkat atas: output_node_id: "node-output-1" # jika node Output ada viewport: { x: 0, y: 0, zoom: 1 } # posisi kanvas saat impor schedule: { cron: "0 0 * * *", timezone: "UTC" } # jika penjadwalan diaktifkan ``` {% endcode %} ### Contoh Contoh berikut menunjukkan alur kerja versi 2 lengkap yang membaca data sensor telematics, menggabungkannya dengan deskripsi sensor dari skema business, menerapkan transformasi aritmetika untuk mengonversi jenis kolom, dan menulis hasilnya ke tabel output. {% code expandable="true" %} ```yaml version: 2 name: enriched_vehicle_metrics description: "Metrik kendaraan yang diperkaya dari telematics dan deskripsi sensor" cte_nodes: - id: node-telematics-1 type: telematics label: "Data mentah: telematics" description: "" position: { x: 100, y: 100 } sources: [] params: table_name: inputs time_column: device_time columns: [device_id, device_time, value] filter_condition: "" time_window_minutes: "" - id: node-business-1 type: business label: "Data mentah: business" description: "" position: { x: 100, y: 220 } sources: [] params: table_name: sensor_description key_column: sensor_id columns: [sensor_id, device_id, sensor_label] - id: node-sql-1 type: sql label: "Transformasi SQL" description: "" position: { x: 400, y: 160 } sources: [node-telematics-1, node-business-1] params: join_type: LEFT join_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id" select_columns: ["a_node_telematics_1.*", "a_node_business_1.sensor_label"] join_spec: - type: "left" on_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id" - id: node-arithmetic-1 type: arithmetic label: "Aritmetika" description: "" position: { x: 700, y: 160 } sources: [node-sql-1] params: expressions: - column: value expression: "value::numeric" expression_alias: value_num - id: node-output-1 type: output label: "Keluaran" description: "" position: { x: 1000, y: 160 } sources: [node-arithmetic-1] params: table_name: enriched_vehicle_metrics time_column: device_time primary_key: [device_id, device_time] write_mode: append edges: - { source: node-telematics-1, target: node-sql-1 } - { source: node-business-1, target: node-sql-1 } - { source: node-sql-1, target: node-arithmetic-1 } - { source: node-arithmetic-1, target: node-output-1 } output_node_id: node-output-1 viewport: { x: 0, y: 0, zoom: 1 } schedule: { cron: "0 0 * * *", timezone: "UTC" } ``` {% endcode %} Alur kerja ini melakukan langkah-langkah berikut: 1. **node-telematics-1** membaca `device_id`, `device_time`, dan `nilai` kolom dari `inputs` tabel dalam `raw_telematics_data` skema. 2. **node-business-1** membaca `sensor_id`, `device_id`, dan `sensor_label` dari `sensor_description` tabel dalam `raw_business_data` skema. 3. **node-sql-1** menggabungkan kedua sumber pada `device_id` menggunakan sebuah `JOIN kiri`, dan memilih semua kolom telematics serta `sensor_label` dari sumber business. 4. **node-arithmetic-1** menambahkan kolom terhitung `value_num` dengan mengonversi kolom teks `nilai` ke tipe numerik. 5. **node-output-1** mengonfigurasi hasil agar ditulis ke `enriched_vehicle_metrics` tabel dengan `tambahkan` mode, menggunakan `device_id` dan `device_time` sebagai primary key. {% hint style="info" %} Ekspor tidak menyertakan `available_tables` atau `available_columns` dalam `parameter`. Field ini diisi secara dinamis saat Builder terhubung ke basis data. Untuk node SQL dengan dua sumber, informasi join muncul di kedua `parameter` dan `join_spec`. {% endhint %} ## Langkah berikutnya * [**Builder transformasi**](/docs/analytics/id/iot-query/schema-overview/transformation-layer/transformation-builder.md): Pelajari cara merancang alur kerja menggunakan antarmuka visual. * [**Templat**](/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**](/docs/analytics/id/iot-query/schema-overview/transformation-layer.md): Pahami bagaimana data terproses diorganisasi ke dalam skema dan cara membuat kueri atasnya. --- # 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/workflow-yaml-reference.md?ask=&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.