airflow-greenplum/docs/design/naming_conventions.md

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

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

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

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

Чтобы имена полей не «плыли» между слоями, DAG и SQL-скриптами:

• студенты видят один и тот же словарь во всех задачах;
• новые реализации (ODS/DDS/DM) не расходятся с тем, как уже учили на dwh-modeling;
• ревью становится проще: сразу видно, где отклонение от стандарта.

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

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

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

Поле	Тип (рекомендация)	Смысл	Где применять
_load_id	TEXT NOT NULL	Идентификатор загрузки/батча	STG/ODS (новые объекты), при необходимости DDS
_load_ts	TIMESTAMP NOT NULL	Когда запись попала в слой	STG/ODS (новые объекты)
event_ts	TIMESTAMP	Когда событие произошло в источнике (effective time)	ODS/DDS при событийной природе данных
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).

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

• event_ts (effective time) и _load_ts (load time) — разные сущности, не смешиваем.
• Если event_ts отсутствует в источнике, используем _load_ts как fallback и явно документируем это в SQL/доке.
• Для snapshot-справочников (airports, airplanes, routes, seats) в STG нет бизнес-события с точным временем: event_ts заполняется через now() при загрузке. Это намеренно и задокументировано в каждом load-скрипте.

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

STG

• Используем канон _load_id, _load_ts, event_ts для всех таблиц.

ODS

• Используем канон _load_id, _load_ts, event_ts.
• Базовый эталон ODS в этом стенде: SCD Type 1 (current state + UPSERT).

DDS

• Для 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.