airflow-greenplum/docs/internal/architecture_review.md

Ревью архитектуры слоёв DWH: оценка учебной ценности

Дата: 2026-03-01 Статус: backlog задач для доработки Контекст: оценка текущей конструкции слоёв с точки зрения учебных целей

Context

Стенд — курсовая работа и эталон для менти-джунов. Они понесут эти паттерны на свою первую работу. Оцениваем по двум осям: production-ready (чтобы не стыдно было показать на собеседовании) и KISS (чтобы джун не утонул в сложности).

Текущее состояние: 95 SQL-файлов, 5 слоёв (STG→ODS→DDS→DM), 9 DAG-ов, полная Star Schema с SCD2, DQ на каждом шаге. Реализована 1 из 5 витрин DM.

---

СИЛЬНЫЕ СТОРОНЫ (что уже отлично)

1. Паттерн load → DQ на каждом шаге — эталонный

Каждая сущность в каждом слое имеет тройку файлов _ddl.sql / _load.sql / _dq.sql. DAG-и обеспечивают порядок load→dq→next. Smoke-тесты проверяют рёбра графа. Студенты усвоят: DQ — не опция, а часть пайплайна.

2. UPSERT через UPDATE + INSERT — production-grade для Greenplum

Не DELETE+INSERT (дорого на AO-таблицах), не MERGE (нет в GP6). IS DISTINCT FROM для null-safe сравнения — деталь, которую даже опытные инженеры забывают.

3. Антипаттерн-обучение в DM (distribution by date)

Комментарий в dm/sales_report_ddl.sql объясняет почему нельзя распределять по дате, с конкретными причинами (Load Skew, Processing Skew). Это «почему нет» — именно то, что не дают учебники.

4. SCD2 в dim_routes — полный и корректный

Все три кейса: закрытие изменённых версий (hashdiff), закрытие исчезнувших маршрутов, вставка новых версий с правильной логикой valid_from. DQ проверяет пересечение интервалов. Готовый reference implementation.

5. Point-in-time lookup в факте — ключевой навык

LEFT JOIN dds.dim_routes AS rte
    ON rte.route_bk = flt.route_no
    AND flt.scheduled_departure::DATE >= rte.valid_from
    AND (rte.valid_to IS NULL OR flt.scheduled_departure::DATE < rte.valid_to)

Многие продакшн-DWH ошибаются, присоединяя только текущую версию.

6. HWM-инкрементальность в DM — самовосстанавливающийся пайплайн

MAX(_load_ts) + TEMP TABLE для однократной агрегации — канон MPP. Пайплайн сам «догоняет» пропущенные дни.

7. DAG-графы корректно отражают зависимости данных

Параллельность airports/airplanes, gates на routes (нужны оба), факт после всех измерений. Smoke-тесты проверяют и наличие, и отсутствие рёбер (параллельность).

8. ANALYZE после каждой загрузки

GP-специфичная best practice, которую забывают даже опытные команды.

9. Идемпотентные STG-загрузки

NOT EXISTS (... WHERE batch_id = '{{ run_id }}') — простой, корректный, понятный паттерн для retry-safe загрузок.

---

ЗАМЕЧАНИЯ И ЗАДАЧИ ДЛЯ ДОРАБОТКИ

P0: Фактическая ошибка (исправить до показа студентам)

• Противоречие в distribution key для airport_traffic
  • bookings_dm_design.md (строка 182): DISTRIBUTED BY (traffic_date)
  • sales_report_ddl.sql: явно объясняет, почему distribution by date — антипаттерн
  • Нужно: исправить на DISTRIBUTED BY (airport_sk) в дизайн-документе
  • Файл: docs/internal/bookings_dm_design.md

P1: Высокий эффект, минимум усилий (комментарии и документация)

• Нет объяснения «почему не SERIAL» в генерации SK

  • MAX(sk) + ROW_NUMBER() корректен для GP, но студент на PostgreSQL/Snowflake будет использовать IDENTITY/SEQUENCE
  • Нужно: 4-строчный комментарий в sql/dds/dim_airports_load.sql

• Факт без суррогатного ключа — не объяснено «почему»

  • Натуральный (ticket_no, flight_id) как grain — правильное Kimball-моделирование
  • Нужно: комментарий в sql/dds/fact_flight_sales_ddl.sql

• Нет упоминания cross-DAG зависимостей

  • STG, ODS, DDS, DM — отдельные DAG-и с schedule=None, студент может не понять порядок
  • Нужно: комментарий в docstring каждого DAG или docs/dag_execution_order.md

