Files

T

ddadmin 4ce0aa7a23 docs(etl): расширена документация ETL DAG-ов ODS, DDS, DM

- Зачем:
  - документация трёх DAG-ов была значительно беднее эталона (bookings_to_gp_stage.md):
    отсутствовал пошаговый разбор задач, SQL-пути и ASCII-графы зависимостей.
- Что:
  - добавлены секции "Как это работает внутри" с таблицами task_id → SQL-файл → паттерн.
  - добавлены ASCII-графы зависимостей в ODS и DDS (в DM уже был).
  - исправлено описание паттернов ODS: явно разделены TRUNCATE+INSERT для AO snapshot-справочников и SCD1 UPSERT для транзакционных таблиц.
  - исправлено описание fact_flight_sales: убрана неточная отсылка к late-arriving dimensions, добавлено объяснение defensive LEFT JOIN и точных DQ-правил (0% / 1%).
  - добавлена таблица grain и описание стратегий загрузки для каждой DM-витрины.
  - план улучшений перенесён в docs/archive/.
- Проверка:
  - визуально: открыть каждый docs/bookings_to_gp_*.md и убедиться, что секции присутствуют.

2026-03-11 19:26:29 +03:00

7.8 KiB

Raw Blame History

План: выравнивание качества документации ETL DAG'ов

Контекст

Документ bookings_to_gp_stage.md — эталон: пошаговый разбор задач, ASCII-граф, ссылки на SQL-файлы, описание edge cases. Три остальных документа (_ods, _dds, _dm) значительно беднее. Цель — подтянуть их до того же уровня.

Единый шаблон секций (целевая структура)

Каждый документ должен содержать:

Заголовок + вводный абзац (что за DAG, какой слой, зачем)
Что делает DAG (буллеты, краткое описание)
Что должно быть готово (prerequisites)
Как запустить (UI + опциональные параметры)
Граф зависимостей (ASCII-диаграмма, не буллет-лист)
Как это работает внутри (по шагам) ← ГЛАВНОЕ ДОБАВЛЕНИЕ
- Пронумерованные шаги: task_id → SQL-файл → что делает → паттерн (SCD1/SCD2/rebuild/HWM)
- Учебные пояснения к нетривиальным паттернам
Как проверить результат (SQL-запросы)
Типичные ошибки (уже есть, оставляем)

Что именно добавить/исправить в каждом документе

A. `bookings_to_gp_ods.md`

Текущее состояние: 95 строк, нет пошагового разбора, нет ASCII-графа, нет SQL-путей.

#	Что сделать	Детали
A1	ASCII-граф зависимостей	Заменить буллет-лист на диаграмму (как в stage). Показать параллельные ветки airports/airplanes, схождение на routes/seats, цепочку flights→segments→boarding_passes
A2	Секция "Как это работает внутри"	10 шагов: resolve_stg_batch_id (Python, INTERSECT-логика), затем 9 пар load→dq с указанием SQL-файлов
A3	Пояснить паттерн SCD1 UPSERT	Кратко: TEMP TABLE → UPDATE (IS DISTINCT FROM) → INSERT. Одного абзаца достаточно, потом ссылка "паттерн одинаков для всех 9 таблиц"
A4	Описать разницу snapshot vs HWM	Snapshot-справочники фильтруются по `stg_batch_id`; транзакционные таблицы — по HWM (`_load_ts`). Объяснить почему (чтобы не терять инкременты при повторных запусках STG)
A5	Edge case: пустой батч	Для инкрементальных таблиц допустим; для snapshot — нет

Ожидаемый объём: ~140–160 строк.

B. `bookings_to_gp_dds.md`

Текущее состояние: 73 строки — самый бедный документ. Нет пошаговости, нет ASCII-графа, SCD2 не объяснён.

#	Что сделать	Детали
B1	ASCII-граф зависимостей	calendar → параллельно 4 SCD1-измерения + dim_routes (после airports+airplanes) → fact (после всех dims) → summary
B2	Секция "Как это работает внутри"	8 шагов: calendar (rebuild), 4×SCD1-измерения, dim_routes (SCD2), fact_flight_sales, summary
B3	Объяснить SCD2 для dim_routes	Учебный блок: hashdiff (MD5), закрытие старых версий, вставка новых, point-in-time valid_from. Это ключевой паттерн DDS — заслуживает 10–15 строк
B4	Объяснить Phase 3 (денормализация)	Обновление SCD1-атрибутов (города, модель) во ВСЕХ версиях dim_routes. Зачем: чтобы не хранить устаревшие названия городов
B5	Объяснить late-arriving dimensions	LEFT JOIN в fact_flight_sales: факт может прийти раньше справочника. 3–5 строк
B6	Объяснить point-in-time join	Как факт привязывается к правильной версии SCD2-маршрута по дате рейса
B7	Edge case: генерация SK	MAX() + ROW_NUMBER() безопасна только при concurrency=1

Ожидаемый объём: ~160–180 строк.

C. `bookings_to_gp_dm.md`

Текущее состояние: 80 строк. ASCII-граф есть (хорошо!), описание стратегий загрузки есть (хорошо!), но нет пошагового разбора с SQL-файлами.

#	Что сделать	Детали
C1	Секция "Как это работает внутри"	5 шагов (по одному на витрину) + start_dm + finish_dm_summary. Для каждой витрины: task_id → SQL-файл → паттерн → зерно (grain)
C2	Расширить описание sales_report	HWM-паттерн: какие даты пересчитываются, NULLIF-guard для boarding_rate, автоматическая "догонка" при первичной загрузке
C3	Расширить описание route_performance	Почему Full Rebuild: AO Column (нет UPDATE/DELETE), таблица маленькая. 3-шаговый паттерн: TRUNCATE → агрегация по route_bk → JOIN с текущей версией SCD2
C4	Добавить grain для каждой витрины	sales_report: (flight_date, departure_airport_sk, arrival_airport_sk, tariff_sk); route_performance: route_bk; и т.д.
C5	Добавить SQL-пути к задачам	Сейчас нигде не указаны пути к SQL-файлам

Ожидаемый объём: ~140–160 строк.

D. Мелкие правки в `bookings_to_gp_stage.md` (опционально)

#	Что сделать	Детали
D1	Убедиться в консистентности шаблона	Если в ходе работы над ODS/DDS/DM выработается чуть лучшая структура — привести stage к тому же формату (только структурные правки, контент не менять)

Порядок работы

ODS (средняя сложность, знакомый паттерн SCD1)
DDS (наибольшая учебная ценность — SCD2, late-arriving dims)
DM (наименьший объём правок — ASCII-граф уже есть)
Stage — только если нужна косметика для консистентности

Принципы

Не раздувать: целевой объём каждого документа — 140–180 строк (stage = 157).
Учебная ценность > полнота: объяснять «почему», а не перечислять все колонки.
SQL-пути обязательны — это главный навигационный инструмент для студента.
Один паттерн объясняем один раз подробно, дальше ссылаемся: "паттерн аналогичен X".

7.8 KiB Raw Blame History Unescape Escape