Учебная дата-платформа кликстрима

Этим стендом можно пользоваться самостоятельно. Он также входит в план обучения Data Engineering Roadmap как курсовая работа. Если вам нужна помощь, обратитесь к автору материалов — ментору @dementev_dev.

Здесь вы будете работать с хранилищем данных небольшого интернет-магазина: загружать и обрабатывать данные в ClickHouse, строить витрины, проверять качество данных и создавать графики. Стенд рассчитан на тех, кто уже изучил основы ClickHouse и хочет попрактиковаться.

Генератор создает заказы и кликстрим — записи о действиях посетителей магазина. Данные поступают через Kafka в ClickHouse и проходят четыре слоя обработки: STG, ODS, DDS и DM. В кластере ClickHouse два шарда и отдельный ClickHouse Keeper. Airflow управляет загрузкой и обработкой, Superset показывает отчеты, а Prometheus и Grafana помогают следить за работой стенда.

При первом запуске стенд загрузит данные за неделю работы магазина. После запуска начните с путеводителя: он объясняет устройство хранилища. Затем переходите к учебным заданиям.

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

Для запуска нужны Docker с Compose, make, curl и jq. Выделите Docker около 8 ГБ оперативной памяти. В Docker Desktop и WSL2 проверьте лимит памяти виртуальной машины: он может быть меньше, чем общий объем памяти компьютера. Команда docker info --format '{{.MemTotal}}' покажет доступный Docker объем в байтах. В WSL2 лимит задается параметром memory в файле .wslconfig в домашнем каталоге пользователя Windows. После изменения выполните wsl --shutdown. Если ресурсов компьютера недостаточно, стенд можно запустить на VPS.

По умолчанию должны быть свободны порты 23000, 28080, 28088, 28123, 28124, 29000, 29001, 29090 и 29092. Для работы с командами make в каталоге generator/ также понадобится uv.

В каталоге репозитория скопируйте образец настроек:

cp .env.example .env

В .env задаются имя экземпляра стенда, внешние порты, учебные логины, пароли и ключи. Проверьте DOCKER_GID: это числовой идентификатор группы docker на вашей машине. Узнать его можно командой getent group docker. Если число отличается от образца, замените значение в .env. От этой настройки зависит запуск генератора из Airflow.

Запустите стенд:

make up

Команда запустит службы и дождется загрузки начальных данных. Порядок запуска и проверки результата описаны в справочнике проверок. Если обязательной настройки в .env не хватает, Compose сообщит об ошибке. Внутренние адреса служб, имена топиков и версии образов заданы в compose.yaml и Dockerfile.

Логины и пароли Postgres и Grafana сохраняются при первом запуске в томах Docker. Простая правка .env их не изменит. Чтобы задать новые значения через .env, потребуется make clean и повторный make up. При этом будут удалены все локальные данные стенда.

Адреса и пароли

С настройками из .env.example порты доступны только с локальной машины:

• узел ClickHouse 1 — http://127.0.0.1:28123, нативный порт 29000;
• узел ClickHouse 2 — http://127.0.0.1:28124, нативный порт 29001;
• Kafka — 127.0.0.1:29092;
• Airflow — http://127.0.0.1:28080, пользователь admin, пароль airflow;
• Superset — http://127.0.0.1:28088, пользователь admin, пароль superset;
• Prometheus — http://127.0.0.1:29090;
• Grafana — http://127.0.0.1:23000, пользователь admin, пароль admin.

Подробнее о службах, правах пользователей и изменении настроек — в справочнике стенда.

Добавить данные за следующие дни

Время в учебном магазине идет отдельно от календарного. В документации оно называется модельным временем, а сам магазин с его посетителями и заказами — миром.

В Airflow запустите world_next_day. Это даг — набор связанных задач, которые Airflow выполняет в заданном порядке. Он создаст и загрузит данные за следующий день работы магазина. В форме запуска можно задать число дней.

Чтобы новые данные поступали непрерывно, снимите с паузы даг world_live. Он будет запускать генерацию день за днем; один модельный день занимает около 24 минут. Подробности — в справочнике генератора и модельного времени.

Восстановить начальные данные

Если хотите начать заново, поставьте world_live на паузу и дождитесь завершения уже запущенного дага генерации. Затем выполните make rebuild-storage.

Команда удалит прикладные базы ClickHouse, топики и позиции потребителей Kafka, затем заново создаст схему хранилища и загрузит начальные данные. Службы и их тома останутся на месте.

Остановить или удалить стенд

make down остановит стенд и сохранит данные. Для повторного запуска выполните make up.

make clean удалит контейнеры и все данные в томах Docker. Для обычного завершения работы достаточно make down.

Подключиться из DBeaver

Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост 127.0.0.1, порт 28123, пользователя analyst и пароль из переменной CLICKHOUSE_ANALYST_PASSWORD в .env; в образце это analyst-26-reader. Для подключения ко второму узлу укажите порт 28124.

Пользователь analyst может читать данные во всех слоях и справочниках. Для заданий с собственными таблицами наблюдений используйте student и пароль из CLICKHOUSE_STUDENT_PASSWORD в .env. Он читает те же источники, а создавать, заполнять и удалять таблицы может только в базе default. Для создания учебных витрин используйте подключение, описанное в инструкции к заданиям. Нативные порты 29000 и 29001 нужны clickhouse-client, но не DBeaver. Остальные пользователи и роли описаны в справочнике стенда.

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

• docs/handbook/ — путеводитель по стенду и порядок чтения.
• docs/labs/ — учебные задания с порядком прохождения и самопроверкой.
• docs/specs/ — требования к стенду и программа обучения.
• docs/adr/ — решения об устройстве стенда: что выбрали, какие варианты отклонили и почему.
• docs/architecture/ — технические справочники:
  • хранилище — правила именования, распределение данных по шардам, прием событий и список таблиц.
  • конвейер — движение данных между слоями и работа дагов.
  • мир и модельное время — начальные данные, создание данных за следующие дни и управление генератором.
  • стенд — службы, доступ и настройка.
  • проверки — команды make для проверки стенда и правила добавления новых проверок.
  • мониторинг — сбор метрик и устройство дашборда.
  • Superset — подключения, наборы данных и автоматическая настройка при запуске.
• docs/research/ — исследования; сейчас это формат кликстрима Яндекса, по которому строится модель события.
• docs/formats/ — форматы исходных данных, необходимые для их загрузки и обработки. Эти документы собираются из кода командой make docs в generator/; вручную их менять не нужно.
• AGENTS.md — правила работы в репозитории для ИИ-агентов.