Справочник
Описание набора данных
Формат holkas-dataset/1 с читаемым примером JSON. Корень и части, составные ключи, граница строк, вложенные ссылки, проверки и отличие описания от снимка данных.
На этой странице
Что описывает этот JSON
holkas-dataset/1 задаёт какие строки считать одним переносимым набором: корневую таблицу, её ключ и границу, подчинённые таблицы и ссылки. Описание используется при чтении базы; оно само не содержит ни строк, ни команд применения.
Начать с интерфейса можно по переносу словаря статусов. Правила сравнения, удаления и порядка команд разобраны в справочнике DAT. Здесь — точный формат для чтения, редактирования и передачи описания через манифест, описатель, CLI или API.
Минимальное описание
В примере ниже выбран только корень EXTRA_DICTS: один словарь с кодом HKSITE_STATUS. Это корректное по структуре описание, но без его значений в подчинённой таблице. В полном скачиваемом файле часть EXTRA_DICTS_VALUES уже добавлена.
{
"format": "holkas-dataset/1",
"name": "Статусы согласования",
"root": {
"table": "EXTRA_DICTS",
"key": ["CODE"],
"where": { "keys": [["HKSITE_STATUS"]] }
},
"prune": false
}
JSON использует camelCase; таблицы и колонки называются заглавными буквами, без схемы и внешних пробелов. Схема — PARUS. Имена набора и значения ключей остаются такими, как они заданы; их не нужно переводить в верхний регистр.
Верхний уровень
| Поле | Тип | Правило |
|---|---|---|
format | Строка | Обязательно holkas-dataset/1. |
name | Строка | Непустое имя без символа |. Должно точно совпадать с именем объекта DAT, с которым передаётся описание. |
root | Объект таблицы | Обязателен. Определяет корень набора. |
prune | Логическое значение | По умолчанию false. При true лишние корни внутри границы могут получить удаление. |
Таблица: root и элементы parts
| Поле | Тип | Правило |
|---|---|---|
table | Строка | Имя таблицы. Одна таблица не может повторяться в дереве одного набора. |
key | Массив строк | Колонки ключа в заданном порядке. У корня обязателен непустой список; у части допустим пустой, с особым правилом сопоставления ниже. |
by | Строка | Только у части: колонка, ссылающаяся на RN непосредственного родителя. У корня её нет. |
where | Объект | Только у корня, обязателен: ровно один из all, folder, keys. |
unit | Строка | Только у корня таблицы, при необходимости: код раздела Паруса UNITLIST.UNITCODE, когда его нельзя определить однозначно. У ссылок есть собственный необязательный unit, описанный ниже. |
refs | Массив объектов | Описания колонок-ссылок. Если поле отсутствует, читается как пустой список. |
parts | Массив объектов таблицы | Подчинённые таблицы. Если поле отсутствует, читается как пустой список. Части могут иметь свои части. |
Колонки RN, COMPANY, VERSION, CRN не перечисляют в ключах и ссылках. Колонка родителя by тоже не входит в ключ своей части и её refs. Полного списка колонок для переноса в описании нет: их состав и типы Holkas читает из каталога базы.
Граница корневых строк
Одна таблица — три разные границы
{ "keys": [["HKSITE_STATUS"]] }| CODE | Папка | В наборе |
|---|---|---|
HKSITE_STATUS | Согласование договоров | Да |
HKSITE_KIND | Согласование договоров | Нет |
OTHER | Общие | Нет |
Один словарь по его CODE. Строки его частей тоже войдут в набор, если эти части описаны в parts.
{ "folder": "Согласование договоров" }| CODE | Папка | В наборе |
|---|---|---|
HKSITE_STATUS | Согласование договоров | Да |
HKSITE_KIND | Согласование договоров | Да |
OTHER | Общие | Нет |
Оба словаря этой папки. Папка выбирается по имени; это не путь и не рекурсивный обход дерева папок.
{ "all": true }| CODE | Папка | В наборе |
|---|---|---|
HKSITE_STATUS | Согласование договоров | Да |
HKSITE_KIND | Согласование договоров | Да |
OTHER | Общие | Да |
Все корневые строки в выбранной организации и версии раздела. Это граница, которую предлагает черновик конструктора; её нужно проверить перед переносом.
У root.where должен быть ровно один вид границы:
| Вид | Запись | Ограничения |
|---|---|---|
| Все строки | {"all": true} | false не задаёт границу. Организация и версия раздела по-прежнему ограничивают чтение. |
| Папка | {"folder": "Согласование договоров"} | Непустое имя папки, не RN и не путь. Таблице нужна колонка CRN. Выбираются строки подходящей папки по имени, не всё поддерево. |
| Ключи | {"keys": [["HKSITE_STATUS"]]} | Непустой список. Каждая внутренняя строка содержит столько значений, сколько колонок в root.key. Значения передаются строками. |
Внутри keys внешний массив — альтернативы, внутренний — один полный ключ. Для условного ключа CODE + KIND два варианта выглядят так:
{
"key": ["CODE", "KIND"],
"where": {
"keys": [
["STATUS", "1"],
["STATUS", "2"]
]
}
}
Это фрагмент таблицы, не полное описание. "1" — строка в JSON; значение преобразуется с учётом типа колонки базы. Порядок соответствует key: поменяв колонки местами, нужно так же переставить значения. Произвольный SQL, LIKE или логические выражения в where не поддерживаются.
Ключ и части
Ключ обозначает тождество строки между базами. У корня он уникален в таблице с учётом служебной области; у части — внутри родителя. Проверка по базе ищет подходящее уникальное ограничение или индекс. RN источника для сопоставления не используется.
Часть связывается с родителем через by. В полном учебном описании внутри root.parts находится:
{
"table": "EXTRA_DICTS_VALUES",
"by": "PRN",
"key": [],
"refs": [],
"parts": []
}
Здесь PRN указывает на корневой словарь. У части нет собственного where: читаются строки, принадлежащие отобранным родителям. Проверка подтверждает наличие внешнего ключа к таблице родителя. Конструктор предлагает части по ON DELETE CASCADE; окончательный состав описания всё равно выбираете вы.
Пустой ключ части — значимое решение. Тогда идентичность строится по её строкам, числам и датам — без ссылок-адресов, длинного текста и байтов: по ним Holkas не может найти строку в приёмнике. Изменение строки, числа или даты может выглядеть как удаление старой строки и создание новой вместо Update; изменение длинного текста или байтов — обычный Update. Если две строки одного родителя дают одинаковую идентичность — в том числе когда они различаются только длинным текстом или байтами, — чтение останавливается с dataset_duplicate_row ещё до плана. У корня такой режим запрещён — нужен явный непустой ключ.
При наличии устойчивого бизнес-ключа части лучше описать его явно и проверить уникальность. Не подставляйте имя колонки по догадке: учебная таблица и ваш справочник могут иметь разные ограничения.
Как описать ссылку
refs нужен для обычной колонки, которая хранит RN другой строки. Вместо номера из источника переносится адрес цели по её ключу. Системные колонки и by обрабатываются отдельно.
| Поле ссылки | Тип | Назначение |
|---|---|---|
column | Строка | Колонка-ссылка в текущей таблице. Не может быть описана дважды. |
table | Строка | Таблица, на строку которой указывает ссылка. |
key | Непустой массив строк | Колонки ключа строки-цели в порядке значений адреса. |
unit | Строка, необязательная | Для внешней цели: раздел Паруса, определяющий её версию, если его нельзя вывести однозначно. У ссылки на каталог ACATALOG не нужен: деление строки каталога определяет раздел из её DOCNAME. |
refs | Массив, необязательный | Для внешней цели: описание тех колонок её ключа, которые сами хранят RN. Вложение продолжается до обычных значений. |
Условный пример одного элемента refs: колонка STATUS_RN указывает на статус, который определяется кодом CODE:
{
"column": "STATUS_RN",
"table": "DEMO_STATUS",
"key": ["CODE"]
}
DEMO_STATUS — вымышленная таблица для объяснения синтаксиса. Пример не утверждает её наличие в вашей базе. Ссылка на таблицу вне набора не добавляет её строки автоматически: они должны уже существовать в приёмнике или переноситься согласованным набором в том же плане.
Если ключ цели тоже содержит ссылку
Предположим, статус уникален по справочнику DICTIONARY_RN и своему CODE. Номер справочника между базами различается, поэтому он тоже должен быть раскрыт в адрес. Вложенный refs относится именно к колонке ключа цели:
{
"column": "STATUS_RN",
"table": "DEMO_STATUS",
"key": ["DICTIONARY_RN", "CODE"],
"refs": [
{
"column": "DICTIONARY_RN",
"table": "DEMO_DICTIONARY",
"key": ["CODE"]
}
]
}
Человеческий смысл адреса: «статус NEW в справочнике CONTRACTS», а не «строка RN = 12345». Пример условный; структура проверяется без базы, реальные ключи и колонки — по каталогу вашего источника.
Внутренняя ссылка — когда table цели уже есть в root или любой части этого набора. Для неё используют ключ, согласованный с описанием цели; дополнительные refs и unit у такой ссылки не задают. Адрес строится по дереву самого набора. Внутренняя колонка-ссылка должна допускать пустое значение: она проставляется отдельной командой после создания нужных строк.
Цикл ссылок сам по себе и цикл в ключах адреса — разные вещи. Если адрес нельзя развернуть до обычных значений, описание будет отклонено. Подробнее о командах DAT.Row и DAT.Ref — Ссылки и порядок.
Что меняет prune
prune: false сохраняет лишние корневые строки в приёмнике. prune: true разрешает удалить корни, которых нет в источнике внутри заданной границы. Строки за границей не входят в это сравнение.
Этот флаг не отключает удаление лишних частей совпавшего родителя. Поэтому даже при false в плане могут быть удаления. Наглядный разбор — Что удаляется и что сохраняется.
Куда передавать описание
| Место | Форма |
|---|---|
| Отдельный файл из этой статьи | Читаемый JSON-объект описания. Это материал для конструктора или клиента, не ZIP и не файл манифеста состава. |
| Строка манифеста или ответ описателя | parameter — строка с JSON. Имя строки совпадает с name внутри описания. |
Объект DAT в REST или MCP | definition — строка с JSON. Например, клиент сериализует объект описания перед отправкой. |
Файл объектов CLI, переданный через --objects | definition может быть JSON-объектом или строкой с JSON. |
JSON объекта DAT внутри ZIP | definition — вложенный объект; рядом находится массив rows со снимком строк. |
Не переносите форму аргумента из одного интерфейса в другой механически. Штатные инструменты MCP и REST умеют строить черновик, проверять описание и показывать первые строки.
Описание и снимок строк
Когда Holkas прочитал набор и сохраняет его в пакет, объект DAT содержит две части:
| Поле | Содержимое |
|---|---|
definition | Описанное выше устройство набора holkas-dataset/1. |
rows | Плоский список прочитанных строк. Родитель записан перед своими частями. |
Отдельное описание не заменяет этот файл: в нём ещё нет данных. И наоборот, DataSet/Имя.json из ZIP не нужно передавать целиком в parameter манифеста.
Одна запись rows
| Поле | Значение |
|---|---|
table | Имя таблицы строки. |
segment | Служебное представление ключа строки. У части включает сегмент родителя и имя таблицы. Формируется Holkas; не является RN. |
parent | Сегмент родителя для строки части; у корня отсутствует. |
folder | Имя папки корня, если оно есть. При переносе используется имя, а не CRN источника. |
folderPath | Путь к этой папке: массив имён папок от первого уровня под корнем каталога раздела до folder включительно, например ["Решение", "Статусы"]. Корень раздела не входит; [] — строка лежит прямо в корне. Поля нет у частей и в наборах прежних версий Holkas. В базе приёмника по пути создаются недостающие папки; уже существующая папка с таким именем используется там, где лежит. |
cells | Массив ячеек { "column": …, "value": … }, не словарь колонок. |
В cells нет RN, COMPANY, VERSION, CRN и колонки by. Отсутствующие значения при чтении не записываются как ячейки. Пустая строка нормализуется в отсутствие значения, чтобы учитывать поведение Oracle.
value.kind | Поле значения | Представление |
|---|---|---|
s | s | Строка. |
t | s | Длинный текст; поле тоже называется s. |
n | n | JSON-число. |
d | d | Дата-время без часового пояса и долей секунды, например 2026-10-20T12:30:00. |
b | b | Строка base64 для двоичных данных. |
a | a | Массив значений адреса; элементы могут сами быть адресами. |
Сокращённый условный пример строки корня с ключом CODE:
{
"table": "EXTRA_DICTS",
"segment": "HKSITE_STATUS",
"cells": [
{ "column": "CODE", "value": { "kind": "s", "s": "HKSITE_STATUS" } },
{ "column": "NAME", "value": { "kind": "s", "s": "Статусы согласования" } }
]
}
Для составного ключа сегмент соединяет значения служебным разделителем U+001F; специальные символы экранируются. Это формат сохранённого снимка, а не поле, которое нужно заполнять при создании описания. Ключи команд и адреса строк следует брать из результата Holkas, а не собирать вручную.
Как проверить описание
Проверка состоит из трёх шагов, каждый отвечает на свой вопрос:
- Структура JSON: известная метка формата, имя, таблицы, ключи, единственная граница, согласованность вложенных частей и ссылок.
- Каталог живой базы: существуют ли таблицы и колонки, уникален ли ключ, описаны ли RN-ссылки, поддерживаются ли типы колонок, разрешается ли раздел.
- Просмотр и план: сколько строк выбрано, какие значения прочитаны, что будет создано, изменено или удалено в конкретном приёмнике.
Правильный JSON не доказывает наличие нужной таблицы, а успешная проверка описания не доказывает наличие всех целей ссылок в приёмнике. Просмотрите границу, затем план. Предпросмотр показывает корневые строки; это не выгрузка всех частей. Больше 10 000 корневых строк вызывает предупреждение о слишком широком наборе.
Частые отказы
| Код | Что проверить |
|---|---|
dataset_format | JSON, метку holkas-dataset/1 и наличие root. |
dataset_name | Непустое имя без | и совпадение с именем объекта DAT. |
dataset_where | Ровно один вид границы, непустые ключи/папку, длину каждого ключа. У части where быть не должно. |
dataset_key | Непустой ключ корня; системные колонки и by в ключ не входят. |
dataset_table, dataset_table_duplicate | Канонические имена таблиц и отсутствие повторов в дереве набора. |
dataset_table_missing, dataset_column_missing | Реальные таблицы и колонки источника. |
dataset_key_not_unique | Уникальное ограничение или индекс с выбранными колонками и областью. |
dataset_by | Связь части с непосредственным родителем. |
dataset_ref_missing | Все обычные колонки с RN-ссылками должны быть описаны. |
dataset_ref, dataset_ref_key, dataset_ref_system, dataset_ref_duplicate | Поля и ключи ссылок, отсутствие системных колонок и дублей. |
dataset_address_unresolved | Все RN-колонки ключа внешней цели раскрыты вложенными refs. |
dataset_address_cycle | Замыкается ли цепочка адреса на обычных значениях ключей. |
dataset_ref_not_null | Внутренняя колонка-ссылка должна допускать пустое значение. |
dataset_catalog_key | В ключе ссылки на каталог ACATALOG нет DOCNAME: строка каталога делится так же, как раздел из этой колонки. |
dataset_unit, dataset_unit_ambiguous, dataset_unit_conflict | Наличие раздела, его однозначность и согласованность unit у ссылок. |
dataset_column_type | Поддерживается ли тип колонки. |
dataset_duplicate_row | Не дают ли две прочитанные строки один и тот же ключ. |
Это основные диагностические коды, не перечень всех возможных отказов базы. У находки проверки есть текст, таблица, при необходимости колонка и isError: false означает предупреждение. При применении дополнительно действуют ограничения и триггеры Паруса.
Связанные форматы: пакет со снимком объектов и манифест состава с parameter набора.