mini-lakehouse-lab/docs/course_program.md

Программа учебного курса: Lakehouse без магии

Здесь собраны порядок модулей, ссылки на ноутбуки и результаты, по которым можно проверить свою работу. Рамки курса и learning outcomes описаны в course_prd.md.

Маршрут по модулям

Перед первым уроком подготовь стенд по START_HERE. Дальше проходи ноутбуки по порядку: файлы и таблицы из ранних модулей нужны в следующих. Пауза между занятиями описана в памятке учащегося.

Модуль и ноутбук	Что понадобится	Результат перед переходом дальше
1. Вход в стенд	Работающий стенд	Smoke test вернул 499999500000; ты можешь показать два worker-а и объяснить роли сервисов
2. Модель Lakehouse	Модуль 1	Ты нашел файлы демо-таблицы в MinIO и запись каталога в PostgreSQL; выполнил очистку демо по ноутбуку
3. Исходные данные	Четыре файла Taxi на хосте	Файлы загружены в raw-зону MinIO, Spark читает их; проверены схема и основные метрики
4. Bronze и Iceberg	Raw-файлы из Модуля 3	Созданы bronze-таблица поездок и таблица зон из самостоятельного задания; видны их данные и metadata-файлы
5. Silver	Обе bronze-таблицы	Создана silver-таблица, проверены правила очистки и качество результата
6. Spark и Trino	Silver из Модуля 5; DBeaver по желанию	Одна таблица читается обоими движками; ты можешь объяснить, какие компоненты у них общие
7. Изменения таблиц	Результаты предыдущих модулей	На демо-таблице проверены изменение схемы, чтение прошлого состояния и rollback; silver сохранена
8. Обслуживание и финальная практика	Raw, bronze и silver	Проверено обслуживание таблиц; самостоятельно пройден поток от исходных файлов до чтения и проверок результата

В каждом ноутбуке сначала прочитай объяснение, затем выполни демонстрацию и самостоятельное задание. Checkpoint в конце урока — вопросы и проверки для самопроверки. Сохраненный вывод помогает вернуться к результату, но не заменяет собственный запуск и объяснение.

1. Рамка курса

Формат: стартовая документация + 8 практических уроков в Jupyter Notebooks + вспомогательные справочные материалы.

Оценка длительности: ~12-15 часов вдумчивой работы.

Ориентир на модуль: в среднем ~1.5 часа, но финальная практика может занять дольше.

Сквозной учебный кейс: NYC TLC Yellow Taxi Trip Records + Taxi Zone Lookup.

Методика каждого урока: объяснение -> демонстрация -> самостоятельное повторение -> checkpoint.

Главная цель курса: дать студенту безопасную рабочую модель Lakehouse на локальном стенде Spark + Trino + Iceberg + MinIO + PostgreSQL, а не обзор всех возможных фич.

2. Принципы декомпозиции программы

1. Сначала студент должен научиться поднимать и диагностировать стенд, и только потом строить пайплайн.
2. Архитектурная модель storage + catalog + compute проходит через весь курс, а не выносится в одну "теоретическую" лекцию.
3. Весь курс строится вокруг одного датасета и одного потока raw -> bronze -> silver.
4. В первой версии курса основной табличный формат только один: Iceberg.
5. Практики про безопасность важнее "вау-фич": аккуратный overwrite, понимание снапшотов, воспроизводимость шагов, базовое обслуживание таблиц.
6. Темы вне PRD v1 не включаются в основной трек и остаются в backlog.

3. Состав учебных материалов

Курс не должен состоять только из ноутбуков. Ноутбуки являются ядром практики, но вход в курс, запуск стенда и правила работы должны быть вынесены в обычную документацию, доступную до открытия IDE.

3.1. Стартовая документация до первого ноутбука

Этот слой нужен, потому что студент ещё не имеет доступа к ноутбукам, пока не поднят стенд.

