refactor(sql): reorganize sql files into structured directory hierarchy
Move DDL files from flat ddl/ directory to sql/ddl/ with layer-based subdirectories (stg, ods, dds, dm). Move batch transformation SQL from jobs/ to sql/ layer directories. Update scripts and documentation to reflect new paths for improved organization and Airflow integration.
This commit is contained in:
+10
-10
@@ -7,7 +7,7 @@
|
||||
- В `AGENTS.md` как quick check ожидается DAG `etl_pipeline`.
|
||||
- В Airflow-контейнере сейчас нет Kafka CLI, поэтому `kafka-topics.sh` и `kafka-console-producer.sh` из `BashOperator` не используем.
|
||||
- DDL должен выполняться строго последовательно: `00 -> 10 -> 20 -> 30 -> 40`.
|
||||
- Файл `jobs/30_dds_refresh.sql` уже включает обе загрузки (`dds.click` и `dds.event`), поэтому в MVP это одна task.
|
||||
- Файл `sql/dds/30_ods_to_dds.sql` уже включает обе загрузки (`dds.click` и `dds.event`), поэтому в MVP это одна task.
|
||||
|
||||
## Архитектура оркестрации
|
||||
### DAG 1 (обязательный): `ddl_init`
|
||||
@@ -44,11 +44,11 @@
|
||||
| Task ID | Что делает | Источник SQL/реализация |
|
||||
|---------|------------|--------------------------|
|
||||
| `check_clickhouse` | Проверка доступности CH (`SELECT 1`) | `PythonOperator` + `clickhouse-connect` |
|
||||
| `ddl_00_databases` | Создание БД | `ddl/00_databases.sql` |
|
||||
| `ddl_10_stg` | STG + Kafka Engine + MV | `ddl/10_stg.sql` |
|
||||
| `ddl_20_ods` | ODS + MV STG→ODS + *_errors | `ddl/20_ods.sql` |
|
||||
| `ddl_30_dds` | Таблицы DDS | `ddl/30_dds.sql` |
|
||||
| `ddl_40_dm` | VIEW витрины DM | `ddl/40_dm.sql` |
|
||||
| `ddl_00_databases` | Создание БД | `sql/ddl/00_databases.sql` |
|
||||
| `ddl_10_stg` | STG + Kafka Engine + MV | `sql/ddl/stg/10_stg.sql` |
|
||||
| `ddl_20_ods` | ODS + MV STG→ODS + *_errors | `sql/ddl/ods/20_ods.sql` |
|
||||
| `ddl_30_dds` | Таблицы DDS | `sql/ddl/dds/30_dds.sql` |
|
||||
| `ddl_40_dm` | VIEW витрины DM | `sql/ddl/dm/40_dm.sql` |
|
||||
| `verify_schema` | Проверка ключевых таблиц/VIEW | SQL-check |
|
||||
|
||||
Зависимости:
|
||||
@@ -113,14 +113,14 @@ precheck >> prepare_topics >> [load_browser_events, load_location_events, load_d
|
||||
| `check_ods_quality` | Базовые DQ-метрики ODS (ошибки/total) | SQL-check |
|
||||
| `truncate_dds_click` | Очистка `dds.click` при `full_refresh=true` | inline SQL |
|
||||
| `truncate_dds_event` | Очистка `dds.event` при `full_refresh=true` | inline SQL |
|
||||
| `refresh_dds` | ODS → DDS | `jobs/30_dds_refresh.sql` |
|
||||
| `load_dds` | ODS → DDS | `sql/dds/30_ods_to_dds.sql` |
|
||||
| `check_dds_integrity` | Проверка orphan событий | inline SQL |
|
||||
| `refresh_dm_summary` | DDS → DM DQ summary | `jobs/40_dm_refresh.sql` |
|
||||
| `load_dm_summary` | DDS → DM DQ summary | `sql/dm/40_dds_to_dm.sql` |
|
||||
| `validate_dm_summary` | Проверка, что `dm.dq_summary` не пуста | SQL-check |
|
||||
|
||||
Зависимости:
|
||||
```text
|
||||
wait_for_ods_data >> check_ods_quality >> [truncate_dds_click, truncate_dds_event] >> refresh_dds >> check_dds_integrity >> refresh_dm_summary >> validate_dm_summary
|
||||
wait_for_ods_data >> check_ods_quality >> [truncate_dds_click, truncate_dds_event] >> load_dds >> check_dds_integrity >> load_dm_summary >> validate_dm_summary
|
||||
```
|
||||
|
||||
### Итоговая цепочка `etl_pipeline`
|
||||
@@ -230,5 +230,5 @@ docker compose exec -T clickhouse clickhouse-client --user=default --password=12
|
||||
```
|
||||
|
||||
## Следующий шаг после MVP
|
||||
- Разделить `jobs/30_dds_refresh.sql` на два файла и распараллелить `refresh_dds_click` и `refresh_dds_event`.
|
||||
- Разделить `sql/dds/30_ods_to_dds.sql` на два файла и распараллелить `load_dds_click` и `load_dds_event`.
|
||||
- Перейти с `full_refresh` на watermark-инкремент.
|
||||
|
||||
+13
-13
@@ -114,32 +114,32 @@ flowchart LR
|
||||
|
||||
## План актуализации DDL (target state репозитория)
|
||||
|
||||
Цель: перестать исполнять DDL из markdown и хранить **исполняемые** DDL в отдельных `ddl/*.sql` (по слоям), чтобы:
|
||||
Цель: перестать исполнять DDL из markdown и хранить **исполняемые** DDL в отдельных `sql/*/*.sql` (по слоям), чтобы:
|
||||
|
||||
- применять их “тонким раннером” через `clickhouse-client` (через `make ddl`);
|
||||
- в будущем легко перенести выполнение в Airflow (1 файл = 1 task, линейные зависимости).
|
||||
|
||||
Важно: Kafka-объекты STG включаем **по умолчанию** (как часть `ddl/10_stg.sql`).
|
||||
Важно: Kafka-объекты STG включаем **по умолчанию** (как часть `sql/ddl/stg/10_stg.sql`).
|
||||
|
||||
### Артефакты DDL (планируемые файлы)
|
||||
|
||||
- `ddl/00_databases.sql` — базы `stg/ods/dds/dm`.
|
||||
- `ddl/10_stg.sql` — STG raw (`stg.*_raw`) + Kafka source tables (`ENGINE = Kafka`) + MV `Kafka → STG`.
|
||||
- `ddl/20_ods.sql` — ODS таблицы типизации + DQ (`parse_errors`) + MV `STG → ODS` + таблицы `ods_*_errors` для строк с битыми ключами.
|
||||
- `ddl/30_dds.sql` — DDS таблицы (`dds.event`, `dds.click`) **без MV** (только `CREATE TABLE`).
|
||||
- `ddl/40_dm.sql` — витрины `VIEW` для Superset (`dm.v_*`).
|
||||
- `sql/ddl/00_databases.sql` — базы `stg/ods/dds/dm`.
|
||||
- `sql/ddl/stg/10_stg.sql` — STG raw (`stg.*_raw`) + Kafka source tables (`ENGINE = Kafka`) + MV `Kafka → STG`.
|
||||
- `sql/ddl/ods/20_ods.sql` — ODS таблицы типизации + DQ (`parse_errors`) + MV `STG → ODS` + таблицы `ods_*_errors` для строк с битыми ключами.
|
||||
- `sql/ddl/dds/30_dds.sql` — DDS таблицы (`dds.event`, `dds.click`) **без MV** (только `CREATE TABLE`).
|
||||
- `sql/ddl/dm/40_dm.sql` — витрины `VIEW` для Superset (`dm.v_*`).
|
||||
|
||||
BI-ограничения (ресурсы/пользователь) **не выносим в `ddl/*.sql`**: оставляем это только как текст/пример в этом плане, чтобы не смешивать инфраструктуру доступа с DDL витрин.
|
||||
BI-ограничения (ресурсы/пользователь) **не выносим в `sql/*/*.sql`**: оставляем это только как текст/пример в этом плане, чтобы не смешивать инфраструктуру доступа с DDL витрин.
|
||||
|
||||
### Артефакты batch-трансформаций (планируемые файлы)
|
||||
|
||||
- `jobs/30_dds_refresh.sql` — регулярная батч‑сборка DDS из ODS:
|
||||
- `sql/dds/30_ods_to_dds.sql` — регулярная батч‑сборка DDS из ODS:
|
||||
- получить “последнюю версию” строк по ключам (`event_id`/`click_id`) через `argMax(..., src_ingest_ts)` (или эквивалент);
|
||||
- выполнить join snapshot’ов и загрузить в `dds.event`/`dds.click` (для демо возможно “full rebuild”; позже — инкрементально).
|
||||
|
||||
### Исполнение DDL (make сейчас / Airflow потом)
|
||||
|
||||
Требования к файлам `ddl/*.sql`:
|
||||
Требования к файлам `sql/*/*.sql`:
|
||||
|
||||
- идемпотентность (`IF NOT EXISTS`), чтобы повторные прогоны были безопасны;
|
||||
- строгий порядок исполнения: `00 → 10 → 20 → 30 → 40` (из‑за зависимостей MV);
|
||||
@@ -163,11 +163,11 @@ BI-ограничения (ресурсы/пользователь) **не вы
|
||||
Текущее “как запускаем” (целевое, для реализации следующим шагом):
|
||||
|
||||
- `make ddl` вызывает `scripts/apply_clickhouse_ddl.sh`;
|
||||
- скрипт прогоняет `ddl/*.sql` по порядку через `clickhouse-client --multiquery` внутри контейнера ClickHouse.
|
||||
- скрипт прогоняет `sql/*/*.sql` по порядку через `clickhouse-client --multiquery` внутри контейнера ClickHouse.
|
||||
|
||||
Batch‑трансформации (целевое, для реализации следующим шагом):
|
||||
|
||||
- `make transform` (или аналогичная команда) запускает `jobs/30_dds_refresh.sql` через `clickhouse-client`;
|
||||
- `make transform` (или аналогичная команда) запускает `sql/dds/30_ods_to_dds.sql` через `clickhouse-client`;
|
||||
- в будущем Airflow будет делать то же самое по расписанию (один job‑SQL = один task).
|
||||
|
||||
### Параметры окружения (docker compose)
|
||||
@@ -178,7 +178,7 @@ Batch‑трансформации (целевое, для реализации
|
||||
|
||||
---
|
||||
|
||||
## Приложение A: текущий inline DDL (legacy; будет вынесен в `ddl/*.sql`)
|
||||
## Приложение A: текущий inline DDL (legacy; будет вынесен в `sql/*/*.sql`)
|
||||
|
||||
### 0) Базы данных
|
||||
|
||||
|
||||
Reference in New Issue
Block a user