clickstream-ch-kafka-superset-demo/README.md

ClickHouse Mini DWH для кликстрима

Многослойное хранилище данных (STG → ODS → DDS → DM) для анализа кликстрима e-commerce.

Данные поступают из Kafka, проходят типизацию и обогащение, формируя витрины для BI-аналитики.

Соответствие заданию: Реализован полный цикл Data Engineering: ingestion → хранилище со слоями → регулярный процесс трансформации → витрины для дашборда.

---

🚀 Быстрый старт

# 1. Поднять инфраструктуру (Kafka + ClickHouse + Superset)
make up

# 2. Создать структуру БД
make ddl

# 3. Загрузить данные (автоматически потекут STG → ODS)
make data           # первые 50 строк
# или: FULL=1 make data   # полный датасет (1000 строк)

# 4. Подождать 5-10 сек (данные проходят через Kafka)
sleep 10

# 5. Запустить batch-трансформацию (ODS → DDS → DM)
make transform

Проверка:

# Статистика по слоям
docker compose exec clickhouse clickhouse-client \
  --user=default --password=123456 --query="
    SELECT database, countDistinct(table) AS tables, sum(rows) AS rows
    FROM system.parts WHERE database IN ('stg','ods','dds','dm')
    GROUP BY database ORDER BY database
"

# Пример запроса к витрине
docker compose exec clickhouse clickhouse-client \
  --user=default --password=123456 --query="
    SELECT * FROM dm.v_utm_effectiveness ORDER BY clicks DESC LIMIT 5
"

---

📊 Доступные сервисы

Сервис	URL	Назначение
ClickHouse HTTP	http://localhost:9123/play	SQL-запросы
Kafka UI	http://localhost:8082	Просмотр топиков
Airflow	http://localhost:8080	Оркестрация ETL (admin/admin)
Superset	http://localhost:8088	BI-дашборды
Prometheus	http://localhost:9090	Метрики
Grafana	http://localhost:3000	Визуализация метрик

---

🏗️ Архитектура

flowchart TB
    subgraph Sources["📁 JSON файлы"]
        BE[browser_events.jsonl]
        LE[location_events.jsonl]
        DE[device_events.jsonl]
        GE[geo_events.jsonl]
    end

    subgraph Kafka["🚀 Kafka"]
        KT[Топики]
    end

    subgraph CH["🗄️ ClickHouse"]
        STG["STG — сырые JSON"]
        ODS["ODS — типизированные"]
        DDS["DDS — сущности"]
        DM["DM — витрины"]
    end

    subgraph Airflow["⚙️ Airflow"]
        DAG[ETL DAGs]
    end

    Sources -->|make data| Kafka -->|MV| STG -->|MV| ODS -->|Batch SQL| DDS -->|VIEW| DM
    DAG -.->|оркестрация| ODS & DDS & DM

Поток данных:

1. STG — сырые JSON из Kafka (MergeTree)
2. ODS — типизированные данные + DQ (ReplacingMergeTree)
3. DDS — собранные сущности event + click (Batch SQL)
4. DM — витрины для BI (VIEW)

Подробное описание архитектуры →

---

📁 Структура проекта

.
├── dags/             # Airflow DAGs для оркестрации
├── sql/
│   ├── ddl/          # DDL по слоям
│   │   ├── 00_databases.sql
│   │   ├── stg/10_stg.sql
│   │   ├── ods/20_ods.sql
│   │   ├── dds/30_dds.sql
│   │   └── dm/40_dm.sql
│   ├── dds/          # Batch SQL: ODS -> DDS
│   └── dm/           # Batch SQL: DDS -> DM
├── scripts/          # Автоматизация (apply ddl, load data, run batch)
├── airflow/          # Конфигурация Airflow
│   └── requirements.txt
├── docs/             # Документация
│   └── ARCHITECTURE.md   # Подробное описание слоёв
├── data/             # Исходные JSONL файлы
├── docker-compose.yml
└── Makefile          # Команды: up, ddl, data, transform

---

🛠️ Команды Makefile

Команда	Описание
make up	Поднять инфраструктуру
make ddl	Создать структуру БД
make data	Загрузить данные в Kafka (50 строк)
FULL=1 make data	Загрузить полный датасет
make transform	Запустить batch-процесс

---

🔗 Ключи данных

flowchart LR
    subgraph Sources["Источники"]
        BE["browser_events (event_id, click_id)"]
        LE["location_events (event_id)"]
        DE["device_events (click_id)"]
        GE["geo_events (click_id)"]
    end

    subgraph DDS["DDS"]
        EV["event (event_id PK)"]
        CL["click (click_id PK)"]
    end

    subgraph DM["DM"]
        V1[v_events_enriched]
        V2[v_daily_traffic]
        V3[v_utm_effectiveness]
    end

    BE -->|event_id| EV
    LE -->|event_id| EV
    BE -->|click_id| CL
    DE -->|click_id| CL
    GE -->|click_id| CL
    
    EV -->|LEFT JOIN click_id| V1
    CL --> V1
    EV --> V2 & V3
    CL --> V2 & V3

---

📚 Документация

• Архитектура и слои — подробное описание STG/ODS/DDS/DM, ER-диаграммы, обоснование решений
• DE-task.md — исходное задание

---

🎯 Дашборд в Superset

1. Открыть http://localhost:8088
2. Database → Add:
   • URI: clickhouse+connect://default:123456@clickhouse:8123/default
3. Datasets → Add from dm.v_*
4. Charts & Dashboard

Основные витрины:

• v_events_enriched — полное обогащение
• v_daily_traffic — агрегация по дням
• v_utm_effectiveness — эффективность кампаний
• v_top_pages_daily — воронка страниц

---

🔮 Развитие проекта

✅ Реализовано

• Airflow — оркестрация batch-процесса (инфраструктура готова, DAGs в разработке)

📋 В планах

• Инкрементальный batch — watermark-based загрузка
• Материализация витрин — для тяжёлых агрегаций
• DQ мониторинг — алерты на ошибки парсинга

---

📝 Лицензия

Проект создан для образовательных целей в рамках DE-тестового задания.