Конструктор правил разбора JSON

14 минутное чтение

Конструктор правил выборки позволяет создавать правила выгрузки на основании имеющегося образца с данными в формате «JSON», а также просматривать данные в формате «JSON».

Конструктор умеет собирать статистику по повторяющимся структурам в данных «JSON». Используется это для прогнозирования формата данных и размерностей полей таблицы приёмника, а также визуальной оценки заполняемости полей данными.

Ключевые понятия

«Дерево данных» — структура данных свойственная таким типам данных как «JSON», «XML». В такой структуре каждый элемент может находится в отношениях родитель/подчинённый к другим элементам структуры.
«Узел дерева» — синоним элемента структуры дерева.
«Корень (дерева данных)» — первый узел в иерархии подчинённости дерева данных обозначается как «$».
«Путь элемента» — последовательность имен или индексов узлов от корня дерева до указанного элемента (включительно).
Например: $.ServiceResponses[0].application.details.accident[0].accident_date.
«Точка итерации» — элемент дерева, подчиненные элементы которого имеют одинаковую структуру или тип данных. Обозначается как: «<ИмяЭлемента>[<Параметры среза>]».
«Параметры среза» — параметры описывающие какие именно подчиненные элементы участвуют в выборке.
Для типа данных «Объект» допустимо указание параметров среза только:
- [*] — все элементы.
  Для типа данных «Массив»:
- [*] — все элементы;
- [0, 1, 2, 3] — элементы с индексами 0, 1, 2, 3;
- [20:100] — (диапазон) элементы с индексами от 20 до 100;
- [20:100, 200:300] — (диапазон) элементы с индексами от 20 до 100 и от 200 до 300;
- [20:-1] — (диапазон) элементы от 20 до последнего;
- [-1] — последний элемент.
  Все диапазоны указываются включительно (содержат в том числе и граничные элементы)
«Путь итерации» — последовательность имен или индексов узлов от корня дерева до крайней точки итерации с указанием параметров среза точек итерации.
Например: $.ServiceResponses[-].application.details.accident[0:5].
«Итерационный путь элемента» — последовательность имен или индексов узлов от корня дерева до указанного элемента (включительно), с указанием параметров среза точек итерации.
Например: $.ServiceResponses[-].application.details.accident[0:5] .accident_date.
«Правила разбора данных» — совокупность путей до элементов и / или итерационных путей элементов участвующих в выборке, с указанием сопутствующих параметров (типы данных, имена полей и т.д.).
«Набор правил» — совокупность путей до элементов и / или итерационных путей элементов участвующих в выборке, относящихся к одному пути итерации.
«Распределённый элемент» — элемент, присутствующий в разных ветвях дерева данных, но имеющий для всех экземпляров одинаковый итерационный путь элемента.
«Статистика элемента» — расчётные показатели распределённого элемента, такие как:
- тип данных;
- % в наличии;
- % Null;
- % пустых;
- минимальное и максимальное значение;
- рекомендуемая длина и точность поля таблицы приёмника для элемента.
«Псевдоэлемент дерева» — элемент отображаемого дерева данных, не имеющий под собой конкретной основы в данных. Служит для настройки или асоциации с текущим (на момент выборки) элементом. Например элементы отображающие параметры среза для точки итерации, или элементы означающие имя / индекс текущего (на момент выборки) элемента.

Диалог конструктора

Диалог конструктора имеет две рабочие области (область данных и облать правил) и панель с кнопками служебных функций.
При открытии конструктора для редактирования правила, область данных будет скрыта, а область правила показана. При отрытии конструктора для просмотра данных, наоборот область правила будет скрыта, а область данных показана. Если конструктор открывается для создания / редактирования правила, но с передачей в него данных, обе область быдут показаны. Однако вы в любой момент можете включить / выключить видимость нужных вам областей при помощи кнопок на панели функций:

Область данных

