Referensi YAML alur kerja

Referensi untuk format ekspor/impor alur kerja YAML, termasuk bidang node, tepi, dan perbedaan versi.

Halaman ini mendokumentasikan format YAML yang Transformation Builder digunakan untuk mengekspor dan mengimpor alur kerja. Gunakan referensi ini ketika Anda perlu berbagi alur kerja antar lingkungan, menyimpannya dalam kontrol versi, atau mengintegrasikannya dengan sistem runtime eksternal.

Format tersebut memiliki dua versi. Versi 2 adalah format saat ini yang dihasilkan Transformation Builder saat ekspor. Ini mengatur node sebagai array datar dalam urutan topologis (cte_nodes) dengan sebuah edges array terpisah untuk koneksi. Versi 1 adalah format lama yang menggunakan sebuah nodes key dengan depends_on referensi inline untuk koneksi. Transformation Builder dapat mengimpor kedua versi tersebut, tetapi selalu mengekspor versi 2.

Ekspor

Menghasilkan berkas YAML dalam format versi 2. Anda dapat memicu ekspor dari Ekspor tombol di bilah alat Transformation Builder, atau melalui API. Berkas yang diekspor dapat disimpan di repositori, dibagikan kepada rekan kerja, atau dikirimkan ke runtime eksternal untuk dieksekusi.

Impor

Menerima baik versi 2 (format saat ini) maupun versi 1 (format sebelumnya dengan depends_on-berbasis koneksi). Gunakan fungsi Impor di Builder dan pilih sebuah .yaml atau .yml file.

Bagaimana ekspor dibentuk

Generator ekspor membangun berkas YAML melalui empat langkah:

1. Pengurutan topologis node. Graf node dan edge diurutkan sehingga node sumber berada di depan, diikuti oleh node transformasi dalam urutan ketergantungan, dan akhirnya node Output. Jika graf mengandung siklus, digunakan urutan fallback (berdasarkan posisi daftar node).

2. Daftar sumber per node. Untuk setiap node, generator mengumpulkan daftar terurut ID node pendahulu dari edges di mana target sama dengan ID node saat ini. Misalnya, sebuah node SQL Transform dengan dua input akan memiliki sebuah sources daftar yang berisi tepat dua ID dalam urutan yang benar.

3. array cte_nodes. Setiap node ditulis sebagai sebuah record dalam cte_nodes array, dalam urutan topologis. Lihat struktur cte_nodes di bawah untuk detail field.

4. Perakitan 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 dari berkas YAML versi 2 berisi kunci-kunci berikut:

Kunci	Kehadiran	Deskripsi
version	Selalu	Nomor versi format. Selalu 2 untuk ekspor saat ini.
name	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.
edges	Selalu	Array objek edge. Lihat struktur edges.
output_node_id	Ketika sebuah node Output ada	ID dari node Output dalam alur kerja.
viewport	Ketika disetel dalam alur kerja	Posisi kanvas dan tingkat zoom: { x, y, zoom }. Digunakan untuk mengembalikan tata letak visual saat impor.
schedule	Saat jadwal diaktifkan	Jadwal eksekusi: { cron, timezone }. Cron default adalah 0 0 * * *, zona waktu default adalah UTC.

struktur cte_nodes

Setiap entri dalam cte_nodes array merepresentasikan satu node dalam graf alur kerja.

Field	Deskripsi
id	Pengidentifikasi unik node (string).
type	Tipe node. Salah satu dari: telematics, business, filter, resample, sql, arithmetic, custom, output.
label	Nama tampilan yang ditunjukkan di kanvas. Jika tidak disetel, menggunakan ID node sebagai gantinya.
description	Deskripsi node. Dapat berupa string kosong.
position	Koordinat kanvas sebagai { x, y }.
sources	Daftar terurut ID node pendahulu, diturunkan dari edges graf. Kosong untuk node sumber.
params	Parameter konfigurasi node. Field spesifik bergantung pada tipe node. Lihat Transformation Builder dokumentasi untuk detail parameter per tipe node.
width, height	Opsional. Dimensi kanvas untuk node, disertakan hanya ketika secara eksplisit disetel.

Pembersihan Params. Skema available_tables dan available_columns field dihapus dari params selama ekspor. Field-field ini diisi pada waktu runtime ketika Builder terhubung ke basis data dan tidak boleh disimpan dalam YAML.

Tipe SQL dengan beberapa sumber. Ketika sebuah node bertipe sql memiliki dua atau lebih sumber, ekspor menambahkan sebuah join_spec field ke dalam record. Ini adalah sebuah array dengan satu elemen yang berisi konfigurasi join:

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"

Skema type nilai diambil dari join_type parameter node (dikonversi ke huruf kecil), dan on_condition diambil dari join_condition. Untuk node SQL dengan dua sumber, informasi join muncul di kedua params dan join_spec.

