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

Учебный стенд DWH кликстрима

Живой стек для работы с кликстримом: Kafka, ClickHouse, Airflow, Superset и мониторинг (Prometheus с Grafana) поднимаются в Docker одной командой. На этом стенде можно учиться по курсу или просто поднять его у себя и поэкспериментировать с потоковой загрузкой и витринами.

Поток данных коротко: data/*.jsonl → Airflow (kafka_load) → Kafka → ClickHouse (слой STG) → Airflow (etl_pipeline: STG → ODS → DDS → DM) → Superset.

Куда дальше

• Хочешь учиться — открой курс «Кликстрим на ClickHouse». Это продвинутый курс «со звёздочкой»: основные приёмы инженерии данных проходишь прямо на этом стенде.
• Хочешь поднять и попробовать — следуй быстрому старту ниже.
• Хочешь разобраться в устройстве — смотри архитектуру слоёв, запуск и эксплуатацию и карту репозитория.

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

Стенд управляется через Airflow — это основной рабочий способ. Отдельные shell-скрипты в scripts/ оставлены как запасной вариант для локальных прогонов (см. OPERATIONS).

# 1. Поднять весь стек
make up
docker compose ps   # убедиться, что контейнеры запустились

Дальше — три шага в Airflow (веб-интерфейс http://localhost:8080, логин и пароль admin/admin). Сними каждый DAG с паузы (кнопка Unpause) и запусти по очереди:

1. ddl_init — создаёт базы, таблицы и представления в ClickHouse.
2. kafka_load — заливает события из data/*.jsonl в Kafka.
3. etl_pipeline — прогоняет цепочку STG → ODS → DDS → DM.

Те же шаги можно запускать из командной строки — это удобно для скриптов:

docker compose exec -T airflow-webserver airflow dags trigger ddl_init

# Загрузить первые 100 строк каждого файла (limit=0 — загрузить всё)
docker compose exec -T airflow-webserver airflow dags trigger kafka_load \
  --conf '{"limit": 100, "reset_topics": true}'

docker compose exec -T airflow-webserver airflow dags trigger etl_pipeline \
  --conf '{"full_refresh": true}'

Проверить, что данные дошли до витрин:

docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 \
  --query "SELECT count() FROM dm.v_events_enriched"

Подробный сценарий запуска, параметры DAG-ов и разбор частых проблем — в OPERATIONS.

Сервисы и доступы

Сервис	Адрес	Назначение	Логин/пароль
Airflow	http://localhost:8080	оркестрация ETL	admin/admin
ClickHouse	http://localhost:9123/play	SQL-запросы	default/123456
Kafka UI	http://localhost:8082	просмотр топиков	—
Superset	http://localhost:8088	дашборды	admin/admin
Prometheus	http://localhost:9090	метрики	—
Grafana	http://localhost:3000	графики метрик	admin/admin

Готовый дашборд в Superset: http://localhost:8088/superset/dashboard/ecommerce-analytics/ — он создаётся автоматически через минуту-две после make up. Состав и настройка дашборда описаны в SUPERSET_DASHBOARD.

Как устроен поток данных

flowchart LR
    subgraph AF["Airflow"]
        D1["ddl_init"]
        D2["kafka_load"]
        D3["etl_pipeline"]
    end

    subgraph Kafka["Kafka"]
        Topics[4 топика]
    end

    subgraph CH["ClickHouse"]
        STG["STG: сырые данные"]
        ODS["ODS: типизация + DQ"]
        DDS["DDS: сущности"]
        DM["DM: витрины VIEW"]
    end

    D2 -->|загрузка JSONL| Kafka -->|Kafka MV| STG
    STG -->|batch| ODS -->|batch| DDS -->|VIEW| DM

    D1 -.->|DDL| CH
    D3 -.->|batch| ODS & DDS

«Грязные» записи не роняют пайплайн: ошибки разбора складываются в ods.*_errors и в поле parse_errors, а обработка продолжается.

Подробное описание слоёв STG/ODS/DDS/DM, диаграммы и обоснование решений — в ARCHITECTURE.

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

• Архитектура и слои — устройство STG/ODS/DDS/DM, диаграммы, обоснование решений.
• Запуск и эксплуатация — сценарий запуска, параметры DAG-ов, мониторинг, частые проблемы.
• Карта репозитория — где какие файлы и что менять.
• Курс «Кликстрим на ClickHouse» — учебная программа на этом стенде.
• DE-task.md — задание, из которого вырос стенд.