airflow-greenplum/docs/internal/bookings_stg_design.md

Дизайн STG для bookings в Greenplum (черновик)

Внутренний документ для учебного стенда. Перед итоговой сдачей можно объединить с основной документацией.

1. Цель и общий контур

• Источник: Postgres в контейнере bookings-db, база demo, таблица bookings.bookings (см. docs/internal/bookings_tz.md).
• Цель: показываем путь данных от операционной БД до сырого слоя DWH в Greenplum.
• В этом документе описываем только часть src (bookings-db) → STG (Greenplum). Слои ODS/DDS/DM студент проектирует сам по статье про моделирование DWH.

Логика на уровне слоёв (по статье):

• src: оперативная система (bookings-db, схема bookings).
• stg: сырой слой в Greenplum, максимально близкий к источнику, без бизнес‑логики.
• дальше по заданию менти можно строить ods/dds/dm поверх STG.

2. Схема и таблицы в Greenplum

2.1. Схема

• Используем одну схему stg в Greenplum.
• В этой схеме будут:
  • внешняя таблица PXF для чтения из bookings-db;
  • внутренняя таблица STG для долговременного хранения «сырых» данных.

2.2. Внешняя таблица (PXF)

• Имя таблицы: stg.bookings_ext.
• Назначение: «окно» в исходную таблицу bookings.bookings в bookings-db через PXF (JDBC).
• Типы колонок:
  • можем использовать «родные» типы из bookings.bookings (включая даты/числа);
  • задача внешней таблицы — корректно читать данные из источника, не заниматься приведением типов.

DDL будет добавлен в sql/ddl_gp.sql в блоке DDL для Greenplum (примерно по шаблону из docs/internal/pxf_bookings.md), с LOCATION ('pxf://bookings.bookings?PROFILE=JDBC&SERVER=bookings-db').

2.3. Внутренняя таблица STG

• Имя таблицы: stg.bookings.
• Назначение: хранить сырые данные из источника для последующей обработки (ODS/DDS/витрины).
• Принципы моделирования:
  • все бизнес‑колонки из bookings.bookings храним как TEXT (как в примерах STG из статьи);
  • не делаем UPDATE/DELETE, только INSERT новых записей;
  • бизнес‑колонки по названию совпадают с источником (чтобы проще было маппить).

Технологические колонки:

• src_created_at_ts TIMESTAMP — дата/время из источника, приведённая к TIMESTAMP:
  • используется как опорная колонка для инкрементальной загрузки;
  • заполняется из исходной даты/времени (created_at или аналог).
• load_dttm TIMESTAMP NOT NULL DEFAULT now() — когда запись была загружена в STG.
• batch_id TEXT NOT NULL — идентификатор «пачки» (например, {{ ds_nodash }} или run_id Airflow).
• при необходимости позже можно добавить src_system TEXT, если появятся другие источники.

Колонки‑бизнес‑ключи (booking_id и т.п.) храним как TEXT. В слое DDS позже можно будет ввести суррогатные ключи и нормализовать модель под витрины.

3. Инкрементальная загрузка

3.1. Опорное поле для инкремента

• Опорная колонка: src_created_at_ts (внутреннее имя в STG).
• Источник значения:
  • берём из соответствующей колонки в bookings.bookings (например, book_date/created_at — будет уточнено при реализации);
  • при чтении через stg.bookings_ext приводим к TIMESTAMP.

3.2. Правила определения full/delta

• При первом запуске, если таблица stg.bookings пуста:
  • считаем режим full — загружаем все строки из stg.bookings_ext.
• При последующих запусках:
  • читаем max(src_created_at_ts) из stg.bookings за все предыдущие загрузки;
  • считаем, что нужно загрузить только строки, где src_created_at_ts больше этой максимальной метки и не позже конца текущего учебного дня.

Таким образом, вся логика инкремента «замкнута» на один техно‑столбец src_created_at_ts, который студент потом сможет использовать и на следующих слоях (например, в CDC‑логике).

4. DAG’и Airflow (логика на уровне задач)

4.1. DAG для DDL

• dag_id: bookings_stg_ddl (рабочее имя).
• Назначение: один раз (или при изменении схемы) создать необходимые объекты в Greenplum:
  • схему stg (если её ещё нет);
  • внешнюю таблицу stg.bookings_ext (PXF → bookings-db);
  • внутреннюю таблицу stg.bookings с текстовыми колонками и тех.полями.
• Этот DAG не загружает данные, только подготавливает структуру.
• Вся DDL‑логика (CREATE/ALTER/DROP) сосредоточена здесь; рабочие DAG’и занимаются только DML (INSERT/SELECT).

4.2. DAG для ежедневной загрузки

• dag_id: bookings_to_gp_stage (рабочее имя).
• Основные параметры:
  • load_date (по умолчанию {{ ds }}) — учебный день, за который генерим и грузим данные.
  • подключения:
    • bookings_db_conn_id — Airflow connection к bookings-db;
    • greenplum_conn_id — Airflow connection к Greenplum.

Предлагаемая последовательность задач:

1. generate_bookings_day
   • при необходимости создаёт таблицу bookings.bookings в bookings-db (одноразово);
   • идемпотентность: проверяет, есть ли данные за load_date в bookings.bookings;
     • если нет — генерирует данные за один учебный день (можно опираться на make bookings-generate-day и логику из docs/internal/bookings_tz.md);
     • если да — ничего не делает, логирует «данные за этот день уже есть» и считается успешно выполненной.
2. get_last_loaded_ts_from_gp
   • читает max(src_created_at_ts) из stg.bookings;
   • если данных нет — возвращает None и режим загрузки full;
   • результат (последняя метка и режим) передаёт через XCom.
3. extract_and_load_increment_via_pxf
   • делает INSERT INTO stg.bookings (...) SELECT ... FROM stg.bookings_ext WHERE src_created_at_ts > :last_ts AND src_created_at_ts <= :window_end;
   • в режиме full подставляет «минимальную» дату (или просто не фильтрует);
   • заполняет src_created_at_ts, load_dttm, batch_id.
4. check_row_counts
   • сравнивает количество строк, прочитанных из stg.bookings_ext, и количеством реально вставленных в stg.bookings;
   • при расхождении падает с понятным сообщением «что посмотреть/проверить».
5. (опционально) finish_summary
   • логирует итог: режим загрузки (full/delta), интервал src_created_at_ts, количество строк.

Эта последовательность служит учебным примером для менти: от генерации «операционных» данных до инкремента в сырой слой DWH.

5. Связь с остальными документами

• docs/internal/bookings_tz.md — как готовится и генерируется источник bookings-db.
• docs/internal/pxf_bookings.md — детали настройки PXF и внешней таблицы для чтения из bookings-db.
• sql/ddl_gp.sql — итоговый DDL для схемы stg и таблиц stg.bookings_ext / stg.bookings (применяется через make ddl-gp).

Дальнейшая модель DWH (слои ODS/DDS/DM, факт/измерения, SCD) должна быть спроектирована студентом по статье о моделировании данных, используя stg.bookings как входной слой.

6. Требования к читаемости и комментариям

• DAG’и bookings_stg_ddl и bookings_to_gp_stage — это учебный материал для менти.
• В коде DAG’ов должны быть:
  • понятные docstring на русском у всех функций и DAG;
  • короткие комментарии рядом с нетривиальной логикой (особенно вокруг инкремента и идемпотентности);
  • говорящие task_id и названия функций, отражающие их роль в процессе.
• Цель: чтобы по одному только коду DAG студент мог восстановить архитектуру процесса и сопоставить её с теорией из статьи про моделирование DWH.