From 830efa7ef4826d03ee8f5401bf130822558ba6a6 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Thu, 3 Sep 2026 17:12:37 -0400 Subject: [PATCH] =?UTF-8?q?docs(labs):=20=D0=A2=D0=97=20=D1=81=D1=82=D1=83?= =?UTF-8?q?=D0=BF=D0=B5=D0=BD=D0=B8=202=20=C2=AB=D0=A1=D0=B2=D0=BE=D0=B9?= =?UTF-8?q?=20=D0=B3=D1=80=D0=B0=D1=84=D0=B8=D0=BA=20=D0=B2=20Superset?= =?UTF-8?q?=C2=BB=20=D0=B8=20=D0=BF=D0=BE=D1=80=D1=8F=D0=B4=D0=BE=D0=BA=20?= =?UTF-8?q?=D0=BF=D1=80=D0=BE=D0=B3=D1=80=D0=B0=D0=BC=D0=BC=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - программа лаб принята спекой, но индекс docs/labs/ показывал только пять витрин и дашборд; ступень 2 не имела ТЗ (#226). - Что: - новое ТЗ docs/labs/superset-chart.md: один столбиковый график доли отказов по устройствам поверх dm.session_overview_v, метрика в датасете. - docs/labs/README.md: семь ступеней основной программы и пять разделов факультативов; правила пяти витрин помечены как правила ступени 1. - шапка docs/labs/superset-dashboard.md: факультатив раздела «Superset и BI». - Проверка: - grep 'ё' и 'менти' по трем файлам молчат; скрипт ссылок из тикета печатает пусто; git diff --check чистый. Closes #226 --- docs/labs/README.md | 75 ++++++++++++++++++++------- docs/labs/superset-chart.md | 89 +++++++++++++++++++++++++++++++++ docs/labs/superset-dashboard.md | 9 ++-- 3 files changed, 151 insertions(+), 22 deletions(-) create mode 100644 docs/labs/superset-chart.md diff --git a/docs/labs/README.md b/docs/labs/README.md index c607f8b..6d33143 100644 --- a/docs/labs/README.md +++ b/docs/labs/README.md @@ -1,21 +1,29 @@ -# Учебные задания: витрины слоя DM и дашборд в Superset +# Учебные задания -Пять домашних заданий — про витрины слоя DM. Стенд привозит слой -наполовину: витрины трех сюжетов дашборда и контроль качества построены, -остальные витрины строит менти. Каждое из них — самостоятельное ТЗ: что за -витрина, какое у нее зерно, из чего она собирается и как проверить, что -собралась верно. +Программа состоит из двух частей: основная включает семь ступеней, которые ты +проходишь по порядку, а факультативы выбираешь по желанию. Причины такого +порядка и формы заданий описаны в [программе учебных лаб](../specs/2026-09-01-labs-program.md#2-устройство-программы-основная-программа-и-факультативы). -Шестое задание — необязательная лаба в Superset. В ней менти собирает свой -дашборд поверх пяти витрин. +## Основная программа -Общее устройство слоя — [дока DM](../architecture/dm.md). Она отвечает на -вопросы «почему так», задание отвечает на вопрос «что сделать». +| Ступень | Задание | Чему учит | +|---|---|---| +| 1 | Пять витрин слоя DM | построить результат для потребителя хранилища; уроки каждой витрины — в таблице ниже | +| 2 | [Свой график в Superset](superset-chart.md) | превратить свой результат из хранилища в отчет в BI | +| 3 | Нарежь сессии сам | счет показывает проблему, но причину приходится искать в отдельных строках | +| 4 | Перепиши нарезку стенда | изменить расчетную сущность внутри готового конвейера и проверить ее внешним эталоном | +| 5 | Сначала сторож, потом ломай: заказы | построить сторожей до рискованного изменения, а не после первой поломки | +| 6 | Разбери сырые события и сверь результат со стендом | изучить разбор потока отдельно от живого приема и сверить его со стендовым результатом | +| 7 | Мониторинг: куда смотреть | выбрать, куда и на что смотреть в живой системе | -## Порядок +ТЗ для ступеней 3–7 появятся по мере продвижения программы. -Задания идут по нарастанию: каждое следующее опирается на то, что уже -усвоено. +## Ступень 1: пять витрин слоя DM + +Слой DM в стенде построен наполовину: витрины трех сюжетов дашборда и контроль +качества уже построены, остальные пять витрин строишь ты. Каждая из них — +самостоятельное ТЗ: в нем есть состав витрины, зерно, источники и способ +проверки. | № | Результат | Чему учит | |---|---|---| @@ -24,11 +32,13 @@ | 3 | [`session_overview`](session-overview.md) | зерно решает, на какие вопросы витрина уже не ответит | | 4 | [`dq_errors_daily`](dq-errors-daily.md) | у брака свой день и свой срок жизни | | 5 | [`utm_effectiveness`](utm-effectiveness.md) | `declared_` в имени — предупреждение, а не украшение | -| 6 | [Свой дашборд в Superset](superset-dashboard.md) — необязательная лаба | свои объекты BI живут отдельно от стендовых | -## Общие правила +Общее устройство слоя — [дока DM](../architecture/dm.md). Она отвечает на +вопросы «почему так», задание отвечает на вопрос «что сделать». -Они одни для пяти заданий по витринам, поэтому записаны здесь, а не +## Общие правила ступени 1 + +Они одни для пяти заданий по витринам ступени 1, поэтому записаны здесь, а не повторяются в каждом ТЗ. **Читать — через `_v`.** Публичный договор сущности DDS — представление с @@ -72,7 +82,7 @@ DDS, и задания остаются независимыми. Исключе Списывать с нее устройство можно и нужно; списывать состав колонок — нет, он у каждой витрины свой. -## Самопроверка +## Самопроверка ступени 1 Даг `homework_check` запускается рукой, расписания у него нет. Задача витрины красная, пока витрины нет или счет не сходится, и зеленая, когда @@ -101,6 +111,37 @@ DDS, и задания остаются независимыми. Исключе Смотреть туда стоит после своей сборки: сравнить два решения полезно, списать одно — нет. +## Факультативы + +Эти задания ты берешь по желанию. Полный список сюжетов — в разделе +[«Факультативы — пять разделов»](../specs/2026-09-01-labs-program.md#4-факультативы--пять-разделов) +программы. + +### Почему выручка не сходится + +Открывается после ступени 1. Расхождения между источниками, повторы +покупок и день, после которого отчет можно считать окончательным. + +### Тонкий анализ данных + +Открывается после ступени 1. Знание о пользователе на дату и обогащение +отчета своим словарем. + +### Superset и BI + +Открывается после ступени 2. [Свой дашборд в Superset](superset-dashboard.md): +свои объекты BI живут отдельно от стендовых. + +### Инженерия стенда + +Открывается после ступени 1. Прием и хранение данных, раскладка по шардам, +повторная обработка дня и обновление витрин. + +### Что делать, когда стенд сломался + +Открывается после ступени 7. Поломки стенда и runbook по итогам +расследований; весь раздел — повышенная сложность. + ## Уборка Черновики и опыты за собой сносить: правило проверок стенда — diff --git a/docs/labs/superset-chart.md b/docs/labs/superset-chart.md new file mode 100644 index 0000000..4383e26 --- /dev/null +++ b/docs/labs/superset-chart.md @@ -0,0 +1,89 @@ +# Свой график в Superset + +**Чему учит:** увидеть, как собственный результат из хранилища становится +отчетом в BI. + +## Сначала прочитать + +- [«Немного Superset»](../handbook/superset.md); +- [задание 3: `dm.session_overview`](session-overview.md). + +## Роль графика + +В задании 3 ты собрал витрину `dm.session_overview_v`. Теперь покажи, с каких +устройств чаще уходят после первой страницы. Построй столбиковый график доли +отказов по `device_category` за весь период витрины. Измерение одно — +`device_category`, метрика тоже одна. + +## Что сделать + +Заведи физический датасет в подключении к `ClickHouse`: схема `dm`, объект +`session_overview_v`. Назови по-русски хотя бы две колонки: + +- `device_category` — «Категория устройства»; +- `report_date` — «Дата отчета». + +В редакторе датасета, на вкладке «Metrics», создай метрику: + +| Поле | Значение | +|---|---| +| `Metric Key` | `bounce_share` — ключ метрики и ее SQL-псевдоним | +| `Label` | «Доля отказов» | +| `SQL expression` | `SUM(bounce_sessions) / SUM(sessions)` | +| `D3 format` | `.1%` | + +Доля считается из сумм слагаемых: среднее готовых долей соврет. Поэтому +метрике нужно это выражение. Сохрани ее в датасете, а не в графике: подписи и +формат задаются в датасете, а график их использует. Так во всех будущих +графиках у метрики будут одинаковые подписи. Это правило описано в +[справочнике Superset](../architecture/superset.md#дерево-импорта). + +Не используй вкладку «Custom SQL» конструктора графика. Созданная там метрика +доступна только этому графику, а нужна метрика датасета. + +Создай столбиковый график с метрикой «Доля отказов». В поле «X-axis» укажи +«Категория устройства», а «Dimensions» не заполняй. Дашборд создавать не +нужно: сохраненного графика достаточно. + +По умолчанию в графике выбран период «No filter». Оставь его таким или задай +явные даты. Относительный период, например «Last week», даст пустой +график: модельный календарь стенда отстает от настоящего. Последнюю дату +витрины посмотри в SQL Lab: + +```sql +SELECT max(report_date) +FROM dm.session_overview_v; +``` + +Стендовые объекты не меняй. Что переживает `make up`, а что стирает +`make clean`, описано в главе [«Немного Superset»](../handbook/superset.md#стендовые-объекты-и-ваши). + +## Как проверить себя + +График проверяется глазами, поэтому задачи для него в `homework_check` нет. +В SQL Lab выполни запрос: + +```sql +SELECT device_category, + round(100 * sum(bounce_sessions) / sum(sessions), 1) AS bounce_pct +FROM dm.session_overview_v +GROUP BY device_category +ORDER BY device_category; +``` + +Сверь с графиком значение для каждой категории. В разделе «Customize» включи +«Show Value» или наведи указатель на столбик. Запрос возвращает проценты с одним знаком, +как формат `.1%`, поэтому числа должны совпасть один в один. + +## Приемка + +- [ ] создан физический датасет `dm.session_overview_v` в подключении + `ClickHouse`; +- [ ] в датасете есть метрика «Доля отказов» с выражением + `SUM(bounce_sessions) / SUM(sessions)` и форматом `.1%`; +- [ ] для `device_category` и `report_date` заданы русские имена «Категория + устройства» и «Дата отчета»; +- [ ] сохранен столбиковый график доли отказов по категориям устройств без + относительного фильтра по времени; +- [ ] график сверен с запросом из SQL Lab; +- [ ] стендовые объекты не изменены, дашборд не создан. diff --git a/docs/labs/superset-dashboard.md b/docs/labs/superset-dashboard.md index 47c36d0..2d3d246 100644 --- a/docs/labs/superset-dashboard.md +++ b/docs/labs/superset-dashboard.md @@ -1,12 +1,11 @@ -# Задание 6 (необязательное): свой дашборд в Superset +# Свой дашборд в Superset **Чему учит:** довести свои витрины до потребителя — завести в Superset датасеты поверх публичных представлений, подобрать графики под вопросы и собрать из них один связный экран. -Эта лаба идет после заданий 1–5 и опирается на их результат. Ее можно -пропустить: основной предмет стенда — ClickHouse, а здесь вся работа — в -интерфейсе BI. +Это факультатив раздела «Superset и BI». Его можно пройти после ступени 2, +когда готовы витрины ступени 1. ## Роль дашборда @@ -29,7 +28,7 @@ Заведи отдельные датасеты и графики, собери из них свой дашборд. Назови его, например, «Мои витрины DM». Это то же правило, по которому DDL домашек лежит -в `sql/ddl/70-labs.sql`: стенд привозит свои объекты, менти создает свои. +в `sql/ddl/70-labs.sql`: стендовые объекты уже есть, свои создаешь ты. ## Датасеты