mini-lakehouse-lab/docs/mentor_notes.md

Заметки для ментора

Этот документ — для ведения курса с ментором. Студенту он не нужен.

Формат работы

Менти работает преимущественно самостоятельно. Ноутбуки написаны так, чтобы студент мог пройти демо-часть и самостоятельные задания без посторонней помощи.

Роль ментора:

• задать направление — обозначить, на что обратить внимание в модуле, какие параллели с текущим опытом студента искать;
• отвечать на вопросы — по ходу прохождения или на checkpoint-е;
• не вести за руку — не объяснять материал до того, как студент попробовал сам.

Типичный цикл: ментор даёт задание на модуль → менти проходит самостоятельно → встреча для обсуждения вопросов и checkpoint-а.

Ориентировочный тайминг

Модуль	Тема	Самостоятельная работа	Обсуждение с ментором	Комментарий
1	Вход в стенд	30-40 мин	10-15 мин	Если Docker знаком, идёт быстро
2	Ментальная модель	40-60 мин	15-20 мин	Ключевой модуль; убедись, что студент заходил в MinIO
3	Raw-данные	40-50 мин	10 мин	Зависит от скорости загрузки данных
4	Bronze + Iceberg	60-80 мин	15-20 мин	Первая таблица — много новых концепций
5	Silver	50-70 мин	15 мин	Трансформации + проверки качества
6	Spark + Trino	40-60 мин	15 мин	Если DBeaver настроен заранее — быстрее
7	Schema evolution, time travel	60-80 мин	15-20 мин	Rollback требует внимания
8	Обслуживание + финальная	80-120 мин	20-30 мин	Финальная практика занимает больше всего

Общий объём самостоятельной работы: ~12-15 часов. Время с ментором: ~2-2.5 часа суммарно (по 15-20 минут на модуль).

Типичные вопросы и затруднения

С чем студент, скорее всего, придёт к тебе.

Модуль 1. Вход в стенд

• Docker не хватает ресурсов. Стенд требует ~4-6 ГБ RAM. На машинах с 8 ГБ бывают проблемы. Решение: увеличить лимиты Docker Desktop или закрыть лишние приложения.
• Порты заняты. 8080, 8888, 9000 — популярные порты. docker compose ps покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в docker-compose.yml.
• Студент не читает START_HERE.md. Начинает с ноутбуков до поднятия стенда. Направь обратно к стартовому документу.

Модуль 2. Ментальная модель

• Путаница storage vs catalog. Студент думает, что MinIO — это база данных. Помогает аналогия: MinIO — это «диск», PostgreSQL — это «оглавление книги», Spark — это «читатель».
• «Зачем нужен отдельный каталог?» Объясни через decoupled compute: два движка могут работать с одними данными, только если есть общий реестр таблиц.
• Студент не заходит в MinIO Console. Без визуального осмотра файлов модель остаётся абстрактной. Попроси студента найти конкретные data files в MinIO.

Модуль 3. Raw-данные

• Путь к данным не совпадает. Студент скачал данные, но положил не в ./data/nyc_taxi/. Проверь монтирование: файлы должны быть видны внутри контейнера по пути /opt/data/nyc_taxi/.
• Ошибки чтения Parquet. Иногда файл скачивается не полностью. Решение: перекачать файл.
• Студент хочет «починить» raw-данные. Объясни принцип неизменяемости raw: чистка — задача следующих слоёв.

Модуль 4. Bronze + Iceberg

• Ошибки при CREATE TABLE. Обычно namespace не создан. Проверь, что CREATE NAMESPACE lakehouse.bronze выполнен.
• Студент не понимает разницу между Parquet-файлами и Iceberg-таблицей. Помогает осмотр MinIO: Iceberg-таблица содержит metadata/ с JSON и Avro-файлами, а не просто набор Parquet.
• Самостоятельное задание (taxi_zone_lookup) сложнее, чем кажется. CSV-файл требует чтения через spark.read.csv() с заголовками. Подсказка в ноутбуке есть, но студенты часто пропускают её.

