> 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/ru/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md). # Справочник по YAML рабочих процессов Формат YAML рабочего процесса содержит графы узлов, параметры и ребра Transformation Builder для экспорта, импорта и обмена между средами На этой странице описан формат YAML, который Transformation Builder использует для сохранения и загрузки\ конфигураций рабочих процессов. YAML — это внутреннее представление Builder для схемы рабочего процесса:\ оно фиксирует граф узлов, параметры и ребра, чтобы рабочий процесс можно было экспортировать,\ хранить, делиться им или повторно импортировать в Builder. Когда вы планируете рабочий процесс, Builder компилирует граф узлов в один SQL-запрос\ и регистрирует его как запланированную функцию базы данных. Именно этот SQL-запрос и его задание pg\_cron\ выполняются в вашей базе данных. YAML не участвует во время выполнения. Если вы хотите создавать\ или запускать преобразования независимо от Builder, пишите и планируйте SQL непосредственно\ в вашей базе данных, не используя этот формат. У формата есть две версии. **Версия 2** — это текущий формат, который Transformation Builder создает при экспорте. Он организует узлы как плоский массив в топологическом порядке (`cte_nodes`) с отдельным `edges` массивом для связей. **Версия 1** — это более старый формат, который использует `nodes` ключ с встроенными `depends_on` ссылками для соединений. Transformation Builder может импортировать обе версии, но всегда экспортирует версию 2. {% columns %} {% column %} #### **Экспорт** Создает файл YAML в формате версии 2. Экспорт можно запустить с помощью **Экспорт** кнопки на панели инструментов Transformation Builder или через API. Экспортированный файл можно хранить в репозитории, делиться им с коллегами или повторно импортировать\ в Transformation Builder в другой среде. {% endcolumn %} {% column %} #### **Import** Принимает как версию 2 (текущий формат), так и версию 1 (более ранний формат с `depends_on`depends\_on-связями). Используйте **Import** функцию в Builder и выберите `.yaml` или `.yml` файл. {% endcolumn %} {% endcolumns %} ## Как формируется экспорт Генератор экспорта создает файл YAML в четыре шага: 1. **Топологическая сортировка узлов.** Граф узлов и ребер сортируется так, чтобы сначала шли исходные узлы, затем узлы преобразования в порядке зависимостей и, наконец, узел Output. Если в графе есть цикл, используется запасной порядок (по позиции в списке узлов). 2. **Список источников для каждого узла.** Для каждого узла генератор собирает упорядоченный список ID узлов-предшественников из ребер, у которых `target` равен ID текущего узла. Например, узел SQL Transform с двумя входами будет иметь `sources` список, содержащий ровно два ID в правильном порядке. 3. **массив cte\_nodes.** Каждый узел записывается как запись в `cte_nodes` массиве в топологическом порядке. См. [структуру cte\_nodes](#cte_nodes-structure) ниже для подробностей о полях. 4. **Сборка YAML верхнего уровня.** Генератор объединяет `cte_nodes` массив с списком ребер, метаданными рабочего процесса и необязательными полями (viewport, schedule) в итоговый документ. ### Ключи верхнего уровня Корень файла YAML версии 2 содержит следующие ключи: | Ключ | Наличие | Описание | | ------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `version` | Всегда | Номер версии формата. Всегда `2` для текущих экспортов. | | `имя` | Всегда | Имя рабочего процесса. | | `описание` | Всегда | Описание рабочего процесса. Может быть пустой строкой. | | `cte_nodes` | Всегда | Массив записей узлов в топологическом порядке. См. [структуру cte\_nodes](#cte_nodes-structure). | | `edges` | Всегда | Массив объектов ребер. См. [структура edges](#edges-structure). | | `output_node_id` | Когда существует Узел Output | Идентификатор узла Output в рабочем процессе. | | `область просмотра` | При установке в рабочем процессе | Положение и масштаб холста: `{ x, y, zoom }`. Используется для восстановления визуального макета при импорте. | | `расписание` | Когда расписание включено | Расписание выполнения: `{ cron, timezone }`. По умолчанию cron — `0 0 * * *`, часовой пояс по умолчанию — `UTC`. | ### структуру cte\_nodes Каждая запись в `cte_nodes` массиве представляет один Узел в графе рабочего процесса. | Поле | Описание | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Уникальный идентификатор Узла (string). | | `тип` | Тип Узла. Один из: `telematics`, `business`, `фильтр`, `ресемплирование`, `SQL`, `арифметика`, `пользовательский`, `вывод`. | | `label` | Отображаемое имя, показываемое на полотне. Если не задано, используется ID узла. | | `описание` | Описание узла. Может быть пустой строкой. | | `позиция` | Координаты полотна как `{ x, y }`. | | `sources` | Упорядоченный список идентификаторов узлов-предшественников, полученный из ребер графа. Пусто для исходных узлов. | | `params` | Параметры конфигурации Узла. Конкретные поля зависят от типа узла. См. [Конструктор трансформаций](/docs/analytics/ru/iot-query/schema-overview/transformation-layer/transformation-builder.md) документацию с подробностями по параметрам для каждого типа узла. | | `width`, `height` | Необязательно. Размеры холста для узла, включаемые только при явной установке. | **Очистка параметров.** Этот `available_tables` и `available_columns` поля удаляются из `params` во время экспорта. Эти поля заполняются во время выполнения, когда Builder подключается к базе данных, и не должны храниться в YAML. **Тип SQL с несколькими источниками.** Когда Узел типа `SQL` имеет два или более источника, экспорт добавляет `join_spec` поле записи. Это массив с одним элементом, содержащим конфигурацию соединения: ```yaml join_spec: - type: "left" # тип соединения (в нижнем регистре): left, inner, right, full on_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id" ``` Этот `тип` значение берется из Узел `join_type` параметр (преобразованный в нижний регистр), и `on_condition` берется из `join_condition`. Для SQL-узлов с двумя источниками информация о соединении отображается в обоих `params` и `join_spec`. ### структура edges Этот `edges` Массив определяет связи между узлами в графе рабочего процесса. ```yaml ребра: - источник: "node-telematics-1" target: "Узел-sql-1" - источник: "Узел-business-1" target: "Узел-sql-1" ``` Каждое ребро — Объект с двумя полями: | Поле | Описание | | ---------- | ----------------------------------------------- | | `источник` | Идентификатор узла, в котором начинается ребро. | | `target` | ID Узел, в котором заканчивается ребро. | ID ребер из интерфейса Builder не сохраняются при экспорте. При импорте новые ID ребер генерируются автоматически. ## Import ### Определение версии Конструктор определяет версию формата YAML по следующей логике: * Если корень содержит `версия: 2` или ключ `cte_nodes`, файл обрабатывается как **версия 2**. * В противном случае, **версия 1** ожидается. ### Импорт версии 2 Builder перебирает `cte_nodes` массив по порядку. Для каждой записи: * Этот `id` и `тип` считываются. Тип преобразуется в нижний регистр. Узлы с типом `python` пропускаются без возникновения ошибки. * Параметры считываются из `params` ключа (или `config` в качестве запасного варианта). Для `SQL`-типовых узлов, если `join_spec` поле присутствует в записи, оно назначается конфигурации объединения узла. * Этот `edges` массив разбирается на пары источник-цель, и генерируются новые ID ребер. * Этот `область просмотра` и `расписание` поля сохраняются, если они присутствуют в YAML. ### Импорт версии 1 (обратная совместимость) Файлы версии 1 используют `nodes` ключ (массив или словарь) и, при необходимости, `edges` массив или `depends_on` поля внутри каждого Узла. Конструктор обрабатывает файлы версии 1 следующим образом: * Поддерживаемые типы Узлов те же, что и в версии 2: `telematics`, `business`, `фильтр`, `ресемплирование`, `SQL`, `арифметика`, `пользовательский`, `вывод`. * Связи между Узлами можно определить двумя способами: массив верхнего уровня `edges` массив или `depends_on` список внутри каждого узла. * Этот `входы` и `выходы` поля на каждом узле нормализуются в объекты с `{ name, type }` структура. * Если ребра включают `sourceHandle` или `targetHandle` идентификаторы портов, импорт соответствующим образом настраивает порты узлов для корректного отображения в интерфейсе Builder. ## Шаблон структуры YAML Следующий шаблон показывает полную структуру YAML-файла версии 2 с аннотациями: {% code expandable="true" %} ```yaml версия: 2 name: "workflow_name" description: "Описание рабочего процесса" cte_nodes: - id: "node-id-1" type: telematics # telematics | business | filter | resample | # sql | арифметика | пользовательский | вывод label: "отображаемое имя Узла" description: "" position: { x: 100, y: 100 } sources: [] # пусто для исходных узлов параметры: table_name: "tracking_data_core" time_column: "device_time" столбцы: [device_id, device_time, speed] filter_condition: "" time_window_minutes: "" - id: "node-id-2" тип: sql label: "Преобразование SQL" description: "" position: { x: 400, y: 160 } источники: ["node-id-1", "node-id-3"] # упорядоченные идентификаторы предшественника параметры: 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" # необязательные поля для каждого узла: # width: 250 # высота: 400 ребра: - источник: "Узел-id-1" цель: "узел-id-2" - source: "Узел-id-3" цель: "узел-id-2" # необязательные поля верхнего уровня: output_node_id: "node-output-1" # если существует Узел вывода viewport: { x: 0, y: 0, zoom: 1 } # позиция холста при импорте schedule: { cron: "0 0 * * *", timezone: "UTC" } # если Планирование включено ``` {% endcode %} ### Пример Следующий пример показывает полный рабочий процесс версии 2, который читает Данные датчиков телематики, объединяет их с описаниями датчиков из бизнес-схемы, применяет арифметическое преобразование для изменения типа столбца и записывает результаты в выходную таблицу. {% code expandable="true" %} ```yaml версия: 2 name: enriched_vehicle_metrics description: "Обогащенные метрики транспортных средств из телематики и описания датчика" cte_nodes: - id: node-telematics-1 тип: телематика метка: "Сырые данные: телематика" description: "" position: { x: 100, y: 100 } источники: [] параметры: table_name: inputs time_column: device_time columns: [device_id, device_time, value] filter_condition: "" time_window_minutes: "" - id: Узел-business-1 тип: бизнес label: "Сырые данные: Бизнес" description: "" position: { x: 100, y: 220 } источники: [] параметры: table_name: sensor_description key_column: sensor_id columns: [sensor_id, device_id, sensor_label] - id: Узел-sql-1 тип: sql label: "Преобразование SQL" description: "" position: { x: 400, y: 160 } sources: [Узел-telematics-1, Узел-business-1] параметры: 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 тип: арифметический label: "Арифметика" description: "" position: { x: 700, y: 160 } источники: [Узел-sql-1] параметры: выражения: - столбец: значение выражение: "value::numeric" expression_alias: value_num - id: node-output-1 тип: вывод label: "Вывод" description: "" position: { x: 1000, y: 160 } источники: [node-arithmetic-1] параметры: table_name: enriched_vehicle_metrics time_column: device_time primary_key: [device_id, device_time] write_mode: append ребра: - { source: node-telematics-1, target: node-sql-1 } - { source: node-business-1, target: node-sql-1 } - { source: узел-sql-1, target: узел-arithmetic-1 } - { source: node-arithmetic-1, target: node-output-1 } output_node_id: узел-output-1 viewport: { x: 0, y: 0, zoom: 1 } schedule: { cron: "0 0 * * *", timezone: "UTC" } ``` {% endcode %} Этот рабочий процесс выполняет следующие шаги: 1. **Узел-telematics-1** чтения `device_id`, `device_time`, и `value` столбцы из `входы` таблица в `raw_telematics_data` схемы. 2. **Узел-business-1** чтения `sensor_id`, `device_id`, и `sensor_label` из `sensor_description` таблица в `raw_business_data` схемы. 3. **Узел-sql-1** объединяет два источника по `device_id` с использованием `LEFT JOIN`, выбирая все телематические столбцы плюс `sensor_label` из бизнес-источника. 4. **Узел-arithmetic-1** добавляет вычисляемый столбец `value_num` путем приведения текста `value` столбец в числовой тип. 5. **Узел-вывод-1** настраивает запись результата в `enriched_vehicle_metrics` таблицу с `append` режиме, используя `device_id` и `device_time` в качестве первичного ключа. {% hint style="info" %} Экспорт не включает `available_tables` или `available_columns` в `params`. Эти поля заполняются динамически при подключении Builder к базе данных. Для SQL-узлов с двумя источниками информация о соединении появляется в обоих `params` и `join_spec`. {% endhint %} ## Следующие шаги * [**Конструктор трансформаций**](/docs/analytics/ru/iot-query/schema-overview/transformation-layer/transformation-builder.md): Узнайте, как проектировать рабочие процессы с помощью визуального интерфейса. * [**Шаблоны**](/docs/analytics/ru/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md): Готовые конфигурации рабочих процессов, которые вы можете импортировать и адаптировать в Transformation Builder. * [**слой преобразования**](/docs/analytics/ru/iot-query/schema-overview/transformation-layer.md): Поймите, как обработанные данные организованы в schemas и как выполнять их запрос. --- # 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/ru/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.