clickstream-data-platform/docs/architecture/dm.md

Слой DM: витрины

Как модель DDS превращается в витрины для потребителя BI: какую форму принимает витрина, кто какие витрины строит и как слой проверяется. Состав колонок каждой витрины задаёт раздел 7 мастер-спеки; здесь — форма, наполнение и контроль.

Форма: по зерну, не по цене запроса

Витрина, меняющая зерно источника — дневной агрегат, сверка по заказам, — материализуется: dm.<имя>_rep / _dist и публичное dm.<имя>_v с явным списком колонок, по общим конвенциям хранилища. Наполняет её dm_transform; ритм и механика пересборки — ниже. Витрина, сохраняющая зерно источника — переименование, обогащение строки, — остаётся обычным представлением: копию событий ради других имён колонок не держит ни один боевой склад.

Правило выбрано учебной целью, а не ценой запроса. На объёмах стенда представлениями обошлось бы всё: условия сквозь цепочку представлений проходят (исследование). Но пересборка агрегатов конвейером — производственный паттерн, ради которого стенд и строится, а пара «таблица рядом с представлением» показывает: форма — решение по роли витрины, у одного слоя законны обе.

Кто строит: стенд и менти

Стенд привозит готовыми витрины трёх сюжетов дашборда этапа 8 и инфраструктуру контроля:

• revenue_daily — выручка по дням и категориям; образец материализованной витрины, на него ссылаются учебные задания;
• purchase_vs_orders — сверка A+C с классами расхождений; зерно — заказ, шардирование сохраняет ко-локацию заказов по cityHash64(order_id);
• daily_traffic — пара «посетители» / «известные пользователи», обогащение картой идентичностей;
• dq_summary — сводка проверок качества (ниже).

Остальные витрины спеки — учебные задания: менти строит их сам по ТЗ с образцом. Разминка — представление events_enriched_v (зерно события), затем агрегаты top_pages_daily, session_overview и dq_errors_daily, последней — самая содержательная utm_effectiveness с уроком declared_*. Построенная витрина встаёт в конвейер руками менти: финальный пункт каждого ТЗ — добавить задачу своей витрины в dm_transform. До этого конвейер о ней не знает и остаётся зелёным, после — витрина пересобирается наравне со стендовыми.

Дашборд этапа 8 стоит только на витринах стенда: приёмка этапа не зависит от выполненных домашек. Расширение дашборда визуализациями по своим витринам — отдельная домашка после этапа 8.

Ритм пересборки

День витрины пересобирается, пока может измениться его источник, — поэтому ритмов три, по числу источников:

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