Область данных служит для отображения загруженных данных.
Просмотр данных возможен как в виде дерева, так и в виде текста. Снизу расположены вкладки «Данные (дерево)» и «Данные (текст)», перемещаясь по которым можно изменять способ отображения (дерево или текст). Отображение в виде дерева позволяет только просматривать структуру данных. Текст же можно редактировать.
Дерево имеет два режима просмотра: режим просмотра значений элементов и режим просмотра статистики по значениям распределённых элементов.

Область правил

Область правил содержит коллекцию правил выборки элементов и описание структуры полей таблицы приёмника.

Панель служебных функций

Позволяет:

выполнять выборку данных из предварительно загруженных «JSON»-данных;
управлять праметрами выборки;
загружать «JSON»-данные;
выбирать кодировку элементов «JSON» текстового типа;
устанавливать значение предела итераций для области просмотра данных;
управлять видимостью Области данных;
управлять видимостью Области правил;
отслеживать текущие процессы конструктора (отображается в правом верхнем углу);
переключать режим отображения дерева данных (статистика / значения).

Представленные функции

«Загрузить JSON» — позволяет загрузить JSON данные. После загрузки данные будут доступны для просмотра в Области данных.

«Кодировка» — позволяет явно указать какую кодировку нужно использовать при выборки данных текстового типа.
Автоопределение будет срабатывать только при наличии в загруженных данных Byte Order Mark (BOM).

«Предел итераций» — позволяет ограничить количество элементов отображающихся в узле дерева данных выбранным значением.

Также влияет на количество элементов участвующих в расчёте статистики, ограничивая его выбранным значением для каждого узла (точки) итерации (например для значения в 100 элементов при 2 точках итерации (в пути до элемента) фактическое количество будет равно 100 - 100 = 10 000).

Цель данного ограничителя — снизить нагрузку на сервер и тем самым сократить временные задержки в реакции интерфейса пользователя, при разворачивании дерева данных в области данных конструктора.

Если необходимо расчитать статистику максимально точно, целесобразно увеличить значение до максимально необходимого, что конечно приведёт к увеличению задержки при разворачивании узлов дерева.

Предел итераций влияет только на отображаемые данные.
На результат извлечения данных предел итераций никак не виляет.

«Видимость области данных» — включает / выключает отображение области данных конструктора:

«Видимость области правил» — включает / выключает отображение области правил конструктора:

«Выбрать данные» — запускает процесс извлечения данных по правилу. По окончании процесса откроется окно просмотра выбранных по правилу данных:

«Параметры выборки» — позволяет указать дополнительные параметры выборки.

Доступные параметры:

«Использовать null как значение по умолчанию» — при активизации данного параметра алгоритм выборки будет игнорировать настройки правила в части установленных значений по умолчанию, значения отсутствующих элементов будут загружены как null-значения.

Полезно для визуального анализа заполняемости таблицы приёмника данными.

Не влияет на последующее использование правила.

«Выбор режима дерева данных» — позволяет переключать дерево данных (в области данных) между режимами просмотра данных и просмотра статистики.
Состояние выключателя:

включен — дерево отображает статистику;
выключен — дерево отображает значения.

«Текущий путь итерации» — путь итерации текущего набора правил.

Текущий путь итерации имеет два режима отображения. Режим отображения зависит от режима отображения дерева данных:

«Режим отображения дерева данных» — показывать статистику:

Если текущий путь итерации не умещается целиком на экране, при помощи кнопок:

можно сдвигать элементы пути вправо/влево для обзора всех элементов.

«Режим отображения дерева данных» — показывать значения:

«Сбросить текущий путь итерации» — позволяет сбросить текущий путь итерации в одно действие.

Доступна если список правил пуст или область правила откреплена от области данных.

Область данных

Область данных служит для отображение загруженных ранее данных.

Отображение возможно в виде дерева и в виде текста.

Дерево данных может отображать данные в режиме статистики и в режиме значений.

Дерево данных: режим статистики

Описание полей представлено ниже.

