Бизнес-глоссарий¶

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

Этот общий словарь — мост между языком бизнеса и физическими данными. AI-агенту, который знает, что «customer» называет каждую колонку, несущую идентификатор клиента, не приходится угадывать, какая из cust_id, customerId и CUSTOMER_KEY верная — все они разрешаются в один и тот же термин, а термин несёт определение.

Как выводятся термины¶

Provisa выводит термин из каждого имени колонки автоматически, по детерминированному правилу нормализации (REQ-1387): приведение регистра, токенизация по разделителям и camelCase, раскрытие сокращений и отсечение хвостовых прокси-токенов.

Раскрытие сокращений отображает распространённые корпоративные сокращения в их полные формы: cust → customer, txn → transaction, qty → quantity и так далее. И id, и key раскрываются в identifier. Таблица фиксирована и консервативна — неоднозначные сокращения вроде st, min и no остаются как написаны, вместо того чтобы угадать неверно.

Отсечение прокси-токенов убирает хвостовой токен identifier, code, index или reference. Колонка с именем cust_id не называет сам идентификатор; она называет клиента через суррогатное значение. Отсечение прокси приводит и cust_id, и customerId к термину customer. Отсекаются только хвостовые токены и никогда — последний оставшийся: голая колонка id раскрывается в identifier и там и остаётся.

Дедупликация — вот в чём смысл. Правило нормализации детерминировано, поэтому cust_id, customerId и CUSTOMER_KEY все дают customer. Каждая колонка получает ref на единственный итоговый термин, а не три отдельных термина. Тогда у курирования есть одно место, куда добавить определение, а не три.

Обобщённые фразы¶

Некоторые нормализованные фразы слишком обобщённые, чтобы быть понятием сами по себе. Голая колонка name, date или identifier называет атрибут понятия своей таблицы, а не понятие, независимое от этой таблицы. У сотрудников есть имена; у продуктов есть названия; это не одно и то же.

Когда фраза попадает в обобщённый набор и доступен контекст таблицы, термин уточняется до <понятие таблицы> <фраза>: employees.first_name нормализуется в employee first name, а orders.id нормализуется в order, потому что отсечение прокси затем схлопывает уточнённую фразу в понятие, которое она идентифицирует. Этот последний случай важен: первичный ключ orders и любой внешний ключ order_id на других таблицах — все приходят к order, без дополнительного курирования.

Обобщённый набор покрывает атрибутивные существительные (name, date, status, type, amount, quantity), фразы аудиторского следа (created_at, modified_by, submitted_timestamp) и ещё несколько, встречающихся почти в каждой таблице.

Бизнес-имя, а не физическое имя¶

Выведенный термин следует бизнес-имени колонки — её псевдониму, если моделировщик его задал, и физическому имени, если нет (REQ-1581). Когда usr_nm получает псевдоним user name, выведенный термин — user name, а не user number или какое-либо раскрытие usr_nm.

Присвоение псевдонима колонке — более сильная поправка. Псевдоним доходит до каждой поверхности, читающей колонку — SQL, GraphQL, AI-агентов, каталога, — поэтому модель описывает себя корректно везде. Переименование термина чинит одну запись каталога и оставляет колонку читаться как usr_nm для следующего читателя. Баннер предложенного термина в UI говорит об этом прямо: сначала задайте псевдоним колонке; переименовывайте термин только тогда, когда имя колонки верное, а словарь — нет.

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

Имена таблиц как путь доступа¶

Некоторые имена таблиц описывают путь доступа, а не понятие: user_by_name — это пользователь, достигнутый через поиск по имени, а не отдельный вид сущности. Когда Provisa выводит понятие таблицы для уточнения обобщённых фраз, она обрезает имя по связке (REQ-1582). user_by_name становится user; orders_by_customer становится order.

Без обрезки суррогатный ключ на user_by_name нормализовался бы в user name и столкнулся бы с настоящим атрибутом users.name — один термин, держащий и вещь, и одно из её собственных полей. Обрезка применяется только к понятиям таблиц. В имени колонки by — часть составного существительного: pet_by_name и pet_name нормализуются в один и тот же термин, pet name.

Что делает термин курируемым¶

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

Сохранено определение.
Добавлено ребро связи.
Назначен профильный эксперт.
Куратор вручную вывел его из обращения.

Курирование важно для жизненного цикла термина. Когда последняя физическая колонка курируемого термина удаляется из модели, термин не удаляется, а объявляется устаревшим: он выходит из обращения, сохраняет содержимое, внесённое редактором, и автоматически оживает, если та же колонка появится снова. Некурируемый термин без колонок просто удаляется.

Повторная синхронизация с таблицами¶

Каждый раз, когда таблица сохраняется или перезагружается, sync_table_refs сверяет колонки этой таблицы с существующими ref. Новые колонки создают термины или связываются с ними; ушедшие колонки снимают свои ref; а правило «удалить или объявить устаревшим» разрешает судьбу любого термина, потерявшего последний ref.

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

Абстрактный термин, чей единственный путь к физическим данным шёл через уходящий термин, объявляется устаревшим, а не удаляется, — так понятийная структура сохраняется до тех пор, пока её не перекоммутируют.

Связи¶

Термины соотносятся с другими терминами через типизированные рёбра. Поддерживаются такие типы связей:

Тип	Значение
`KIND_OF`	Исходный термин — разновидность целевого термина.
`PART_OF`	Исходный термин — составная часть целевого термина.
`SYNONYM_OF`	Два термина взаимозаменяемы в этой предметной области.
`RELATED_TO`	Свободная ассоциация — более сильное утверждение не подходит.
`VALID_VALUE_OF`	Исходный термин — допустимое значение целевого перечисления или домена.
`DERIVED_FROM`	Исходный термин вычисляется или берётся из целевого.
`REPLACES`	Исходный термин приходит на смену устаревшему целевому.
`PREFERRED_TERM_FOR`	Исходный термин предпочтителен по сравнению с нежелательным целевым.
`TRANSLATION_OF`	Исходный термин — перевод целевого на другой язык или локаль.
`ANTONYM_OF`	Исходный термин — семантическая противоположность целевого.

Связи направленные. UI показывает и исходящие рёбра (этот термин → другой), и входящие рёбра (другой термин → этот), помечая каждое направление собственной формулировкой на обычном языке.

Рёбра хранятся в glossary_term_edges — ассоциативной таблице, объявленной как связь через junction (REQ-1586): её колонка rel_type служит дискриминатором, поэтому каждый из перечисленных выше типов является отдельным типом связи Cypher между двумя узлами GlossaryTerm, а не свойством реифицированного узла. Таблица разворачивается вместе с остальной схемой метаданных и не показывается как узел в графовых клиентах — она и есть ребро. Ничего специфичного для глоссария в ней нет: она объявляется так же, как вы объявили бы junction над своими таблицами, и читается тем же кодом. [tool-verified: provisa/cypher/label_map.py:378-397, provisa/api/startup_seed.py:508-550]

Абстрактные термины¶

У абстрактного термина нет собственных ref на физические колонки. Используйте такой для бизнес- понятия, охватывающего несколько конкретных терминов, — зонтик, который вы затем связываете с конкретными терминами, у которых колонки есть. Например, revenue может быть абстрактным, с рёбрами PART_OF, направленными на него от order amount, adjustment amount и refund amount.

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

Правило допуска для потребляющих поверхностей¶

Термин, который потребляющая поверхность вправе предлагать, должен удовлетворять трём условиям (REQ-1387):

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

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

Экспорт метаданных¶

Глоссарий публикуется во внешние каталоги данных в рамках экспорта метаданных. Действует то же правило допуска с одним сужением: заземлённость термина оценивается только по колонкам, которые действительно публикуются. Термин, все колонки которого удержаны от экспорта — потому что их таблицы не помечены как продукты данных или потому что их исключают технические фильтры, — для целей экспорта не считается заземлённым, даже если он держит ref в плоскости управления.

Рёбра связей публикуются только тогда, когда публикуются оба термина-конца.

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

Исключение термина из экспорта¶

Некоторые колонки несут служебную обвязку, а не бизнес-данные: идентификаторы ETL-пакетов, версии строк, отметки времени загрузки. У термина, выведенного из такой колонки, может быть совершенно точное определение, которое просто не является бизнес-словарём (REQ-1583). Управляющий элемент Exclude from metadata export удерживает термин и любые рёбра связей, оканчивающиеся на нём, от каталогов, куда публикует Provisa, тогда как сами колонки по-прежнему экспортируются как активы.

Проверка в том, говорит ли бизнес это слово, а не в том, хорошо ли определение. У идентификатора ETL-пакета есть ясный смысл, которому место в глоссарии для инженеров; ему не место в бизнес-каталоге рядом с customer и revenue.

Работа с глоссарием¶

Откройте Admin → Glossary в UI. Левая панель перечисляет все термины; щёлкните по одному, чтобы открыть его детальное представление. Оттуда:

Rename — переименовать термин, изменив формулировку, но не перемещая его колонки.
Add a definition — ввести определение или нажать кнопку AI-черновика, чтобы сгенерировать отправную точку из имени термина, его физических колонок и его связей. Черновик не сохраняется, пока вы его не подтвердите.
Move a ref — объединить два термина: выберите целевой термин из выпадающего списка рядом с любым физическим ref. Если исходный термин теряет последний ref, его судьба автоматически решается правилом «удалить или объявить устаревшим».
Add a relationship — добавить связь между этим термином и другим, выбрав тип из закрытого набора. Переназначайте тип существующего ребра на месте, а не удаляйте и добавляйте заново.
Assign experts — назначить экспертов по идентификатору пользователя, с видом expert или author.
Retire — вывести термин из обращения. Он сохраняет свои колонки и остаётся редактируемым здесь, но и поиск терминов агентом, и экспорт метаданных его пропускают. Позже восстановите его, если понятие вернётся.
Bulk-generate definitions — заполнить все пустые определения за один проход. Записываются только пустые определения; человеческий текст никогда не перезаписывается.
Bulk-generate relationships — предложить типизированные рёбра по всему списку терминов. Некорректные предложения — неизвестные имена терминов, петли, нераспознанные типы — отбрасываются автоматически.

Баннер Proposed на термине без определения сообщает вам, является ли термин неопределённым (задайте псевдоним колонке или добавьте определение) или незаземлённым (свяжите его с термином, у которого есть колонки). Когда вы его видите, термин ещё не достижим для агентов или каталогов.

Смотрите также¶

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