• Late-arriving dimensions не упомянуты

  • Факт делает LEFT JOIN → passenger_sk = NULL при опоздании; нет механизма исправления
  • Нужно: комментарий в sql/dds/fact_flight_sales_load.sql у LEFT JOIN-ов

• Batch resolver недообъяснён

  • _resolve_stg_batch_id с INTERSECT по 4 таблицам — нет комментария зачем нужна согласованность
  • Нужно: комментарий в airflow/dags/bookings_to_gp_ods.py перед SQL-запросом

• helpers/greenplum.py без пометки «legacy»

  • Использует прямой psycopg2 + ENV — противоречит PostgresOperator-подходу
  • Нужно: docstring «LEGACY: только для CSV-пайплайна» в airflow/dags/helpers/greenplum.py

P2: Средние усилия, заметное улучшение качества

• Дублирование hashdiff CTE в dim_routes_load.sql

  • md5(COALESCE(...)) повторяется в Statement 1 и Statement 2, ROW_NUMBER() — 3 раза
  • Решение: вынести в CREATE TEMP TABLE tmp_routes_src ON COMMIT DROP
  • Файл: sql/dds/dim_routes_load.sql

• Несогласованность нейминга STG vs ODS+ ✅ РЕШЕНИЕ ПРИНЯТО

  • STG: batch_id, load_dttm, src_created_at_ts → переименовать в канон _load_id, _load_ts, event_ts
  • Единый словарь во всех слоях снижает когнитивную нагрузку
  • Добавить заметку в naming_conventions.md (секция «legacy-нейминг в реальных проектах»)
  • Удалить секцию 6 «Переходный маппинг» как неактуальную
  • Файлы: ~27 STG SQL + ODS load-скрипты + naming_conventions.md + тесты

• Дублирование CTE в ODS load-скриптах

  • WITH src AS (...) копируется 2-3 раза в каждом из 9 ODS load-файлов
  • Решение: TEMP TABLE для самых сложных (airports, flights, routes); простые — оставить
  • Файлы: sql/ods/airports_load.sql, sql/ods/flights_load.sql, sql/ods/routes_load.sql

• DM слой незавершён

  • 1 из 5 витрин реализована, остальные — закомментированные заглушки
  • Решение: реализовать route_performance (full rebuild + AO Column Store); остальные 3 — задания для студентов
  • Файлы: sql/dm/route_performance_*.sql (новые), DAG, тесты

P3: Хорошо бы, но не горит

• Крутая лестница сложности ODS→DDS

  • Решение: создать «маршрут изучения» DDS: tariffs → calendar → airports → passengers → routes (SCD2) → fact

• DQ без переиспользуемых функций

  • Решение: добавить один опциональный пример sql/lib/dq_assert_no_duplicates() как seed

• Нет документа по стратегии distribution

  • Решение: docs/internal/distribution_strategy.md с объяснением логики для каждого слоя

• Отсутствующие паттерны (комментарии/заметки):

  • Partitioning (когда и зачем, почему не здесь)
  • SCD Type 3/6 (хотя бы упомянуть существование)
  • Data lineage (_load_id в DM ≠ batch_id в STG — нет сквозного трассирования)

---

ЧТО ОСТАВИТЬ КАК ЕСТЬ

Аспект	Почему не трогаем
Факт без SK	Правильное моделирование, нужен только комментарий (P1)
ODS DAG с 20 задачами	Не перегружает — параллельная структура наглядна на графе
5 витрин DM	Правильное количество, каждая учит своему паттерну
PL/pgSQL DQ	Достаточно для учебного проекта, фреймворк — перебор
MAX+ROW_NUMBER для SK	Корректно для GP, нужен только комментарий (P1)

---

Сводка по трудозатратам

Приоритет	Действие	Оценка	Ключевые файлы
P0	Исправить distribution key в airport_traffic	5 мин	docs/internal/bookings_dm_design.md
P1	Добавить 7 точечных комментариев	30-40 мин	6-7 файлов (DDL, load, DAG)
P2	Рефакторинг hashdiff → TEMP TABLE	1 час	sql/dds/dim_routes_load.sql
P2	Переименовать STG поля в канон + заметка	1-2 часа	27 STG SQL + ODS load + naming_conventions.md
P2	TEMP TABLE для сложных ODS load-ов	1 час	3-4 ODS load файла
P2	Реализовать dm.route_performance	2-3 часа	3 SQL + DAG + тесты
P3	Маршрут изучения DDS + distribution strategy doc	1 час	2 новых md-файла