«Имя» — имя элемента дерева данных или имя псевдоэлемента или параметры среза в виде строки.
«Признак точки итерации» — обозначает узлы выбранные в качестве точек итерации:

«Тип» — тип «JSON»-элемента. Если элементы, будучи распределёнными, имеют разные типы то они будут перечислены через запятую, а поле окрасится красным цветом. Данные из полей смешанного типа допускается собирать только в виде JSON данных (см. настроку правила).
«Всего %» — процент значений элемента в выборке по текущему правилу от общего числа строк в результате выборки.
«Null %» — процент отсутствующих значений элемента в выборке по текущему правилу от общего числа строк в результате выборки. Сюда входят как элементы со значениям null, так и элементы отсутствующие, но ожидаемые. Элемент является ожидаемым если в некоторых узлах он присутствует, а в других нет.
«Пустые %» — процент пустых значений элемента в выборке от общего числа строк в результате выборки. К пустым относятся пустые строки для текстового типа элемента и нулевое значение элемента для числового типа элемента.
«Мин.» — минимальное значение элемента в выборке. Для числового типа элемента — это минимальное числовое значение элемента. Для текстового типа элемента — это минимальная длина строки. По типам данных элемента отличным от текстового или числового данный показатель не рассчитывается.
«Макс.» — максимальное значение элемента в выборке. Для числового типа элемента — это максимальное числовое значение элемента. Для текстового типа элемента — это максимальная длина строки. По типам данных элемента отличным от текстового или числового данный показатель не рассчитывается.
«Длина» — рекомендуемая для поля таблицы приёмника длина. Для строкового типа — длина строки. Для числового — максимальное количество цифр в числе. Например, для числа 91234567.89 длина — 10. Этот показатель идентичен параметру поля таблицы СУБД character_maximum_length и precision соответственно для строк и чисел. Подсчитывается только для числового и текстового типов элемента.
«Точность» — рекомендуемая для поля таблицы приёмника размер дробной части. Этот показатель идентичен параметру поля таблицы СУБД scale. Подсчитывается только для числового типа элемента.

При наличии точек итерации (относительно которых нижележащие структуры повторяются) в пути к элементу, расчёт показателей статистики происходит с помощью анализа значений повторяющихся структур. В отсутствии точек итерации статистические показатели расчитываются для единичных элементов.

Дерево данных: режим значений

Описание полей представлен ниже.

«Имя» — имя элемента дерева данных или имя псевдоэлемента или параметры среза в виде строки.
«Признак точки итерации» — обозначает узлы выбранные в качестве точек итерации:

«Тип» — тип «JSON»-элемента.
«Значение» — поле отображающее значение элементов чиcловых и булевых типов, а также null.
«Строковое значение» — поле отображающее значение элементов строкового типа.

Разделение на разные колонки отображаемых значений по типам сделано для улучшения читаемости данных в таблице-дереве.
В режиме дерева данных «просмотр значений» функции по работе с точками итерации не доступны (выбор/отмена выбора узла в качестве точки итерации, настройка параметров среза).

Панель функций дерева данных

Позволяет выбрать элемент дерева в качестве точки итерации или отменить выбор элемента в качестве точки итерации. При отмене выбора элемента в качестве точки итерации все нижележащие точки итерации будут также отменены.

Чтобы выбрать элемент в качестве точки итерации его необходимо предварительно развернуть. В момент разворачивания будет прочитана структура нижележащих элементов и проведена оценка возможности использования данного узла в качестве точки итерации. Оценка проводится на предмет совпадения типов данных элементов. Типы должны быть одинаковыми и не содержать смешанные типы.

Доступна только в режиме просмотра статистики.

Кнопка на рисунке выше открывает диалог настройки параметров среза точки итерации. Доступна только для настройки параметров среза элемента типа Массив.

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

Кнопка функции станет активной.
Доступна только в режиме просмотра статистики.

Кнопка на рисунке выше позволяет посмотреть все значения распределённого элемента. Предварительно нужный элемент необходимо выбрать в дереве данных.

