Files

T

ddadmin 9b1e853d99 docs(dwh): зафиксированы конвенции нейминга и обновлён план ODS

- Зачем:
  - нужен единый стандарт именования полей, чтобы новые слои не расходились с учебными материалами.
- Что:
  - добавлен единый документ с правилами нейминга `docs/internal/naming_conventions.md`.
  - полностью переписан `docs/internal/bookings_ods_design.md` в эталонный учебный план ODS (SCD1, батч-контракт, DQ, граф DAG).
  - добавлены ссылки на стандарт нейминга в `docs/README.md`, `docs/internal/db_schema.md` и `AGENTS.md`.
- Проверка:
  - проверен diff по измененным файлам (`git diff`).

2026-02-28 22:13:06 +03:00

4.8 KiB

Raw Blame History

Конвенции Нейминга 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/доке.

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

STG

Для уже реализованного bookings STG сохраняем текущие legacy-имена ради обратной совместимости:
- src_created_at_ts
- load_dttm
- batch_id
Для новых 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. Переходный маппинг legacy -> канон

Legacy (текущий bookings STG)	Канон
`batch_id`	`_load_id`
`load_dttm`	`_load_ts`
`src_created_at_ts`	`event_ts`

Примечание: это логический маппинг для новых слоёв. Массовое переименование существующего STG не требуется.

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

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

4.8 KiB Raw Blame History