diff --git a/docs/internal/db_schema.md b/docs/internal/db_schema.md index ac85d20..634ea6b 100644 --- a/docs/internal/db_schema.md +++ b/docs/internal/db_schema.md @@ -6,13 +6,21 @@ Эта документация описывает архитектуру хранилища данных (DWH) для учебного проекта Airflow + Greenplum. Источник данных — демо-БД `bookings` (Postgres). -### Ключевые договорённости (для LLM и студентов) +**Целевые аудитории:** +- **LLM/Разработчики**: Технические спецификации для реализации (см. раздел "Спецификации для реализации") +- **Студенты**: Обучающие материалы и пояснения (см. раздел "Обучающие материалы") -- **Источник**: используем основные таблицы схемы `bookings` (табличные данные, не `VIEW`). -- **Зерно факта `fact.flight_sales`**: 1 строка = 1 сегмент билета (`ticket_no` + `flight_id`, источник: `segments`). -- **Обязательная связь для аэропортов и самолёта**: `flights.route_no → routes → (departure_airport, arrival_airport, airplane_code)`. -- **Даты**: как минимум различаем `book_date` (дата покупки) и `scheduled_departure` (дата/время вылета). -- **Инкремент в STG**: для `tickets` опорная дата берётся из `bookings.book_date`, потому что в `tickets` нет собственного поля времени изменения. +--- + +## Спецификации для реализации (для LLM и разработчиков) + +### Ключевые договорённости + +- **Источник**: используем основные таблицы схемы `bookings` (табличные данные, не `VIEW`) +- **Зерно факта `fact.flight_sales`**: 1 строка = 1 сегмент билета (`ticket_no` + `flight_id`, источник: `segments`) +- **Обязательная связь для аэропортов и самолёта**: `flights.route_no → routes → (departure_airport, arrival_airport, airplane_code)` +- **Даты**: как минимум различаем `book_date` (дата покупки) и `scheduled_departure` (дата/время вылета) +- **Инкремент в STG**: для `tickets` опорная дата берётся из `bookings.book_date`, потому что в `tickets` нет собственного поля времени изменения ### Статус реализации по слоям @@ -20,10 +28,64 @@ |------|--------|-------------| | **Source** | ✅ Готово | Демо-БД bookings (Postgres) | | **STG** | ⚠️ В процессе | 2 из 9 таблиц (bookings, tickets) | -| **DQ** | ⚠️ В процессе | Есть скрипты для bookings и tickets | | **ODS** | ❌ Не реализован | Планируется | | **DDS** | ❌ Не реализован | Планируется | +### Архитектура слоёв + +#### STG (Staging Layer) +- **Назначение**: Сырой слой, максимально близкий к источнику, без бизнес-логики +- **Хранение**: AO-Row (Append-Only Row-oriented) для эффективной загрузки больших объёмов +- **Типы данных**: Бизнес-колонки как `TEXT`, тех.колонки как `TIMESTAMP` +- **Инкрементальная загрузка**: Опорное поле `src_created_at_ts` (из `book_date` для tickets) +- **Технологические колонки**: + - `src_created_at_ts TIMESTAMP` — дата/время из источника для инкремента + - `load_dttm TIMESTAMP NOT NULL DEFAULT now()` — когда запись была загружена + - `batch_id TEXT NOT NULL` — идентификатор пачки (например, `{{ ds_nodash }}`) + +#### ODS (Operational Data Store) +- **Назначение**: Очищенные данные в 3NF, готовые для аналитики +- **Хранение**: Heap для частых чтений и обновлений +- **Трансформации**: Очистка, приведение типов, нормализация +- **Связи**: Все связи через бизнес-ключи (без суррогатных ключей) + +#### DDS (Data Delivery System) +- **Назначение**: Star Schema для аналитики и отчётности +- **Хранение**: Heap или AO-CO (Append-Only Column-oriented) для аналитических запросов +- **Структура**: Измерения (Dimensions) + Факты (Facts) +- **Ключи**: Суррогатные ключи (SK) для измерений, FK в фактах + +### Измерения DDS (Dimensions) + +| Измерение | Бизнес-ключ | Суррогатный ключ | Атрибуты | +|-----------|-------------|------------------|----------| +| `dim.calendar` | `date DATE` | `calendar_sk INT` | `year`, `month`, `day`, `day_of_week`, `is_holiday` | +| `dim.airports` | `airport_code CHAR(3)` | `airport_sk INT` | `airport_name`, `city`, `timezone`, `coordinates` | +| `dim.airplanes` | `airplane_code TEXT` | `airplane_sk INT` | `model`, `total_seats`, `range_km` | +| `dim.tariffs` | `fare_conditions TEXT` | `tariff_sk INT` | `fare_conditions` (Economy/Comfort/Business) | +| `dim.passengers` | `passenger_id TEXT` | `passenger_sk INT` | `passenger_name` (SCD Type 1) | + +### Факт DDS (Fact) + +`fact.flight_sales`: +- **Зерно**: 1 строка = 1 сегмент билета (`ticket_no` + `flight_id`) +- **FK на измерения**: + - `calendar_sk` — ссылка на дату вылета + - `departure_airport_sk` — аэропорт вылета + - `arrival_airport_sk` — аэропорт прилёта + - `airplane_sk` — самолёт + - `tariff_sk` — тариф + - `passenger_sk` — пассажир +- **Метрики**: + - `price NUMERIC` — стоимость сегмента + - `is_boarded BOOLEAN` — сел ли пассажир в самолёт (из boarding_passes) +- **Атрибуты**: + - `book_ref TEXT` — бизнес-ключ бронирования + - `book_date DATE` — дата покупки + - `ticket_no TEXT` — номер билета + - `flight_id INT` — ID рейса + - `seat_no TEXT` — место (если есть) + --- ## Полная схема потоков данных (Data Lineage) @@ -33,7 +95,6 @@ graph LR %% Стили classDef source fill:#e1f5fe,stroke:#01579b,stroke-width:2px; classDef stg fill:#fff9c4,stroke:#fbc02d,stroke-width:2px; - classDef dq fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px; classDef ods fill:#e0f2f1,stroke:#00695c,stroke-width:2px; classDef dim fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px; classDef fact fill:#ffccbc,stroke:#bf360c,stroke-width:4px; @@ -77,24 +138,7 @@ graph LR SRC_Segments --> STG_Segments SRC_Boarding --> STG_Boarding - %% 3. DATA QUALITY (Quality Checks) - subgraph DQ_Layer [Layer: DQ Data Quality] - direction TB - DQ_Bookings[dq.bookings_checks]:::dq - DQ_Tickets[dq.tickets_checks]:::dq - DQ_Routes[dq.routes_checks]:::dq - DQ_Flights[dq.flights_checks]:::dq - DQ_Segments[dq.segments_checks]:::dq - end - - %% Links STG to DQ - STG_Bookings --> DQ_Bookings - STG_Tickets --> DQ_Tickets - STG_Routes --> DQ_Routes - STG_Flights --> DQ_Flights - STG_Segments --> DQ_Segments - - %% 4. ODS (3NF, Clean, Type, Heap) + %% 3. ODS (3NF, Clean, Type, Heap) subgraph ODS_Layer [Layer: ODS Operational Core] direction TB ODS_Airports[ods.airports]:::ods @@ -108,18 +152,18 @@ graph LR ODS_Boarding[ods.boarding_passes]:::ods end - %% Links DQ to ODS - DQ_Bookings --> ODS_Bookings - DQ_Tickets --> ODS_Tickets - DQ_Routes --> ODS_Routes - DQ_Flights --> ODS_Flights - DQ_Segments --> ODS_Segments + %% Links STG to ODS STG_Airports --> ODS_Airports STG_Airplanes --> ODS_Airplanes + STG_Routes --> ODS_Routes STG_Seats --> ODS_Seats + STG_Bookings --> ODS_Bookings + STG_Tickets --> ODS_Tickets + STG_Flights --> ODS_Flights + STG_Segments --> ODS_Segments STG_Boarding --> ODS_Boarding - %% 5. DDS (Star Schema) + %% 4. DDS (Star Schema) subgraph DDS_Layer [Layer: DDS Star Schema] direction TB @@ -165,24 +209,41 @@ graph LR --- -## Пояснения к схеме (для студентов) +## Обучающие материалы (для студентов) + +### Глоссарий ключевых терминов + +| Термин | Объяснение | +|--------|-----------| +| **Зерно факта (Fact Grain)** | Минимальная единица измерения в факте. Для `fact.flight_sales` — это один сегмент билета. | +| **Суррогатный ключ (Surrogate Key, SK)** | Технический ключ (обычно INT), который генерируется в DWH и не зависит от бизнес-ключа. | +| **Бизнес-ключ (Business Key)** | Ключ из источника (например, `airport_code`, `passenger_id`). | +| **Star Schema** | Модель данных, где факт в центре, а измерения вокруг него (как звезда). | +| **SCD Type 1** | Slowly Changing Dimension Type 1: при изменении данных просто перезаписываем старую запись. | +| **SCD Type 2** | Slowly Changing Dimension Type 2: при изменении данных создаём новую запись с датой начала/действия. | +| **AO-Row** | Append-Only Row-oriented: хранение данных по строкам, только добавление (без UPDATE/DELETE). | +| **Heap** | Обычное хранение данных (как в обычной таблице), поддерживает UPDATE/DELETE. | +| **Инкрементальная загрузка** | Загрузка только новых/изменённых данных за период, а не всей таблицы. | + +### Пояснения к схеме Эта диаграмма покрывает основные таблицы источника и показывает логику их трансформации. Вот на что стоит обратить внимание при обучении: -### 1. Ветка справочников (Reference Data) +#### 1. Ветка справочников (Reference Data) -* **`seats` + `airplanes` → `dim.airplanes`**: Здесь мы показываем пример **обогащения**. Таблица `seats` сама по себе в аналитике редко нужна отдельной сущностью. Мы используем её в ODS, чтобы посчитать общее количество мест (`total_seats`) и добавить это как атрибут в измерение самолётов (`dim.airplanes`). +**`seats` + `airplanes` → `dim.airplanes`**: Здесь мы показываем пример **обогащения**. Таблица `seats` сама по себе в аналитике редко нужна отдельной сущностью. Мы используем её в ODS, чтобы посчитать общее количество мест (`total_seats`) и добавить это как атрибут в измерение самолётов (`dim.airplanes`). -* **`airports` → `dim.airports`**: Простой перенос (1-в-1), но в DDS мы можем добавить, например, поле `city_ru` и `city_en` как отдельные колонки, убрав JSON, который есть в источнике. +**`airports` → `dim.airports`**: Простой перенос (1-в-1), но в DDS мы можем добавить, например, поле `city_ru` и `city_en` как отдельные колонки, убрав JSON, который есть в источнике. -### 2. Ветка генерации измерений (Dimension Generation) +#### 2. Ветка генерации измерений (Dimension Generation) -* **`tickets` → `dim.passengers`**: Это самая сложная трансформация для измерения. В источнике нет таблицы "Пассажиры". Мы должны объяснить студентам, что мы "майним" пассажиров из билетов. Важно: один и тот же пассажир может иметь разные записи с разными именами (опечатки, изменение фамилии), поэтому в проде часто делают логику SCD Type 2 для отслеживания изменений. - - Для домашки (и первого эталонного решения) обычно достаточно **SCD Type 1**: одна актуальная запись на `passenger_id`, а SCD2 можно оставить как усложнение. +**`tickets` → `dim.passengers`**: Это самая сложная трансформация для измерения. В источнике нет таблицы "Пассажиры". Мы должны объяснить студентам, что мы "майним" пассажиров из билетов. Важно: один и тот же пассажир может иметь разные записи с разными именами (опечатки, изменение фамилии), поэтому в проде часто делают логику SCD Type 2 для отслеживания изменений. -* **`segments` → `dim.tariffs`**: Таблицы тарифов физически нет в источнике, она хранится строкой (`fare_conditions`: Economy/Comfort/Business) в таблице `segments`. Мы выносим её в отдельный справочник (нормализация), чтобы в факте хранить маленький `INT` ключ, а не длинную строку. +- Для домашки (и первого эталонного решения) обычно достаточно **SCD Type 1**: одна актуальная запись на `passenger_id`, а SCD2 можно оставить как усложнение. -### 3. Сборка Факта (`fact.flight_sales`) +**`segments` → `dim.tariffs`**: Таблицы тарифов физически нет в источнике, она хранится строкой (`fare_conditions`: Economy/Comfort/Business) в таблице `segments`. Мы выносим её в отдельный справочник (нормализация), чтобы в факте хранить маленький `INT` ключ, а не длинную строку. + +#### 3. Сборка Факта (`fact.flight_sales`) Это центр звезды. Мы собираем его из шести ODS таблиц: @@ -193,9 +254,9 @@ graph LR 5. **`ods.routes`**: Приджойниваем по `route_no`, чтобы получить аэропорты вылета/прилёта и `airplane_code` (в `flights` этих полей нет напрямую). 6. **`ods.boarding_passes`**: Приджойниваем (LEFT JOIN), чтобы узнать, **сел ли пассажир реально в самолёт** и на какое место (`seat_no`). Это важный бизнес-аспект: билет куплен, но посадочный не выдан = пассажир не летел. -### 4. Почему нет `dim.bookings`? +#### 4. Почему нет `dim.bookings`? -В классической Star Schema измерения — это справочники (airports, airplanes, passengers), а факты — транзакции/события (sales, bookings). +В классической Star Schema измерения — это справочники (airports, airplanes, passengers), а факты — транзакции/события (sales, bookings). `bookings` — это транзакционная таблица, а не справочник. Вместо отдельного измерения `dim.bookings` мы храним: - `book_ref` — бизнес-ключ бронирования (в факте) @@ -203,7 +264,7 @@ graph LR Это позволяет отвечать на вопросы типа: *"За сколько дней до вылета люди обычно покупают билеты?"* (разница между `book_date` и датой вылета из `dim.calendar`). -### 5. Суррогатные ключи (Surrogate Keys) +#### 5. Суррогатные ключи (Surrogate Keys) В Star Schema факт должен ссылаться на суррогатные ключи (SK) измерений, а не на бизнес-ключи: @@ -213,13 +274,14 @@ graph LR | `airplane_code TEXT` | `airplane_sk INT` | Меньший размер, стабильность | | `passenger_id TEXT` | `passenger_sk INT` | Меньший размер, отслеживание изменений | -### 6. Слой DQ (Data Quality) +--- -Между STG и ODS добавлен слой Data Quality для проверки качества данных. В проекте уже есть скрипты: -- `sql/stg/bookings_dq.sql` -- `sql/stg/tickets_dq.sql` +## Связанные документы -На схеме показаны примеры проверок для всех таблиц, которые должны быть реализованы. +- [`docs/internal/bookings_stg_design.md`](docs/internal/bookings_stg_design.md) — Детальный дизайн STG слоя для bookings +- [`docs/internal/bookings_tz.md`](docs/internal/bookings_tz.md) — Работа с часовыми поясами в источнике +- [`docs/internal/pxf_bookings.md`](docs/internal/pxf_bookings.md) — Настройка PXF для чтения из bookings-db +- [`TESTING.md`](TESTING.md) — Пошаговый чек-лист для тестирования стенда --- @@ -227,6 +289,7 @@ graph LR | Дата | Версия | Описание изменений | |------|--------|-------------------| +| 2025-01-17 | 2.0 | Удалён слой DQ для упрощения учебного стенда. Добавлены спецификации для LLM и обучающие материалы для студентов. Добавлен глоссарий терминов. | | 2025-01-17 | 1.1 | Исправлены названия таблиц (`aircrafts_data` → `airplanes_data`, `ticket_flights` → `segments`), удалено `dim.bookings`, добавлены суррогатные ключи, добавлен слой DQ, исправлены связи | | 2025-01-XX | 1.0 | Первоначальная версия | @@ -235,7 +298,6 @@ graph LR ## TODO - [ ] Реализовать STG слой полностью (все 9 таблиц) -- [ ] Реализовать DQ слой для всех таблиц - [ ] Реализовать ODS слой - [ ] Реализовать DDS слой (измерения и факт) - [ ] Создать DAG для загрузки ODS