Отображается только в режиме просмотра статистики.

Кнопка на рисунке выше включает / отключает сбор и отображение статистики в режиме просмотра статистики.

Если объём данных большой, а посмотреть нужно только структуру дерева, можно использовать эту функцию и отключить сбор статистики. Вернуться к сбору статистики можно в любой момент.

Отображается только в режиме просмотра статистики.

Кнопка на рисунке выше отображает путь до текущего выбранного элемента дерева.

Псевдоэлементы дерева данных

При выборе элемента дерева в качестве точки итерации элемент сворачивается, а в его содержимом появляется два псевдоэлемента:

«Параметры среза» — отображает текущую настройку среза в виде строки вида “[0:5, 10, 20:-1]” или “[-]”. Содержит в качестве дочерних элементов свернутую структуру повторяющихся элементов. По двойному нажатию открывает диалог настройки параметров среза. В контекстном меню элемента присутствует команда «Параметры среза», которая также открывает диалог настройки параметров среза.

«Текущее положение» — имя элемента зависит от типа радителя, для массива — «Индекс элемента», для объекта «Имя элемента». Используется для формирования правила выборки имени / индекса текущего элемента, методом перетаскивания в область правила. Если в результатах выборки нужно получать не только данные элементов, но и их имена/индексы, используйте этот элемент для формирования соответствующей строки правила.

Контекстное меню дерева данных

Отображается по правому клику мыши на элементе дерева данных.

Функциональность аналогична «Панели функций дерева данных».

Диалог настройки параметров среза

Отображает настройки параметров среза выбранного элемента.
Каждая строка задаёт диапазон значениий или единичный элемент. Единичные элементы указываются ввиде одинаковых индексов для начала и конца диапазона. Нумерация индексов начинается с нуля. Если необходимо указать элементы с конца, необходимо указывать отрицательные знаяения:

«-1» — последний элемент;
«-2» — предпоследний и т.д.

Внесённые изменения применятся при закрытии окна диалога настроек параметров среза.

Если в списке правила присутствуют элементы содержащие в пути настраиваемую точку итерации, их пути автоматически скорректируются под новые параметры среза.

Просмотр данных в виде текста

В нижнем левом углу присутствуют вкладки:

перемещаясь по которым, можно изменять способ отображения данных (дерево или текст). Дерево позволяет только просматривать структуру данных JSON. Текст можно редактировать. Окно просмотра данных в виде текста находится на вкладке «Данные (текст)».

В окне просмотра текста имеется кнопка команды позволяющая отформатировать текст для улучшения читаемости.

Область правила

Область правил содержит коллекцию строк с правилами выбора значений и панель с функциями для работы с коллекцией.

Коллекция строк с правилами выбора значений

Значения колонок таблицы коллекции:

«Имя поля» — имя колонки таблицы в которую следует поместить значение из первичных данных.
«Тип поля» — тип данных колонки таблицы
«Путь к элементу» — описание пути к элементу внутри первичных данных в формате «JSONPath».
«Тип элемента» — ожидаемый тип элемента в первичных данных. Используется для проверки/приведения типа. Если тип элемента в первичных данных не соответствует указанному, данные элемента загружены не будут. Если выбрать тип элемента аналогичный типу первичных данных (пример: «JSON-JSON»), то данные элемента будут загружены в оригинальном формате. Таким образом можно загружать целиком блоки данных, например массив «JSON» можно поместить в одну колонку таблицы с типом text или «JSONb». Если тип поля таблицы и тип поля элемента отличаются, будет выполнена попытка приведения типа элемент к типу поля. В ситуациях когда приведение не очевидно, есть варианты для таких типов, например: «Дата строкой (ISO)» подсказывает, что данные имеют строковой тип, но представляют собой дату в ISO формате.
«!» — флаг необязательного элемента. Необязательным является такой элемент, данные из которого не нужны сами по себе, а только совместно с данными обязательных элементов. Таким образом, если данных в обязательных элементах не окажется, не обязательные загружены не будут.
«По умолчанию» — значение по умолчанию для колонки таблицы. Используется если элемент в данных отсутствует, не содержит значение или не может быть приведён к типу данных колонки таблицы.