Минимальный обязательный набор:

• START_HERE.md или аналогичный стартовый документ с маршрутом прохождения курса;
• инструкция по prerequisites: Docker, Docker Compose, свободные порты, базовые команды;
• пошаговый гайд по запуску стенда: build, up, проверка сервисов, открытие UI;
• краткое объяснение, как запускать Jupyter-ноутбуки в браузерном VS Code, где лежат ноутбуки и как читать структуру урока;
• troubleshooting по типовым проблемам старта;
• памятка учащегося: продолжение занятия, сохранение данных, перезапуск ядра и диагностика;
• отдельная инструкция по сбросу учебных данных для повторного прохождения практик.

Что должен закрывать этот слой:

• студент понимает, что нужно установить и проверить до начала курса;
• студент может поднять стенд без ментора;
• студент знает, как попасть в браузерный VS Code, MinIO, Trino UI;
• студент понимает, как устроен формат уроков и что от него ожидается.

3.2. Практическое ядро курса

Это 8 ноутбуков, в которых живут демонстрации, самостоятельные задания и checkpoints.

3.3. Вспомогательные материалы

Кроме ноутбуков и стартового onboarding-слоя, курсу потребуются:

• вспомогательные скрипты в src/spark и src/trino;
• инструкции по загрузке или подготовке учебных датасетов;
• краткий glossary по терминам storage, catalog, compute, table format, namespace, metadata, manifest, snapshot, time travel, schema evolution, compaction, vacuum;
• шпаргалка по типовым командам, адресам сервисов, ключевым путям и точкам входа (секция в stack_reference.md);
• опционально, заметки для ментора для ведения курса с ментором.

4. Трассировка Learning Outcomes на модули

Learning Outcome	Основные модули	Где проверяется
LO1. Понимание различий между storage, catalog, compute	1, 2, 6	checkpoints модулей 2 и 6
LO2. Умение поднять и диагностировать стенд	1	checkpoint модуля 1
LO3. Умение подключиться к Spark, загрузить raw-данные и проверить схему	3	checkpoint модуля 3
LO4. Умение создать и заполнить Iceberg-таблицу	4	checkpoint модуля 4
LO5. Умение собрать поток raw -> bronze -> silver	4, 5, 8	checkpoints модулей 5 и 8
LO6. Умение читать одну таблицу из Spark и Trino	6, 8	checkpoint модуля 6 и финальная практика
LO7. Умение выполнять безопасные операции с таблицей	7, 8	checkpoints модулей 7 и 8

5. Верхнеуровневая структура практической части

Модуль 1. Вход в стенд и базовая диагностика

Рабочее название ноутбука: 01_environment_and_smoke_test.ipynb

Зачем нужен: студент должен уметь самостоятельно поднять локальный стенд и понять, куда смотреть, если что-то не работает.

Содержание:

• скачивание готовых образов, сборка окружения и запуск по START_HERE.md;
• проверка сервисов и веб-интерфейсов;
• базовый smoke test для Spark;
• первый обзор того, где в стенде MinIO, PostgreSQL, Spark, Trino и IDE.

Практика студента:

• запустить стенд;
• проверить статусы контейнеров и основные UI;
• выполнить простой smoke test и прочитать его результат.

Checkpoint: студент подтверждает, что стенд поднят, понимает назначение сервисов и умеет сделать первичную диагностику через docker compose ps, логи и UI.

Модуль 2. Ментальная модель Lakehouse: storage, catalog, compute

Рабочее название ноутбука: 02_lakehouse_mental_model.ipynb

Зачем нужен: убрать магическое восприятие Lakehouse и связать новую модель с привычным миром PostgreSQL/Greenplum.

Содержание:

• демонстрационный проход по цепочке Spark -> catalog -> MinIO на маленькой demo-таблице;
• что такое таблица в Lakehouse в практическом смысле;
• где лежат данные, где лежат метаданные, кто выполняет вычисления;
• разница между "одной базой данных" и набором согласованных компонентов;
• короткие параллели с классическим DWH.

