Пример "Здравствуй, Мир!"

Несмотря на простоту данного примера, в нём представлены основные принципы работы с PDI:Kettle:

• Работа с инструментарием Spoon
• Преобразования
• Шаги и Переходы
• Предопределенные переменные
• Предварительный просмотр и выполнение из Spoon
• Выполнение Преобразований из окна терминала средствами Pan

Описание

Для начала предполагается что существует список фамилий и имён людей в формате CSV файла, и необходимо создать XML файл с приветствием для каждого из них.

Если содержание CVS файла для обработки будет:

фамилия,имя
Иванов,Пётр
Семёнова,Любовь
Сидоров,Иван
Васильев,Семён
Семёнов,Дмитрий
Петрова,Анна

То готовый XML файл после обработки будет вида:

<Rows>
 −<Row>
       <message>Здравствуй, Пётр!</message>
  </Row>
 −<Row>
       <message>Здравствуй, Любовь!</message>
  </Row>
 −<Row>
       <message>Здравствуй, Иван!</message>
  </Row>
 −<Row>
       <message>Здравствуй, Семён!</message>
  </Row>
 −<Row>
       <message>Здравствуй, Дмитрий!</message>
  </Row>
 −<Row>
       <message>Здравствуй, Анна!</message>
  </Row>
</Rows>

Целью выполнения данного Преобразования будет создание фраз приветствий из файла.

В целом любое Преобразование состоит из цепочки Шагов (Step) связанных Переходами (Hop). Шаги и Переходы отображают путь перемещения потоков данных. Из чего следует, что Преобразование ориентированно на поток данных.

Подготовка окружения

До запуска Преобразования необходимо создать папку Tutorial в каталоге инсталляции или любом другом месте. В ней будут хранится все файлы из данного примера. Создать CSV файл с приведённым выше содержанием, и сохранить его в папке Tutorial под именем list.csv.

Инструкция по Преобразованию

Предлагаемую задачу можно разделить на три этапа:

1. Создание Преобразования
2. Разработка каркаса Преобразования из отдельных Шагов и Переходов
3. Настройка Шагов в соответствии с возлагаемыми на них задачами

Создание Преобразования

• Нажать New, затем выбрать Transformation, либо в меню File выбрать New, а затем Transformation. Также доступна комбинация клавиш Ctrl-N.
• Выбрав Transformation, нажать Settings....
• Появившееся окно позволяет задать настройки для Преобразования. Но для данного примера необходимо задать лишь графы Название Преобразования (Transformation name) и Описание (Description), затем нажать Save.
• Сохранить Преобразование в каталоге Tutorial под именем hello. Будет создан файл hello.ktr.

Разработка каркаса Преобразования из отдельных Шагов и Переходов

Каждое Преобразование состоит из множества отдельных Шагов. Из всего разнообразия Шагов в первую очередь группируются категории отвечающие за Ввод (Input) и Вывод (Output) данных из/для внешних источников/приёмников. Каждый из Шагов разработан так, чтобы его выполнение обеспечивало результат для определенной функции, например для чтения определённых параметров или нормализации набора введённых данных.

Переход это графическое представление передачи данных между двумя Шагами от источника к приёмнику. Данные передаваемые по средствам Перехода создаются на Шаге Исходящих Данных (Output Data) и предназначены для получения на Шаге Входящих Данных (Input Data). У одного Перехода есть только одно начало и одно окончание, но можно создать несколько Переходов которые будут выходить из одного Шага. Для таких случаев Исходящие Данные могут быть скопированы или распределены между каждым из приёмников. Также данные могут поступать из разных источников на один приёмник. В таких случаях Шаг приёмник должен обладать способностью объединять Входящие Данные из нескольких источников, чтобы создать единый поток Исходящих Данных.

Преобразование должно выполнять следующие функции:

• Получить данные из файла формата CSV
• Сформировать приветствия
• Сохранить приветствия в файле формата XML

Для каждого из этих функций необходимо использовать отдельные Шаги, согласно представленной ниже схемы:

В данном примере переходы между Задачами и Шагами определены как один к одному. Это Преобразование с очень простое структурой, но так бывает не всегда.

Для того чтобы начать создавать Преобразование необходимо:

• В окне приложения Spoon расположена панель Steps Palette, в ней раскрыть категорию Input.
• Перетащить иконку CSV file в рабочую область справа.
• Раскрыть категорию Scripting.
• Перетащить иконку Modified JavaScript Value в рабочую область.
• Раскрыть категорию Output.
• Перетащить иконку XML Output в рабочую область.

Теперь необходимо организовать связь между CSV file input и Modified Java Script Value создав Переход:

• Выбрать иконку первого Шага CSV file input.
• Удерживая на клавиатуре Shift переместить курсор на иконку второго Шага Modified Java Script Value.
• Установить связь между Modified Java Script Value и XML Output повторив действия.

Настройка Шагов в соответствии с возлагаемыми на них задачами

