Справочник YAML рабочего процесса

Справочник по формату экспорта/импорта рабочего процесса в YAML, включая поля узлов, связи и различия версий.

На этой странице документируется формат YAML, который Transformation Builder используется для экспорта и импорта рабочих процессов. Используйте этот справочник, когда необходимо обмениваться рабочими процессами между средами, хранить их в системе контроля версий или интегрировать с внешними системами выполнения.

Формат имеет две версии. Версия 2 является текущим форматом, который Transformation Builder генерирует при экспорте. Он организует узлы как плоский массив в топологическом порядке (cte_nodes) с отдельным edges массивом для связей. Версия 1 — это более старый формат, который использует nodes ключ с встроенными depends_on ссылками для связей. Transformation Builder может импортировать обе версии, но всегда экспортирует версию 2.

Экспорт

Генерирует YAML-файл в формате версии 2. Вы можете запустить экспорт из Экспорт кнопки на панели инструментов Transformation Builder или через API. Экспортированный файл можно сохранить в репозитории, поделиться с коллегами или передать во внешнюю среду выполнения для исполнения.

Import

Принимает как версию 2 (текущий формат), так и версию 1 (ранний формат со связями на основе depends_on-). Используйте Import функцию в Builder и выберите .yaml или .yml файл.

Как формируется экспорт

Генератор экспорта формирует YAML-файл в четыре шага:

1. Топологическая сортировка узлов. Граф узлов и ребер сортируется так, чтобы сначала шли исходные узлы, затем узлы трансформаций в порядке зависимостей, и, наконец, узел Output. Если в графе присутствует цикл, используется запасной порядок (по позиции в списке узлов).

2. Список источников для каждого узла. Для каждого узла генератор собирает упорядоченный список идентификаторов предшествующих узлов из ребер, где target равно идентификатору текущего узла. Например, узел SQL Transform с двумя входами будет иметь sources список, содержащий ровно два идентификатора в правильном порядке.

3. cte_nodes массив. Каждый узел записывается как запись в cte_nodes массиве, в топологическом порядке. См. структуру cte_nodes ниже для подробностей полей.

4. Сборка верхнего уровня YAML. Генератор объединяет cte_nodes массив со списком edges, метаданными рабочего процесса и опциональными полями (viewport, schedule) в итоговый документ.

Ключи верхнего уровня

Корень YAML-файла версии 2 содержит следующие ключи:

Ключ	Наличие	Описание
version	Всегда	Номер версии формата. Всегда 2 для текущих экспортов.
name	Всегда	Имя рабочего процесса.
description	Всегда	Описание рабочего процесса. Может быть пустой строкой.
cte_nodes	Всегда	Массив записей узлов в топологическом порядке. См. структуру cte_nodes.
edges	Всегда	Массив объектов ребер. См. структуру edges.
output_node_id	Когда существует узел Output	Идентификатор узла Output в рабочем процессе.
viewport	Если задано в рабочем процессе	Позиция на канве и уровень масштабирования: { x, y, zoom }. Используется для восстановления визуального расположения при импорте.
schedule	Если планировщик включён	Расписание выполнения: { cron, timezone }. По умолчанию cron — 0 0 * * *, часовой пояс по умолчанию — UTC.

структуру cte_nodes

Каждая запись в cte_nodes массиве представляет один узел в графе рабочего процесса.

Поле	Описание
id	Уникальный идентификатор узла (строка).
type	Тип узла. Один из: telematics, business, filter, resample, sql, arithmetic, custom, output.
label	Отображаемое имя, показанное на канве. Используется идентификатор узла, если имя не задано.
description	Описание узла. Может быть пустой строкой.
position	Координаты на канве как { x, y }.
sources	Упорядоченный список идентификаторов предшествующих узлов, полученный из ребер графа. Пуст для исходных узлов.
params	Параметры конфигурации узла. Конкретные поля зависят от типа узла. См. Transformation Builder документацию для подробностей параметров по типам узлов.
width, height	Необязательно. Размеры канвы для узла, включаются только если явно заданы.

Очистка параметров. The available_tables и available_columns поля удаляются из params во время экспорта. Эти поля заполняются во время выполнения, когда Builder подключается к базе данных, и не должны храниться в YAML.

SQL тип с несколькими источниками. Когда узел типа sql имеет два или более источников, экспорт добавляет join_spec поле в запись. Это массив с одним элементом, содержащим конфигурацию соединения:

join_spec:
  - type: "left"       # тип соединения (строчными): left, inner, right, full
    on_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id"

