Конструктор правил выборки позволяет создавать правила выгрузки данных на основе JSON-образца и просматривать данные в формате 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» — позволяет загрузить JSON данные. После загрузки данные будут доступны для просмотра в Области данных.

• «Кодировка» — позволяет явно указать какую кодировку нужно использовать при выборки данных текстового типа.

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

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

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

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

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

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

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

Состояние выключателя:

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

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

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

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

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

• «Режим отображения дерева данных» — показывать значения: 
• «Сбросить текущий путь итерации» — позволяет сбросить текущий путь итерации в одно действие.

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

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

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

Данные можно просматривать в двух форматах, переключаясь между ними с помощью вкладок в нижней части области:

• Данные (дерево): отображает структуру данных в виде иерархического дерева. Подходит только для просмотра.
• Данные (текст): отображает данные в текстовом формате JSON. Доступно редактирование текста.

В режиме «Данные (дерево)» доступны два варианта отображения: нужен скрин

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

глянуть скрин

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

Описание полей:

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

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

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

Описание полей:

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

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

•   — кнопка позволяет выбрать элемент дерева в качестве точки итерации или отменить выбор элемента в качестве точки итерации. При отмене выбора элемента в качестве точки итерации все нижележащие точки итерации будут также отменены. Чтобы выбрать элемент в качестве точки итерации его необходимо предварительно развернуть. В момент разворачивания будет прочитана структура нижележащих элементов и проведена оценка возможности использования данного узла в качестве точки итерации. Оценка проводится на предмет совпадения типов данных элементов. Типы должны быть одинаковыми и не содержать смешанные типы. Доступна только в режиме просмотра статистики.
•  — кнопка открывает диалог настройки параметров среза точки итерации. Доступна только для настройки параметров среза элемента типа Массив.
•  — кнопка разворачивает узел дерева выбранного в качестве точки итерации для настройки параметров среза. Кнопка функции станет активной. Доступна только в режиме просмотра статистики.
•  — кнопка позволяет посмотреть все значения распределённого элемента. Предварительно нужный элемент необходимо выбрать в дереве данных. Отображается только в режиме просмотра статистики.
•  — кнопка включает и отключает сбор и отображение статистики в режиме просмотра статистики. Если объём данных большой, а посмотреть нужно только структуру дерева, можно использовать эту функцию и отключить сбор статистики. Вернуться к сбору статистики можно в любой момент. Отображается только в режиме просмотра статистики.
•  — поле отображает путь до текущего выбранного элемента дерева.

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

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

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

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

Отображается по правому клику мыши на элементе дерева данных. Функциональность аналогична «Панели функций дерева данных».

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

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

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

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

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

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

Окно просмотра данных в виде текста находится на вкладке «Данные (текст)».

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для добавления нового элемента в коллекцию правил доступны следующие способы:

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