Принципы доменной модели¶

1. Governance¶

Базовые принципы¶

Каждый ресурс должен принадлежать домену. Таблицы, представления и связи — всё это ресурсы домена. Неуправляемых «плавающих» ресурсов не существует. Домен — единица подотчётности.
У каждого домена должен быть стюард. Домен может существовать в состоянии ожидания, пока стюард не назначен, но он не может обслуживать управляемые данные без него.
Администратор владеет источниками. Источники — это инфраструктура, а не ресурсы домена. Администратор регистрирует и управляет подключениями к внешним системам данных.
Стюарды могут закреплять таблицы за доменом. Закрепление исключительно: таблица принадлежит ровно одному домену. Закрепление — это управляемое действие, которое связывает инфраструктуру с моделью.
Стюарды могут создавать внутридоменные представления из активов домена. Представления выражают бизнес-логику, например соединения, агрегаты и производные метрики, над активами, которыми стюард владеет в том же домене. Представление создаёт новый смысл и требует одобрения стюарда.
Аналитики могут создавать междоменные запросы по одобренным связям. Запросы — это междоменные представления на любом поддерживаемом языке запросов. Они не создают нового смысла; они проходят по одобренным путям связей. Дополнительного одобрения не нужно, потому что управление действует раньше, на уровнях связей и видимости столбцов. Принуждает каталог: компилятор отклоняет любой обход, которого нет в каталоге одобренных связей.
Любой может запросить доступ к ресурсу домена. Доступ выдаётся на ресурс, а не на запрос: если у вас есть доступ к ресурсу, вы можете его запрашивать. Управление применяется во время выполнения в конвейере.

Ресурсы: таблицы и представления как равноправные сущности¶

Таблица и представление различаются только происхождением: таблица закрепляется из источника, а представление определяет стюард. Как только любое из них становится активом домена, модель управления обращается с ними одинаково:

Обе являются полноценными ресурсами домена, видимыми в каталоге
Обе могут быть целью связи
Обе могут предоставляться по Принципу 6
Обе подчиняются одному и тому же конвейеру governance

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

Композиция представлений¶

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

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

Представление может ссылаться на:

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

Глубину вложенности представлений ничто технически не ограничивает. Контроль качества — это суждение стюарда при проверке HITL.

Каждое представление несёт заявленное бизнес-назначение, указанное при создании:

Часть управляемого артефакта, поэтому стюарды одобряют, зная, для чего предназначено представление
На него ссылаются запросы доступа по Принципу 7, чтобы стюард мог оценить соответствие
Сопровождает представление на всём пути процесса governance от создания

Запросы¶

Запрос проходит по одобренным путям связей над активами домена. В отличие от представления, он не создаёт нового смысла; он следует одобренной структуре модели. Запрос можно написать на любом поддерживаемом языке запросов (SQL, GraphQL, Cypher).

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

Одобрение не нужно: Управление действует раньше, на уровнях связей и видимости столбцов. Если пользователю видны столбцы и путь обхода одобрен, запрос — допустимое использование, без дополнительных барьеров.

Отличие от представлений:

Представления: внутридоменные, вносят новый семантический смысл, курируются стюардом
Запросы: проходят по одобренным связям, не создают новую семантику, без контроля одобрения

Выражение домена по языку запросов:

Каждый поддерживаемый язык представляет домен как структурное пространство имён, естественное для этого языка:

Язык	Выражение домена	Пример
GraphQL	Префикс имени типа и поля	`type sales__Order { ... }`, `query { sales__orders { ... } }`
SQL	Имя схемы	`SELECT * FROM sales.orders`
Cypher	Дополнительная метка узла (домен требуется только когда имя типа неоднозначно)	`MATCH (o:Sales:Order)`

Компилятор определяет принадлежность к домену по этим структурным позициям, поэтому аннотации и подсказки не нужны.

Связи¶

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

Одобрение:

Запрос на связь решают домены, которых он касается: домен его исходной таблицы и домен его целевой таблицы
Одобрение засчитывается, только если оно исходит от пользователя, чьё право создавать связи достигает одного из этих доменов; отклонить его может любой такой пользователь
Запрос выполняется, когда его одобрили два разных пользователя, ни один из которых не является автором запроса, и у каждого затронутого домена есть одобряющий: связи между двумя доменами нужно «да» с каждой стороны, а связи внутри одного домена — два одобряющих этого домена
Одобрение связи выстраивает граф зависимостей каждого стюарда, поэтому стюарды узнают об изменениях схемы до того, как они вступят в силу

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

Следствие для оптимизации: Объявление связи — это артефакт управления и одновременно структурное описание формы соединения. Две таблицы, два столбца и тип соединения, которые определяют связь, — ровно то, что нужно оптимизатору запросов, чтобы заранее материализовать это соединение. Межисточниковые связи автоматически получают заранее материализованные таблицы соединений, а связи внутри одного источника могут включить это через materialize: true. Стюарды, которые продумывают и одобряют корректные связи, получают более быстрые запросы как прямое следствие: работа по управлению и работа по оптимизации — одно и то же действие.

Гранты доступа к полям¶

Разрешение на доступ к полям — это разрешение от одного домена другому: домен A может использовать определённые поля домена B в своих представлениях.

Жизненный цикл гранта:

Инициируется созданием представления, когда выявляется потребность во внешних полях
Одобряется один раз стюардом целевого домена
Принадлежит запрашивающему домену, а не представлению, которое его инициировало
Любое последующее представление в запрашивающем домене может использовать предоставленные поля без дальнейшего кросс-доменного участия
Дополнительные негрантованные поля требуют нового запроса

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

Видимость — осведомлённость о том, как используются его данные
Надзор — основания для беспокойства, если использование выглядит неуместным
Средство защиты — возможность отозвать грант, аннулировав зависимые представления

Компромисс: домен-источник одобряет доступ к полям, не зная о каждом будущем использовании. Одобрение на уровне каждого представления корректно в теории, но неработоспособно на практике.

Рабочий процесс создания запроса¶

Три этапа, по порядку.

Этап 1 — Формирование (SQL-исследование, со страницы Relationships):

Аналитик открывает инструмент формирования со страницы Relationships чтобы опробовать пути соединения в необработанном SQL
SQL выполняется над доступными данными, с учётом существующих RLS и маскирования колонок
JOIN-ы в SQL разбираются и представляются в виде кандидатных предложений связей
Кандидаты, предложенные машиной (вывод по FK, семантический вывод), показываются вместе с SQL аналитика в одном и том же представлении
Аналитик выбирает кандидатов для продвижения в формальный запрос на связь

Этап 2 — Одобрение связи (значимо — структурно и постоянно):

Решают домены, которых касается связь, как описано в разделе Связи
Это законный путь обхода? Семантически ли корректно соединение?
Одобрить должны два разных пользователя, ни один из которых не является автором запроса, и у каждого затронутого домена должен быть одобряющий; после этого связь становится постоянной записью каталога

Этап 3 — Создание запроса:

Аналитик строит запрос на любом поддерживаемом языке (SQL, GraphQL, Cypher), проходя по одобренным путям связей
Обходить можно только одобренные связи каталога, и компилятор обеспечивает это структурно
Одобрение не требуется: единственные контрольные точки: видимость колонок и одобрение связи

HITL как основной механизм контроля¶

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

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

Высокая степень рассмотрения при принятии решения о пересечении границы
Лёгкая осведомлённость впоследствии — через уведомления и историю запросов

2. Discoverability¶

Уровни обнаружения¶

Обнаружение структурировано по пяти уровням возрастающего governance. Каждый уровень — предпосылка для следующего.