Поэтому daily_traffic наследует у своего источника и ритм, и механику: полный пересчёт всех дней каждый прогон в ReplacingMergeTree(_load_ts), как у самой карты. Дневных партиций у неё нет: партиция — единица замены, а эта витрина заменяется только целиком. На стенде такая работа остается быстрой; витрина читает сессии и карту через их публичные договоры. Пересчитывать точечно только затронутые дни не из чего: для этого надо знать, какие связки новые, а полный пересчёт карты этот след затирает — восстановление следа оставлено лабе повышенной сложности (issue #149).

У purchase_vs_orders два источника и одна непрерывная пересборка. Заказная сторона задает изменяемое окно последним принятым слепком ODS, событийная — последний прожитый день с purchase. Левая граница возвращает первую дыру и самый ранний день с awaiting_order: предварительная строка уже есть в витрине, поэтому поиск отсутствующего дня ее не заметит. Правая граница доходит до более позднего из двух хвостов. Так один прогон догоняет пакетный разгон длиннее K и не оставляет старое ожидание замороженным.

Витрины стенда

Публичные представления перечисляют деловые колонки и координаты запуска _load_id, _load_ts явно. Новая колонка физической таблицы сама в договор не попадет.

dm.revenue_daily_v

Зерно: день заказа × категория товара. Витрина читает только оплаченные заказы из dds.order_v, синхронно разворачивает три массива позиций и узнает категорию артикула через dic.products. Один заказ с несколькими позициями категории считается в orders один раз. units складывает количество единиц, revenue складывает цену позиции × количество. Скидка, доставка и итог заказа между категориями не делятся. aov равен revenue / orders в том же срезе и хранит два знака после запятой.

Первый запуск строит всю доступную историю. Следующие берут границы дней из последнего слепка ODS: только источник знает, какие даты еще может изменить. Пропущенный оплаченный день расширяет левую границу, чтобы частичный отказ не оставил дыру после следующего прогона. Агрегат при этом читает DDS; ODS отвечает только на вопрос об объеме.

dm.revenue_daily_rep нарезана по report_date; день собирается в таблице-доноре и заменяется через REPLACE PARTITION. Цель и донор шардируются по cityHash64(product_category). Кроме дня, у витрины только категория, а шесть категорий стартового мира близки по объему. Более сложный составной ключ распределил бы эту маленькую таблицу без нового урока.

dm.purchase_vs_orders_v

Зерно — заказ. Покупки из dds.event_v сначала сворачиваются по purchase_id[1]: контракт источника обещает один номер и одну объявленную сумму, а отдельный счет событий оставляет будущий класс duplicate_event наблюдаемым. Заказы приходят из dds.order_v. Обе стороны записаны подзапросами, затем соединены FULL OUTER GLOBAL JOIN: голая левая Distributed-таблица вернула бы каждый непарный заказ по разу с каждого шарда (исследование).

Непарная сторона остается NULL благодаря join_use_nulls = 1. При join_use_nulls = 0 ClickHouse заполнил бы ее нулем или пустой строкой и скрыл отсутствие источника. Клиентская declared_revenue и серверная items_total сравниваются как Decimal(18, 2). Классы проверяются по порядку: awaiting_order для покупки без заказа, затем cancelled, lost_event, duplicate_event, amount_delta, match. Поэтому отмененный заказ без события остается отмененным, а не потерянным.

Витрина нарезана по order_day, цель и донор шардируются по cityHash64(order_id). Диапазон собирается в доноре одной вставкой и заменяется по дням. Первичная сборка охватывает всю историю обоих источников; следующие прогоны идут по двустороннему ритму, описанному выше.

dm.daily_traffic_v

В строке один день. visitors считает разные client_id из dds.session_v; known_users считает разные user_id после левого соединения с полной текущей dds.identity_map_v. Анонимная сессия остается в витрине. Несколько кук одного человека увеличивают visitors, но дают одного known_user, поэтому known_users <= visitors.

Сессии и карта лежат по client_id, но публичные _v скрывают Distributed-таблицы от локальной подстановки. На ClickHouse 26.3 EXPLAIN PLAN показал чтение обоих шардов на инициаторе: настройка distributed_product_mode = 'local' локального соединения не дала. Поэтому витрина использует явный GLOBAL LEFT JOIN через публичные договоры, а не подменяет их физическими таблицами. Это дороже по сети, зато граница слоев остается явной. Новая связь куки меняет прошлые дни, поэтому каждый запуск пишет полную историю новой версией в ReplacingMergeTree(_load_ts), а публичное представление выбирает текущие строки через FINAL.

dm.dq_summary

Зерно — «день данных × проверка»: строка отвечает, каково качество дня сейчас, а не сколько раз его проверяли, — история прогонов и так живёт в Airflow. Партиция — день данных; прогон звена DQ заменяет партиции проверенных дней через REPLACE PARTITION. Обещанный спекой перевод с TRUNCATE+INSERT выполняется той же механикой замены, что и у витрин, — ничего отдельного учить не надо.

Звено DQ конвейера

Встаёт в etl_pipeline после DM (конвейер) и проверяет только объекты стенда:

• счётная сверка сессий с эталоном VisitID — кука × день, эталон читается из ods.event_v (модель сессии);
• счётчики классов расхождений против описи мира — по дням с закрытым окном. Проверка техническая, не урок DQ: её оракул — опись генератора, а у настоящего магазина оракула нет. Обещание узкое и честное: до витрин доехал тот мир, который родился, — одна растяжка через весь путь вместо сторожей на каждом шаге. Верно ли сам мир рождён, она не видит: опись считает тот же генератор;
• счётные сверки витрин стенда с их DDS-источниками.

Результаты ложатся в dm.dq_summary. Звено — не только сторож конвейера, но и экспонат: менти видит, как контроль качества устроен в бою — по расписанию, с историей, рядом с трансформациями.

Даг самопроверки

Домашки контролирует отдельный даг без расписания: менти запускает его рукой. Задача витрины красная, пока витрины нет или счёт не сходится, и зелёная, когда построено верно; сообщение об ошибке говорит, что не так и куда смотреть. Проверки — инварианты против DDS-источников, золотые константы не прибиваются. В dq_summary даг не пишет: он инструмент лабы, а не история качества конвейера.

Приём проверен на соседнем учебном стенде Airflow + Greenplum: валидационный даг с группами проверок по слоям давал менти обратную связь по каждому шагу домашки, не трогая рабочий конвейер.

Остаётся нарезке

• Имена звена DQ и дага самопроверки.
• Ключи шардирования остальных материализованных витрин — вместе с их DDL; правило партиции-донора — в доке хранилища.
• Тексты учебных заданий и точный список проверок обоих контуров.

Отклонённые варианты

• Весь слой представлениями. Дёшево и всегда свежо, но главный производственный паттерн слоя — пересборка агрегатов — остался бы невидим, а dm_transform — без работы.
• Материализовать всё. Копия событий ради переименования колонок — антипаттерн, который менти увёз бы в бой.
• Гибрид по цене запроса. Выбор формы по стоимости, которой на объёмах стенда нет: сторож без настоящей опасности.
• Проверки домашек в конвейерном звене DQ. Конвейер стоял бы красным до выполнения лаб, а проверка, которая всегда красная, приучает себя игнорировать.
• «Жёлтый» статус недостроенной витрины. У задачи Airflow нет такого состояния; изображать его логами — семантика, которую пришлось бы расшифровывать. Красное «ещё не построено» честнее.
• Самопроверка пишет в dq_summary. Попытки менти смешались бы с историей качества конвейера.
• Окно заказов для daily_traffic — прошлое замерзает. Дни за окном хранили бы число известных на момент закрытия — витрина тихо расходится с картой и протаскивает обратно «знание на дату», отвергнутое развилкой карты (#133).
• Инкрементальный пересчёт затронутых дней по first_matched_at. Производственный ход, но на объёмах стенда его экономия неизмерима, а след новых связок требует вернуть колонку, выкинутую в #133. Стал лабой повышенной сложности — issue #149.
• Superset поверх DDS без слоя DM. Терялся бы урок «витрина — контракт под потребителя», против раздела 7 спеки.

Связанные решения

• Мастер-спека, разделы 4 и 7, — состав колонок витрин и классы сверки.
• Дневной конвейер — запуск dm_transform, объём прогона, замена партиций на кластере.
• Дока хранилища — имена объектов, конвенция чтения через _v, партиция-донор.
• Карта модели DDS — источники витрин.
• Резолюция — тикет #135 карты #127.