Для каждого из Шагов предусмотрено окно соответствующих настроек. В окне устанавливаются параметры определяющие функциональные возможности каждого вида Шагов. При этом Наименование Шага (Step Name) не влияет на функциональные возможности Шага, а только обозначает его в Преобразовании. Описание Шага (Step Description) подробно разъясняет цели выполнения Шага, и также не влияет на его функциональные возможности.

Настройка Шага Ввод из CSV файла (CSV file input)

• Дважды нажать на Шаг CSV file input.
• Появиться окно настроек для этого Шага. В нём необходимо указать расположение, формат и описать содержания файла для загрузки.
• Изменить наименование заданное по-умолчанию в графе Step name на более соответствующее возлагаемым на данный Шаг задачам. Для данного примера назовём Шаг Получение списка имён.
• В графе Filename ввести название и расположение исходного файла.

Примечание: Справа от поля ввода находится символ в виде красного доллара. Это обозначает возможность использования в данном поле переменные. Переменная может быть введена вручную:

${name_of_the_variable}

Или выбрана из списка в окне переменных, для чего следует нажать Ctrl-Пробел. В данном окне представлены предопределённые переменные и переменные заданные пользователем, но так как переменные не задавались, то в списке будут лишь предопределённые переменные. Среди них необходимо выбрать:

${Internal.Transformation.Filename.Directory}

После переменной ставиться наклонная черта и имя предварительно созданного файла:

${Internal.Transformation.Filename.Directory}/list.csv

После запуска значение данной переменной будет получено и выведено в виде пути к каталогу, где храниться Преобразование. Затем будет найден файл list.csv в данном каталоге.

• Нажатие кнопки Get Fields добавляет список наименований столбцов и структуры данных из исходного файла. Предполагается что у файла есть заголовок (для этого в графе Header row present должна стоять отметка).

Примечание: Кнопка Get Fields существует во многих видах Шагов и доступна в окне настроек. Она необходима для загрузки структуры данных из внешнего источника или из предыдущего Шага. При этом всё может быть введено вручную, но эта кнопка сокращает время необходимое для ввода множества полей, при этом предполагается что все они будут использованы в дальнейшей работе.

• Теперь структура содержит наименование столбцов из файла. Для данного примера это фамилия и имя:
  
• Снять галочку с графы Lazy conversion?.

Примечание: При работе с данными содержащими символы кириллицы также лучше всего указывать кодировку данных файла явно, выбрав из списка в графе File encoding соответствующее значение.

• Нажать Preview и удостовериться, что файл был корректно прочитан. Полученные из файла данные должны отобразится в появившемся окне.
• Нажать OK для завершения и принятия настроек для Шага CSV file input.

Конфигурация Шага JavaScript для модификации значения (Modified JavaScript Value)

• Дважды нажать на Шаг Modified JavaScript Value.
• Появиться окно настроек для этого Шага. Данное окно отличается от предыдущего возможностью написания исполняемого кода на языке JavaScript. Оно необходимо для создания фразы из двух частей, объединения части приветствия "Здравствуй, " с каждым из имён.
• Назвать данный Шаг Создание приветствия.
• Центральная область окна настроек предназначена для ввода кода. В левой панели представлен набор доступных для использования при написании кода функций. При этом внизу списка представлены две группы Input fields и Output fields готовые к использованию. Для данного примера потребуются два поля: фамилия и имя. Ввести код:

  var message = 'Здравствуй, ' + имя.getString() + "!";
  

  Примечание: Функцию имя.getString() можно ввести вручную или дважды нажать на поле в раскрывающемся списке функций.
• В нижней части окна расположен список создаваемых в результате выполнения скрипта переменных. В данном примере создаётся переменная message. Так как значение данной переменной должно быть передано в файл с результатом Преобразования, наименование данной переменной следует указать в списке. Результат будет иметь следующий вид:
  

Внимание: Не следует путать переменные внутри скрипта с переменными приложения PDI:Kettle, это не одно и тоже.

Примечание: Для совместимости выполнения скриптов в различных вариантах версий PDI:Kettle следует графу Compatibility mode? отметить галочкой.

• Нажать OK для завершения и принятия настроек для Шага Step Modified Script Value.
• Выбрать иконку только что отредактированного Шага. На данном Шаге происходит добавление нового поля к Входящим Полям (Input Field) и передача их всех вместе в Исходящие Поля (Output Field). Входящие Поля поступают на данном Шаге. Исходящие Поля покидают данный Шаг. Каждый шаг производит трансформацию значений поступивших данных. В данном примере, значения поступивших данных остались без изменений добавилось только одно Исходящее Поле. Но есть Шаги, которые добавляют значения к Входящим Полям, например Calculator. Также есть Шаги производящие фильтрацию и комбинирование поступающих данных, в результате Исходящих Полей меньше чем Входящих Полей, например Group by.
• Нажать правую клавишу мыши для доступа к контекстному меню.
• Выбрать Show Input Fields. В появившемся окне можно увидеть Входящие Поля фамилия и имя, полученные на предыдущем Шаге.
• Выбрать Show Output Fields. В появившемся окне видно, что поступившие поля остались без изменений, но добавилось одно новое поле message.