Практика студента:

• выполнить готовую демонстрационную запись через Spark в небольшую demo-таблицу;
• найти соответствующие артефакты в MinIO и запись о таблице в каталоге через подготовленные диагностические шаги;
• сопоставить наблюдения с ролями storage / catalog / compute.

Checkpoint: студент своими словами объясняет роли MinIO, PostgreSQL, Spark и Trino, не путает физическое хранение с логической таблицей и может показать, где в стенде видны данные, метаданные и вычислитель.

Модуль 3. Raw-данные и первое чтение в Spark

Рабочее название ноутбука: 03_raw_ingest_and_first_read.ipynb

Зачем нужен: пройти путь от подключения к Spark до первого чтения и проверки исходных файлов Taxi.

Ориентир по времени: около 2 часов, из них 20–30 минут на подготовку Spark-сессии.

Содержание:

• подключение к Spark-кластеру: сессия, контекст, driver и executors; настройки из файла, параметров запуска и кода;
• повторное использование сессии, остановка и перезапуск ядра; изменение настроек во время работы;
• подготовленный data bundle и загрузка исходных файлов в raw-зону MinIO;
• чтение через Spark, проверка схемы и типов;
• базовые метрики, аномалии и причины сохранять raw без изменений.

Практика студента:

• заполнить шаблон сессии с подготовленным каталогом Iceberg; проверить подключение на собственной временной таблице и удалить ее;
• изменить и восстановить часовой пояс, сравнить повторный вызов builder-а с новым запуском приложения;
• проверить состав data bundle и загрузить несколько месяцев Taxi в MinIO;
• прочитать поездки и справочник зон, проверить схему и посчитать метрики;
• найти проблемные значения и объяснить, почему их сохраняют в raw.

Checkpoint: студент создает сессию для кластера, объясняет источники настроек и место выполнения заданий, умеет повторить подключение в новом ядре. Загружает учебный набор в raw-зону, читает его через Spark, проверяет схему и объясняет, зачем сохранять исходные данные.

Модуль 4. Первая рабочая Iceberg-таблица и слой bronze

Рабочее название ноутбука: 04_bronze_with_iceberg.ipynb

Зачем нужен: перейти от набора файлов к управляемой таблице и построить первый слой обработки.

Содержание:

• создание namespace и Iceberg-таблицы через Spark;
• запись raw-данных в bronze;
• осмотр структуры Iceberg на прикладном уровне: data files, metadata, snapshots;
• связь raw -> bronze с привычным stg/ods-мышлением.

Практика студента:

• создать первую Iceberg-таблицу;
• загрузить в неё данные из raw;
• проверить результат через чтение таблицы и осмотр артефактов хранения.

Checkpoint: студент умеет создать и заполнить Iceberg-таблицу и понимает, что таблица в Lakehouse не сводится к одному каталогу с файлами.

Модуль 5. Слой silver и воспроизводимые трансформации

Рабочее название ноутбука: 05_silver_layer.ipynb

Зачем нужен: научить строить простой, понятный и воспроизводимый pipeline raw -> bronze -> silver.

Содержание:

• базовые трансформации и очистка данных;
• явная фиксация правил преобразования;
• разделение ответственности между слоями;
• проверки качества на уровне строк, схемы и агрегатов.

Практика студента:

• собрать silver из bronze;
• нормализовать часть полей;
• добавить простые проверки результата.

Checkpoint: студент может воспроизводимо построить silver и объяснить, чем bronze отличается от silver.

Модуль 6. Одна таблица, два движка: Spark и Trino

Рабочее название ноутбука: 06_spark_and_trino_on_same_table.ipynb

Зачем нужен: закрепить идею разделения вычислительных движков и показать, что данные не нужно копировать между системами.

Содержание:

