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

1. Governance¶

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

Каждый ресурс должен принадлежать домену. Таблицы, представления и связи — всё это ресурсы домена. Неуправляемых «плавающих» ресурсов не существует. Домен — единица подотчётности.
У каждого домена должен быть куратор (steward). Домен может существовать в состоянии ожидания, пока куратор не назначен, но он не может обслуживать управляемые данные без него.
Администратор владеет источниками. Источники — это инфраструктура, а не ресурсы домена. Администратор регистрирует подключения к внешним системам данных и управляет ими.
Кураторы могут заявлять таблицы для домена. Заявка (claiming) эксклюзивна — таблица принадлежит ровно одному домену. Это управляемый акт, соединяющий инфраструктуру и семантический слой.
Кураторы могут создавать внутридоменные представления из ресурсов домена. Представления выражают бизнес-логику — соединения, агрегации, производные метрики — над ресурсами, которыми куратор владеет в рамках того же домена. Представления создают новый семантический смысл и требуют одобрения куратора.
Аналитики могут создавать междоменные запросы из одобренных связей. Запросы — это междоменные представления, выраженные на любом поддерживаемом языке запросов. Они не создают новую семантику — они проходят по одобренным путям связей. Дополнительное одобрение не требуется: 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 discovery, со страницы Relationships):

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

Этап 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 дней, только активные контрагенты, с отображением юридического названия контрагента и кредитного рейтинга. Без PII.»

Процесс LLM:

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

Выход:

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

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

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

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

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

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

3. Использование¶

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

Каждый запрос, затрагивающий ресурс домена, записывается в журнал только для добавления 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 — история запросов для паттернов использования во время выполнения