struktur edges

Skema edges array mendefinisikan koneksi antar node dalam graf alur kerja.

edges:
  - source: "node-telematics-1"
    target: "node-sql-1"
  - source: "node-business-1"
    target: "node-sql-1"

Setiap edge adalah sebuah objek dengan dua field:

Field	Deskripsi
source	ID dari node tempat edge berasal.
target	ID dari 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, berkas diproses sebagai versi 2.

• Jika tidak, versi 1 diharapkan.

Impor versi 2

Builder mengiterasi array cte_nodes urut. Untuk setiap record:

• Skema id dan type dibaca. Tipe dikonversi ke huruf kecil. Node dengan tipe python dilewati tanpa menimbulkan kesalahan.

• Parameter dibaca dari params kunci (atau config sebagai fallback). Untuk node bertipe sql-, jika sebuah join_spec field ada dalam record, itu ditetapkan ke konfigurasi join node.

• Skema edges array diurai menjadi pasangan sumber-target, dan ID edge baru dihasilkan.

• Skema viewport dan schedule field dipertahankan jika hadir dalam YAML.

Impor versi 1 (kompatibilitas mundur)

Berkas versi 1 menggunakan sebuah nodes key (array atau kamus) dan opsional sebuah edges array atau depends_on field di dalam setiap node.

Builder memproses berkas versi 1 sebagai berikut:

• Tipe node yang didukung sama dengan versi 2: telematics, business, filter, resample, sql, arithmetic, custom, output.

• Koneksi antar node dapat didefinisikan dengan dua cara: sebuah top-level edges array, atau sebuah depends_on daftar di dalam setiap node.

• Skema inputs dan outputs field pada setiap node dinormalisasi menjadi objek dengan { name, type } struktur.

• Jika edges menyertakan sourceHandle atau targetHandle identifier port, impor menyesuaikan port node sesuai untuk tampilan yang benar dalam antarmuka Builder.

Template struktur YAML

Template berikut menunjukkan struktur lengkap dari berkas YAML versi 2 dengan anotasi:

version: 2
name: "workflow_name"
description: "Workflow description"

cte_nodes:
  - id: "node-id-1"
    type: telematics    # telematics | business | filter | resample |
                        # sql | arithmetic | custom | output
    label: "Node display name"
    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: "SQL Transform"
    description: ""
    position: { x: 400, y: 160 }
    sources: ["node-id-1", "node-id-3"]   # ID pendahulu yang 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 top-level opsional:
output_node_id: "node-output-1"           # jika sebuah node Output ada
viewport: { x: 0, y: 0, zoom: 1 }        # posisi kanvas saat impor
schedule: { cron: "0 0 * * *", timezone: "UTC" }  # jika penjadwalan diaktifkan

Contoh

Contoh berikut menunjukkan sebuah alur kerja versi 2 lengkap yang membaca data sensor telematics, menggabungkannya dengan deskripsi sensor dari skema bisnis, menerapkan transformasi aritmetika untuk mengonversi tipe kolom, dan menulis hasilnya ke tabel output.

version: 2
name: enriched_vehicle_metrics
description: "Enriched vehicle metrics from telematics and sensor description"

cte_nodes:
  - id: node-telematics-1
    type: telematics
    label: "Raw data: 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: "Raw data: 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: "SQL Transform"
    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: "Arithmetic"
    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: "Output"
    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" }

Alur kerja ini melakukan langkah-langkah berikut:

1. node-telematics-1 membaca device_id, device_time, dan value kolom dari inputs tabel di raw_telematics_data skema.

2. node-business-1 membaca sensor_id, device_id, dan sensor_label dari sensor_description tabel di raw_business_data skema.

3. node-sql-1 menggabungkan kedua sumber pada device_id menggunakan sebuah LEFT JOIN, memilih semua kolom telematics ditambah sensor_label dari sumber bisnis.

4. node-arithmetic-1 menambahkan sebuah kolom terhitung value_num dengan melakukan casting teks value kolom menjadi tipe numerik.

5. node-output-1 mengonfigurasi hasil untuk ditulis ke enriched_vehicle_metrics tabel dengan append mode, menggunakan device_id dan device_time sebagai kunci utama.

Ekspor tidak menyertakan available_tables atau available_columns dalam params. Field-field ini diisi secara dinamis ketika Builder terhubung ke basis data. Untuk node SQL dengan dua sumber, informasi join muncul di kedua params dan join_spec.

Langkah selanjutnya

• Transformation Builder: Pelajari cara merancang alur kerja menggunakan antarmuka visual.

• Lapisan Transformasi: Pahami bagaimana data yang diproses diatur ke dalam skema dan bagaimana cara mengkuernya.