docs(handbook): упрощен язык путеводителя

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

Что: уточнены заголовки и объяснения в пяти главах и вводной, добавлена
сверка графика с SQL, обновлены ссылки из заданий и документации генератора.

Проверка: SQL и команды сохранены, локальные ссылки проверены;
git diff --check пройден. Ревью смысла Sol 6.1 high замечаний не выявило,
новые пояснения дополнительно сверены с кодом и настройками.
This commit is contained in:
ddadmin committed 2026-10-18 19:59:21 +02:00
1 parent 9394b789e5
commit 453a1d6ddf
13 files changed
+98 -75

No files matched your search

+26 -16
View File
@@ -1,16 +1,17 @@
# Хранилище и его слои
В хранилище приходят два потока из Kafka: в топике `hits` — события
кликстрима, в `orders` — заказы магазина. Оба проходят один путь: STG → ODS →
DDS → DM. В STG сообщения сохраняются как есть, в ODS разбираются по полям,
в DDS из них собираются события, заказы и сессии, а в DM — витрины для отчетов.
В Kafka поступают события сайта, или кликстрим, и заказы магазина.
Для событий выделен топик `hits`, для заказов — `orders`.
Из Kafka данные проходят четыре слоя хранилища. В STG сообщения сохраняются
как есть, в ODS разбираются по полям, в DDS из них собираются события,
заказы и сессии, а в DM — витрины для отчетов.
```mermaid
flowchart LR
Kafka --> STG --> ODS --> DDS --> DM
```
## Как читать имена
## Имена таблиц и представлений
Для обычного чтения выбирайте представления с суффиксом `_v`. Они позволяют
менять устройство таблиц, сохраняя привычные запросы к данным.
@@ -20,7 +21,7 @@ flowchart LR
Подробный разбор имен есть в [справочнике
хранилища](../architecture/storage.md#имена-объектов).
## STG: как поступило
## STG: исходные сообщения
STG — сырой слой. Он сохраняет сообщение целой строкой, без разбора. Вместе
с ним записываются сведения о доставке: топик, партиция, смещение и время
@@ -31,7 +32,7 @@ STG — сырой слой. Он сохраняет сообщение цело
удаляются по правилу из [справочника
хранилища](../architecture/storage.md#срок-жизни-сырых-данных).
## ODS: язык источника
## ODS: разбор сообщений
В ODS содержимое сообщения разбирается на колонки с нужными типами данных:
датами, числами, строками. Колонки сохраняют имена из источника. Например,
@@ -41,7 +42,7 @@ STG — сырой слой. Он сохраняет сообщение цело
`*_errors` вместе с исходной строкой и классом ошибки. Правильно записанные
сообщения обрабатываются дальше.
## DDS: язык бизнеса
## DDS: события, заказы и сессии
DDS — детальный слой: в нем данные подготовлены для анализа событий,
заказов и сессий. Здесь же хранится карта идентичностей — таблица связей
@@ -51,6 +52,8 @@ DDS — детальный слой: в нем данные подготовле
В стенде визитом, или сессией, считают подряд идущие события одного
`ClientID` без пауз дольше 30 минут. Визит не пересекает границу модельных суток.
Модельные сутки — день в календаре учебного магазина. Этот календарь
не зависит от текущей даты на вашем компьютере.
Источник передает готовый идентификатор визита `VisitID` по образцу
Яндекс Метрики. В учебном хранилище сессии рассчитываются заново по времени
@@ -61,7 +64,7 @@ DDS — детальный слой: в нем данные подготовле
Готовые сессии читайте через `dds.session_v`. События для самостоятельного
расчета доступны в `dds.event_v`: в этом представлении `VisitID` скрыт.
## DM: данные для дашбордов
## DM: витрины для отчетов
DM — слой витрин. Витрина — готовый набор показателей для отчета или
дашборда. Здесь уже посчитаны, например, дневная выручка по категориям и
@@ -71,7 +74,7 @@ DM — слой витрин. Витрина — готовый набор по
путь расчета. Состав готовых витрин смотрите в [карте
таблиц](../architecture/storage.md#карта-таблиц).
## Справочные данные: зона `dic`
## Справочники в базе `dic`
В базе `dic` хранятся готовые справочные данные. Они загружаются отдельно
от событий и заказов и могут использоваться в расчетах любого слоя.
@@ -81,7 +84,7 @@ DM — слой витрин. Витрина — готовый набор по
устроена зона, смотрите в [разделе о
справочниках](../architecture/storage.md#справочники).
## Сквозные ключи
## Связь данных между слоями
Идентификаторы позволяют связать данные из разных слоев. При переходе в DDS
часть колонок переименовывается: например, `WatchID` становится `event_id`.
@@ -99,7 +102,7 @@ DM — слой витрин. Витрина — готовый набор по
[словарь понятий](../../CONTEXT.md#язык). Точные имена объектов и полей сверяйте с
[картой таблиц](../architecture/storage.md#карта-таблиц).
## Посмотрите сами
## Примеры запросов
Подключитесь к ClickHouse по инструкции из разделов [«Адреса и
пароли»](../../README.md#адреса-и-пароли) и [«Подключиться из
@@ -122,6 +125,8 @@ ORDER BY UTCEventTime
LIMIT 20;
```
Каждая строка здесь — отдельное действие посетителя.
Второй запрос покажет 20 сессий того же дня с наибольшим числом событий.
Сессии рассчитаны по всем событиям дня:
@@ -140,7 +145,12 @@ ORDER BY events_total DESC
LIMIT 20;
```
Третий запрос покажет готовую выручку по категориям за тот же день:
Теперь одна строка представляет целый визит. `events_total` показывает,
сколько событий в него вошло; начало и конец визита записаны в
`started_at` и `finished_at`.
Третий запрос покажет выручку магазина по категориям за тот же день.
Эта витрина рассчитана по заказам:
```sql
SELECT
@@ -153,13 +163,13 @@ WHERE report_date = '2026-06-01'
ORDER BY revenue DESC;
```
Здесь одна строка содержит итоги дня для категории товаров.
Все три запроса читают представления `_v`.
## Куда дальше
## Следующая глава и справочники
Откройте [интерактивную карту](architecture-map.html) из своей копии
репозитория и проследите путь данных.
Список объектов, сроки хранения и устройство таблиц — в [справочнике
хранилища](../architecture/storage.md). Как данные обрабатываются между слоями — в
следующей главе: [потоки Airflow и даги модельного
времени](airflow-dags.md).
следующей главе: [«Генерация и обработка данных в Airflow»](airflow-dags.md).