• чтение одной и той же Iceberg-таблицы из Spark и Trino;
• роль общего каталога;
• простые SQL-проверки в Trino;
• ограничение темы: курс не уходит в глубокое сравнение движков.

Практика студента:

• записать таблицу через Spark;
• прочитать ту же таблицу через Trino;
• сверить результаты и ответить, почему это работает.

Checkpoint: студент понимает, почему Spark может писать, а Trino читать ту же таблицу без копирования данных.

Модуль 7. Безопасная работа с таблицами: schema evolution и time travel

Рабочее название ноутбука: 07_safe_table_changes.ipynb

Зачем нужен: научить не ломать таблицы вслепую и пользоваться базовыми защитными механизмами.

Содержание:

• добавление и изменение схемы на базовом уровне;
• влияние schema evolution на downstream-чтение;
• snapshots и time travel;
• разбор типовых ошибок новичка: неаккуратный overwrite, слепая перезапись, неявные изменения типов.

Практика студента:

• добавить новую колонку или безопасно изменить схему;
• посмотреть историю snapshot-ов;
• прочитать предыдущее состояние таблицы после намеренно "неудачного" изменения.

Checkpoint: студент умеет делать базовые изменения схемы, смотреть историю таблицы и использовать time travel как страховку.

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

Рабочее название ноутбука: 08_maintenance_and_final_lab.ipynb

Зачем нужен: завершить курс рабочим циклом поддержки таблицы и собрать все изученное в одну практику.

Содержание:

• проблема мелких файлов;
• базовый compaction;
• базовый vacuum / cleanup старых версий;
• короткая параллель с обслуживанием Greenplum AppendOnly-таблиц;
• финальный мини-сценарий: raw -> bronze -> silver -> проверка через Trino -> безопасное изменение -> обслуживание.

Практика студента:

• выполнить compaction на учебной таблице;
• очистить старые версии в контролируемом сценарии;
• пройти финальный end-to-end checkpoint.

Checkpoint: студент выполняет полный учебный сценарий и может объяснить, зачем нужны compaction и cleanup в прикладной работе.

6. Что получает студент по итогам курса

После прохождения программы студент:

1. Поднимает локальный стенд и диагностирует типовые проблемы на старте.
2. Понимает различие между storage, catalog и compute.
3. Подключается к Spark-кластеру, загружает raw-данные и проверяет их после чтения.
4. Умеет создать и заполнить Iceberg-таблицу.
5. Умеет построить простой поток raw -> bronze -> silver.
6. Умеет читать одну и ту же таблицу из Spark и Trino.
7. Умеет выполнять базовые безопасные операции: schema evolution, snapshots/time travel, compaction, vacuum.

7. Что не входит в первую версию курса

Следующие темы сознательно исключены из основного плана и могут стать отдельным расширением:

• gold-слой и полноценные бизнес-витрины;
• партиционирование и partition pruning как отдельная обязательная тема v1;
• performance tuning и физический дизайн таблиц как самостоятельный модуль;
• MERGE, row-level deletes, update-heavy сценарии;
• streaming, Kafka, CDC, Airflow, NiFi;
• deep dive во внутренности Iceberg на уровне спецификации;
• production security, governance, multi-user setup, Kubernetes и облака.

Существующие demo-артефакты по партиционированию в репозитории считаются legacy-материалами и не входят в обязательный трек первой версии курса.

8. Следующий уровень детализации

После утверждения этой структуры следующий документ должен описывать не "темы вообще", а каркас учебных артефактов:

1. состав стартовой документации и порядок чтения до первого запуска, включая получение data bundle;
2. список ноутбуков и их точные learning objectives;
3. обязательные демонстрации, самостоятельные задания и checkpoints по каждому уроку;
4. набор вспомогательных src/spark и src/trino-скриптов, включая загрузку датасета и диагностические шаги для модуля 2;
5. правила сброса стенда и повторного прохождения практик.