The type значение берётся из параметра узла join_type (преобразовано в строчные буквы), а on_condition берётся из join_condition. Для SQL-узлов с двумя источниками информация о соединении появляется в обоих params и join_spec.

структуру edges

The edges массив определяет связи между узлами в графе рабочего процесса.

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

Каждое ребро — это объект с двумя полями:

Поле	Описание
source	Идентификатор узла, от которого исходит ребро.
target	Идентификатор узла, в котором ребро заканчивается.

Идентификаторы ребер из интерфейса Builder не сохраняются в экспорте. При импорте генерируются новые идентификаторы ребер автоматически.

Import

Определение версии

Builder определяет версию формата YAML с использованием следующей логики:

• Если в корне содержится version: 2 или ключ cte_nodes, файл обрабатывается как версия 2.

• В противном случае версия 1 ожидается.

Импорт версии 2

Builder проходит по cte_nodes массиву в порядке. Для каждой записи:

• The id и type читаются. Тип преобразуется в строчные буквы. Узлы с типом python пропускаются без генерации ошибки.

• Параметры читаются из ключа params (или config как запасной вариант). Для узлов типа sql-type, если поле join_spec присутствует в записи, оно присваивается конфигурации соединения узла.

• The edges массив разбирается в пары источник-назначение, и генерируются новые идентификаторы ребер.

• The viewport и schedule поля сохраняются, если присутствуют в YAML.

Импорт версии 1 (обратная совместимость)

Файлы версии 1 используют nodes ключ (массив или словарь) и, опционально, edges массив или depends_on поля в каждом узле.

Builder обрабатывает файлы версии 1 следующим образом:

• Поддерживаемые типы узлов такие же, как в версии 2: telematics, business, filter, resample, sql, arithmetic, custom, output.

• Связи между узлами могут быть определены двумя способами: верхнеуровневый edges массив, или depends_on список внутри каждого узла.

• The inputs и outputs поля на каждом узле нормализуются в объекты со структурой { name, type } .

• Если ребра включают sourceHandle или targetHandle идентификаторы портов, импорт соответственно настраивает порты узлов для корректного отображения в интерфейсе Builder.

Шаблон структуры YAML

Следующий шаблон показывает полную структуру YAML-файла версии 2 с аннотациями:

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: []         # пусто для исходных узлов
    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"]   # упорядоченные идентификаторы предшественников
    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:                             # добавлено для sql-узлов с 2+ источниками
      - type: "left"
        on_condition: "a_node_id_1.device_id = a_node_id_3.device_id"

    # необязательные поля на узел:
    # ширина: 250
    # высота: 400

edges:
  - источник: "node-id-1"
    цель: "node-id-2"
  - источник: "node-id-3"
    цель: "node-id-2"

# необязательные верхнеуровневые поля:
output_node_id: "node-output-1"           # если существует выходной узел
viewport: { x: 0, y: 0, zoom: 1 }        # положение холста при импорте
schedule: { cron: "0 0 * * *", timezone: "UTC" }  # если планирование включено

Пример

В следующем примере показана полная версия рабочего процесса версии 2, которая читает телематические данные датчиков, объединяет их с описаниями датчиков из бизнес-схемы, применяет арифметическое преобразование для приведения типа столбца и записывает результаты в выходную таблицу.

version: 2
name: enriched_vehicle_metrics
description: "Обогащенные метрики транспортных средств из телематики и описания датчиков"

cte_nodes:
  - id: node-telematics-1
    type: telematics
    label: "Исходные данные: 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: "Исходные данные: 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" }

Этот рабочий процесс выполняет следующие шаги:

1. node-telematics-1 читает device_id, device_timeи значение столбцы из inputs таблицы в raw_telematics_data .

2. node-business-1 читает sensor_id, device_idи sensor_label из sensor_description таблицы в raw_business_data .

3. node-sql-1 объединяет два источника по device_id используя LEFT JOIN, выбирая все столбцы телематики плюс sensor_label из бизнес-источника.

4. node-arithmetic-1 добавляет вычисляемый столбец value_num путём приведения текстового значение столбца к числовому типу.

5. node-output-1 настраивает запись результата в enriched_vehicle_metrics таблицу с append режимом, используя device_id и device_time в качестве первичного ключа.

Экспорт не включает available_tables или available_columns в paramsЭти поля заполняются динамически при подключении Builder к базе данных. Для SQL-узлов с двумя источниками информация о соединениях появляется в обоих params и join_spec.

Дальнейшие шаги

• Transformation Builder: Узнайте, как проектировать рабочие процессы с помощью визуального интерфейса.

• Слой Transformation: Поймите, как обработанные данные организованы в схемы и как их запрашивать.