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

1. Governance¶

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

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

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

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

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

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

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

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

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

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

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

Глубина композиции технически не ограничивается — суждение стюарда при HITL-проверке является механизмом контроля качества.

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

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

Запросы¶

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

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

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

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

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

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

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

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

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

Связи¶

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

Одобрение:

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

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

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

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

Грант доступа к полям — это разрешение домен-домен: домен 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, стюард должен закрепить её, прежде чем governance сможет продолжиться. Отсутствие любого кандидата на всех уровнях требует эскалации к администратору.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вход:

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

Пример:

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

Процесс LLM:

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

Выход:

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

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

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

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

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

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

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).

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

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

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