Уровень	Описание	Состояние governance
1 — Зарегистрированная схема источника	Каждая таблица, колонка и тип из зарегистрированного источника. Видимость на уровне администратора.	Отсутствует — необработанная инвентаризация
2 — Незакреплённые таблицы	Таблицы, интроспектированные из зарегистрированных источников, без владельца-домена. Видны стюардам с доступом к источнику.	Доступно, но не управляется
3 — Ресурсы домена	Закреплённые таблицы и представления, определённые стюардом. Полностью управляемые, принадлежащие домену, видимые в каталоге.	Полностью управляется
4 — Связи	Одобренные пути обхода между ресурсами уровня 3. Предпосылка для создания кросс-доменных представлений.	Одобрено обоими стюардами
5 — Гранты на поля	Разрешения доступа к полям домен-домен. Наиболее конкретный и целенаправленный вид управляемого доступа.	Одобрено стюардом-источником

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

Ограничения FK¶

Ограничения FK принадлежат одному источнику, поэтому не могут охватывать несколько. Пути соединения между источниками берутся целиком из одобренных связей каталога (уровень 4), а это более сильное свидетельство, потому что их проверили оба стюарда.

Внутри источника:

Ограничения FK автоматически выявляются как кандидатные связи при регистрации источника
Они отражают явное намерение моделирования: неприменяемое в большинстве аналитических SQL-систем, но целенаправленно объявленное
Проверка стюардом по-прежнему требуется, прежде чем кандидат станет одобренной связью

Иерархия достоверности связей¶

Свидетельство	Достоверность
Одобренная связь каталога — кросс-исходная, проверена обоими стюардами	Наивысшая
Ограничение FK внутри источника — явное намерение моделирования, неприменяемое, но целенаправленное	Высокая
Семантический вывод внутри источника — сходство имени/типа колонки в рамках согласованной схемы	Средняя
Семантический вывод между источниками — соглашения об именовании расходятся между системами; высокий риск ложных срабатываний	Низкая

Предложения, подтверждённые несколькими типами свидетельств, накапливают достоверность.

Зондирование и корреляция данных¶

Для семантически выведенных кандидатов зондирование данных предоставляет этап проверки:

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

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

Обнаружение с помощью LLM¶

LLM работает одновременно на всех пяти уровнях, предлагая связи, кандидатов на закрепление и пути обхода, ранжированные по достоверности.

Что предлагает LLM:

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

Проектирование представления по бизнес-описанию:

Аналитик предоставляет описание на естественном языке и необязательные ограничения. LLM формирует предлагаемую структуру представления.

Вход:

Бизнес-описание: сущности, метрики, связи, намерение
Необязательные ограничения: фильтры, временные окна, агрегации, исключённые поля, ограничения по чувствительности

Пример:

«Ежедневные объёмы торгов по контрагентам за последние 30 дней, только активные контрагенты, с указанием юридического наименования контрагента и кредитного рейтинга. Без ПДн.»

Процесс LLM:

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

Выход:

Черновик запроса для проверки и доработки аналитиком
Оценки достоверности по каждому компоненту
Упорядоченный список предпосылок
Список пробелов

Бизнес-описание становится заявленным бизнес-назначением представления, как только представление формально создано.

SQL-first обнаружение связей (инструмент Modeling):

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

Аналитик пишет произвольный SQL по доступным таблицам (RLS и маскирование по-прежнему применяются)
AST SQL разбирается, и каждое условие JOIN становится кандидатным предложением связи
Список кандидатов показывается вместе с предложенными машиной кандидатами (вывод по FK, семантический вывод) для единой проверки
Аналитик продвигает выбранных кандидатов в формальные запросы на связь
Одобренные связи добавляются в каталог и становятся проходимыми в запросах

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

3. Usage¶

Журнал аудита запросов¶

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

tenant_id, user_id, role_id — контекст идентичности
Хеш SHA-256 запроса; дословный текст запроса никогда не сохраняется
table_ids — ресурсы домена, которые затронул запрос
source, status_code, duration_ms
logged_at — временная метка

Журнал доступен только для добавления (DELETE и UPDATE блокируются на уровне базы данных) и индексируется по (tenant_id, logged_at) и (user_id, logged_at).

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

Два механизма видимости:

Push — уведомления постфактум о структурных действиях (с использованием ваших полей было создано новое представление)
Pull — история запросов для паттернов использования во время выполнения