Конфигурация Шага Вывод в XML файл (XML Output)

• Дважды нажать на Шаг XML Output. Откроется окно для данного вида Шага. На данном шаге определяется место расположения и название файла с результатом выполнения Преобразования. Также задаются Поля, которые необходимо поместить в данный файл. Для вывода могут быть заданы, как все Поля достигшие данного Шага, так и отдельные Поля по выбору.
• На вкладке File задать название Выгрузка списка приветствий для данного Шага.
• В графе File ввести:

  ${Internal.Transformation.Filename.Directory}/hello.xml
  

• Перейти на вкладку Fields и нажать кнопку Get Fields, в списке полей появятся три поля для вывода. Для исходящего файла необходимо только поле message, поэтому необходимо удалить поля имя и фамилия.
  
• Нажать OK для завершения и принятия настроек для Шага XML Output.
• Сохранить Преобразование.

Принципы работы

При выполнении Преобразования практически все Шаги выполняются одновременно. Из-за того, что Преобразование запускает потоки асинхронно, скорость выполнения отдельных Шагов неодинакова. Каждая выполняемая строка потока передаётся на следующий Шаг не ожидая следующей строки данных. Необходимо не забывать эту особенность Преобразований, так как она может сильно повлиять на результат выполнения.

Настройка примера "Привет, Мир!" практически завершено. Преобразование считывает данные из входного файла; с помощью кода JavaScript создаются приветствия для каждого из рядов данных; в итоге полученное сообщение сохраняется в конечном файле. В данном небольшом примере всего несколько строк с именами, поэтому заметить асинхронное выполнение очень сложно. Однако надо иметь ввиду что, когда одна строка записывается в конечный файл, другая только покидает первый Шаг Преобразования.

Проверка, просмотр и выполнение

• Перед выполнением Преобразования, необходимо проверить правильность работы каждой из функций. Выбрать Transformation и нажать Verify. Spoon проверит синтаксис Преобразования, выявив недостижимые Шаги и несуществующие связи. Если Преобразование прошло проверку успешно (а это должно быть именно так, если следовать данной инструкции), оно готово для предварительного просмотра.
• Выделить Шаг Создание приветствия, выбрать Transformation и затем нажать Preview. Должно появится окно вида:
  
• Spoon предлагает предварительно просмотреть результаты выполнения выбранного Шага. Нажать кнопку QuickLaunch. После чего появится окно с результатом полученным в результате выполнения Шага Создание приветствия. Если результат удовлетворяет предъявляемым требованиям, значит всё готов для выполнения Преобразования.
• Выбрать Transformation и затем нажать Run.
• Появится окно в котором можно задать параметры выполнения и отслеживания Преобразования. Нажать кнопку Launch.
• В нижней части окна приложения появится окно с несколькими вкладками. Во вкладках содержится информация о выполнении текущего Преобразования.

На вкладке Step Metrics отображено выполнение операций Преобразования по Шагам. Необходимо обратить внимание на следующие колонки:

• Read: количество строк полученных из предыдущего Шага.
• Written: количество строк переданных с данного шага на следующий.
• Input: число строк прочитанных из файла или таблицы базы данных.
• Output: число строк записанных в файл или таблицу базы данных.
• Errors: число ошибок возникших при выполнении. Если возникли ошибки вся строка отмечается красным.

На вкладке Logging отображён журнал выполнения. В нём содержится подробная информация о выполнении Преобразования по Шагам. Если детально разбирать журнал выполнения, то можно увидеть асинхронность выполнения Шагов. При успешном выполнении Преобразования в нижней строке журнала будет следующее сообщение:

Spoon - The transformation has finished!!

Также при успешном завершении Преобразования будет создан файл hello.xml, необходимо проверить его содержание на корректность выполнения поставленной задачи.

Pan

Pan это модуль исполнения Преобразований из терминального окна. Его запуск производится через скрипт pan.bat в Windows или pan.sh на других платформах. Скрипт расположен в установочном каталоге. Если скрипт запускается без параметров на экран выводятся список доступных параметров для выполнения Pan.

Запустить Преобразование можно следующей командой:

Pan /file <Jobs_path>/hello.ktr /norep

• /norep команда не включает подключение Spoon к репозитарию.
• /file указывает на имя файла содержащего Преобразование.
• <Jobs_path> полный путь к каталогу с примером: C:/Pentaho/Tutorial или /home/PentahoUser/Tutorial.
  Остальные параметры запуска будут использованы по-умолчанию.

После запуска данной команды Преобразование выполняется точно также, как и при запуске через Spoon. В данном случае на экран или в файл (если его указать) будет выведен журнал выполнения. Формат журнала будет отличаться от того, что был представлен в графической оболочке, но его содержание будет аналогичным.