docs(course): добавлены glossary, mentor notes, шпаргалка и переписан README
- Зачем: - закрыты 3 вспомогательных артефакта из course_program.md §3.3: glossary, cheat sheet, mentor notes. - README переписан с фокусом на ценность для студента. - Что: - создан docs/glossary.md (16 терминов, сгруппированных по темам с параллелями к DWH). - создан docs/mentor_notes.md (тайминг, типичные вопросы, checkpoint-ы, формат «менти работает сам»). - добавлена секция «Краткая шпаргалка» в docs/stack_reference.md (S3-пути, таблицы, SQL-команды, маунты). - README.md переписан: лид с навыками, убрано дублирование со stack_reference. - обновлены перекрёстные ссылки в AGENTS.md, course_program.md, maintainer_guide.md. - Проверка: - все ссылки между документами валидны (glossary.md, mentor_notes.md существуют). - термины glossary и команды шпаргалки верифицированы по содержимому ноутбуков. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -0,0 +1,108 @@
|
||||
# Заметки для ментора
|
||||
|
||||
Этот документ — для ведения курса с ментором. Студенту он не нужен.
|
||||
|
||||
## Формат работы
|
||||
|
||||
Менти работает преимущественно самостоятельно. Ноутбуки написаны так, чтобы студент мог пройти демо-часть и самостоятельные задания без посторонней помощи.
|
||||
|
||||
Роль ментора:
|
||||
- **задать направление** — обозначить, на что обратить внимание в модуле, какие параллели с текущим опытом студента искать;
|
||||
- **отвечать на вопросы** — по ходу прохождения или на 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 нельзя пропускать** даже для опытных студентов. Они содержат ключевые практики, которые отличают «знаю теорию» от «умею делать руками».
|
||||
Reference in New Issue
Block a user