airflow-greenplum/docs/design/naming_conventions.md

Конвенции Нейминга DWH (Единый Источник)

Статус: активный стандарт для новых реализаций в этом репозитории.

Основа: учебные материалы de-roadmap/dwh-modeling.

Зачем этот документ

Этот справочник задает имена служебных полей. Состав колонок конкретной таблицы проверяйте по ее DDL, а требования к учебной загрузке - по ТЗ.

1. Базовые правила

• Имена колонок: snake_case, на английском.
• Бизнес-ключи источника не переименовываем без необходимости (book_ref, ticket_no, route_no).
• Булевы поля начинаются с is_ (is_outbound, is_boarded).
• Денежные и количественные поля называем по смыслу (total_amount, amount, range_km).

2. Каноничные служебные поля

Поле	Тип (рекомендация)	Смысл	Где применять
_load_id	TEXT NOT NULL	Идентификатор запуска или исходного STG-батча; зависит от слоя	STG, ODS, DDS и DM, кроме календаря
_load_ts	TIMESTAMP NOT NULL	Метка загрузки; в транзакционных ODS сохраняется время STG	STG, ODS, DDS и DM, кроме календаря
event_ts	TIMESTAMP	Опорное время источника или получения снимка	Все таблицы STG и транзакционные ODS
created_at	TIMESTAMP NOT NULL	Когда строка создана в таблице слоя	DDS/DM, где есть lifecycle строки
updated_at	TIMESTAMP NOT NULL	Когда строка обновлена в таблице слоя	DDS/DM, где есть UPDATE
valid_from	DATE NOT NULL (базовый трек)	Начало действия версии SCD2	DDS SCD2
valid_to	DATE	Конец действия версии SCD2 (NULL = current)	DDS SCD2
hashdiff	TEXT NOT NULL	Хэш атрибутов версии для детекта изменений	DDS SCD2

3. Ключи в DDS

• Бизнес-ключ измерения: суффикс _bk (customer_bk, airport_bk).
• Суррогатный ключ измерения: суффикс _sk (customer_sk, airport_sk).
• В существующих таблицах есть бизнес-ключи без _bk: passenger_id у пассажиров, fare_conditions у тарифов, date_actual у календаря. Используйте имена из DDL и ТЗ; переименовывать их в задании не нужно.

4. Правило времени (важно для обучения)

• В STG event_ts задает опору инкремента: book_date у бронирований, билетов, сегментов и посадочных талонов; scheduled_departure у рейсов. Например, у талона это дата бронирования, а не boarding_time.
• У снимков airports, airplanes, routes, seats в STG event_ts = now(): точного времени изменения записи в источнике здесь нет.
• _load_ts относится к загрузке. Какой именно слой ее поставил, указано ниже. Правила отбора строк описаны в руководствах STG и ODS.

5. Применение по слоям

STG

• Все таблицы содержат _load_id = run_id запуска STG, _load_ts = now() и event_ts по правилам выше.

ODS

• Снимки airports, airplanes, routes, seats: _load_id выбранного STG-батча, _load_ts = now(), без event_ts. Загрузка заменяет снимок целиком.
• Транзакционные таблицы: _load_id, _load_ts и event_ts переносятся из STG. Сохраненная _load_ts служит границей инкремента для UPDATE + INSERT.

DDS и DM

• _load_id измененной или вставленной строки относится к текущему запуску своего слоя, _load_ts фиксирует время записи.
• Календарь статический: у dim_calendar нет меток загрузки.
• created_at и updated_at используем там, где они предусмотрены DDL. Например, у факта и полностью пересчитываемой route_performance их нет.
• Для SCD2 используем:
  • valid_from, valid_to, hashdiff, created_at, updated_at.
• Интервалы считаем как [valid_from, valid_to), current-версия: valid_to IS NULL.

6. Что проверяем в ревью

• Нет новых техполей-синнонимов вроде loaded_at, ingested_at, batch_key, если уже есть канон.
• Нет смешивания event_ts и _load_ts в одном смысле.
• В SCD2 не используются альтернативы dw_start_date/dw_end_date, если в проекте принят valid_from/valid_to.