Модуль 5. Silver

• Ошибки в трансформациях. Студент путает порядок операций (фильтрация до/после JOIN). Помоги разобрать логику пошагово.
• Не знает PySpark API. Если студент привык к чистому SQL, покажи эквивалентный SQL через spark.sql() — он поддерживается наравне с DataFrame API.
• Проверки качества кажутся «лишними». Объясни, что в production без проверок ошибки обнаруживаются на этапе отчётов, когда уже поздно.

Модуль 6. Spark + Trino

• Trino не видит таблицу. Обычно Trino не успел стартовать или каталог не настроен. Проверь docker compose logs trino и убедись, что контейнер healthy.
• DBeaver не подключается. Host: localhost, Port: 8090, User: любая строка, Password: пусто. Драйвер Trino встроен в DBeaver.
• «Зачем два движка, если Spark всё умеет?» В production Trino используется для ad hoc запросов аналитиками, которые не работают с Spark. Разделение ролей: Spark — ETL, Trino — BI/analytics.

Модуль 7. Schema evolution и time travel

• Студент путает schema evolution и data snapshot. ALTER TABLE ADD COLUMNS не создаёт новый data snapshot — это metadata-only операция. Snapshot создаётся только при изменении данных (INSERT, DELETE и т.д.).
• Time travel: забывает сохранить snapshot_id. Без сохранённого ID в переменную приходится заново запрашивать table.snapshots. Привычка: перед экспериментом запиши ID текущего состояния.
• rollback_to_snapshot vs CREATE OR REPLACE. Ключевое отличие: rollback сохраняет историю, CREATE OR REPLACE уничтожает её. Это описано в Секции 10 ноутбука.

Модуль 8. Обслуживание и финальная практика

• 8 INSERT-ов в демо-таблице идут медленно. Каждый INSERT запускает отдельный Spark job. На слабых машинах может занять 2-3 минуты. Это нормально.
• Студент запускает expire перед compaction. Порядок важен: сначала compaction, потом expire. Иначе старые мелкие файлы становятся «сиротами».
• Финальная практика: ошибка несовпадения колонок при INSERT. После ADD COLUMNS (processed_at) INSERT требует указания всех колонок, включая processed_at. Подсказка есть в описании шага 6.

Checkpoint-ы: как использовать

Checkpoint — не тест. Это повод для короткого разговора. Студент уже ответил на вопросы сам (они есть в ноутбуке), задача ментора — проверить понимание и дополнить, если нужно.

Что работает:

• Попросить объяснить своими словами, а не зачитать ответ. «Расскажи, как ты понимаешь, что такое snapshot» лучше, чем «что такое snapshot?».
• Связать с опытом студента. Параллели с PostgreSQL/Greenplum есть в каждом модуле — используй их.
• 3-4 вопросов достаточно. Если студент уверенно отвечает на первые, не нужно проходить весь список.
• Финальный checkpoint (Модуль 8) — самый важный. Часть B покрывает весь курс. Хороший признак: студент объясняет, почему Spark и Trino видят одну таблицу, без подсказок.

Если студент опытный

Некоторые модули можно ускорить для студентов с опытом в DE/DWH:

Модуль	Можно ускорить?	Что пропустить	Что нельзя пропускать
1	Да	Детальную диагностику Docker	Проверку, что все UI доступны
2	Частично	Базовые пояснения про storage/catalog	Практический осмотр MinIO и PostgreSQL
3	Да	Пояснения про raw-зону	Загрузку данных (без неё не работают Модули 4-8)
4	Нет	—	Создание таблицы и осмотр структуры Iceberg
5	Частично	Базовые трансформации	Проверки качества и принцип воспроизводимости
6	Нет	—	Практику с Trino (даже если студент знает Trino)
7	Нет	—	Time travel и rollback — ядро безопасной работы
8	Нет	—	Финальная практика — итоговая проверка всех навыков

Модули 4, 6, 7, 8 нельзя пропускать даже для опытных студентов. Они содержат ключевые практики, которые отличают «знаю теорию» от «умею делать руками».