Если данные были загружены в конструктор, но отображение панели данных не включено, то будет показана ещё одна колонка:

В этой колонке отображаются кнопки:

по нажатии на которые окрывется панель данных (панель правил при этом скрывается), что позволяет выбрать в дереве данных целевой элемент для строки правила. Выбор осуществляется двойным нажатием кнопки мыши. Такой вариан использования подойдёт, если разрешение монитора не позволяет разместить панель данных и панель правила одновременно на экране.

Внизу коллекции строк находятся вкладки наборов:

Наборы позволяют загружать в одну таблицу строки, полученные из разных областей первичных данных. Все наборы описывают общую структуру таблицы приёмника, но содержат разные пути к элементам. Для добавления / удаления наборов используются кнопки на панели функций.

Панель функций

На панели функций представлены следующие функции для работы с коллекцией.

Перемещение строк коллекции по списку. При этом меняется очерёдность в которой колонки будут описаны при создании таблицы.

Добавляет новую строку правила загрузки элемента в коллекцию.

Сортирует строки коллекции по имени колонки (по возрастанию).

Очищает пути к элементам у всех строк текущего набора.

Полностью очищает коллекцию правил

Заполняет значения по умолчанию типовыми значениями. Заполняются только те позиции в коллекции, значение по умолчанию для которых выставлено в Null.

Открывает коллекцию как таблицу в отдельном окне. Эта функция позволяет сохранить правила в табличный документ (файл), или перенести коллекцию (через буфер обмена) в другое правило или в другой конструктор. Например из ETL тестового контура в рабочий. Таблица доступна для редактирования. Все внесённые изменения отразятся на коллекции правил после закрытия окна с таблицей.

Сохраняет текущее правило в справочник правил разбора данных. Если правило новое, то будет предложено ввести имя. Если правило модифицируется пользователем, то данная кнопка подсвечивается розовым контуром, для сигнализации о необходимости сохранения изменений.

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

Открепляет / прикрепляет правила к дереву данных. Дерево данных сворачивается согласно пути итерации текущего набора. При модификации пути итерации будет происходить автоматическая синхронизация путей правил с путём итерации. Если необходимо временно отключить автоматическую синхронизацию, то с помощью данной функции это можно сделать. При это откреплённое правило будет отображать свой собственный путь итерации соответствующий правилу

Кнопка:

служит для ручной синхронизации итерационного пути дерева с итерационным путём правила.

Меняет местами панель данных и панель правила.

Показывает / скрывает колонку значений по умолчанию.

Добавляет новый набор.

Позволяет задать произвольное имя текущего набора.

Удаляет текущий набор.

Добавление элементов в коллекцию строк правила

Добавить новый элемент в коллекцию можно:

перетащив его из дерева данных в область правила. При этом, если это единичный элемент будет создана одна строка в правиле. Если элемент содержит дочерние элементы и развернут, то в правило будут добавлены строки соответствующие дочерним элементам с типами строка, число, булево. Если элемент не развёрнут, то он добавится в виде одной строки с типом данных JSON, что позволит загрузить всю ветвь в виде строки в ячейку таблицы;
перетащив его из дерева данных в область правила на поле «Путь к элементу» с незаполненым путем. Имя поля таблицы и тип поля останутся без изменения, а путь и тип элемента заполнятся значениями перетаскиваемого элемента;
предварительно выдилив в дереве данных несколько элементов, перетащить их на область правила. Добавится столько строк правила, сколько было выделено элементов типа строка, число, булево;
при отключенной панели данных двойным щелчком на поле с изображением:

открыть область данных и в ней выбрать (двойным щелчком) целевой элемент дерева.