ddmitry/clickstream-ch-kafka-superset-demo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(sql): reorganize sql files into structured directory hierarchy

Browse Source 
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:
ddadmin
2026-02-07 20:51:51 +03:00
parent 6466921bda
commit 9e340bb729
14 changed files with 95 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plans/clickhouse_ddl.md
+13 -13
View File
@@ -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) Базы данных