diff --git a/docs/COURSE_PLAN.md b/docs/COURSE_PLAN.md deleted file mode 100644 index b37a06f..0000000 --- a/docs/COURSE_PLAN.md +++ /dev/null @@ -1,44 +0,0 @@ -# Программа учебного курса: Введение в Lakehouse - -Ориентировочная разбивка на 10 интерактивных уроков (Jupyter Notebooks). -Каждый урок рассчитан на 1-1.5 часа вдумчивой работы (теория + самостоятельная практика). - -## Блок I. Основы Lakehouse (Storage + Format) - -* **01_intro_and_storage.ipynb** - * Что такое Lakehouse. Разделение хранения и вычислений. - * Загрузка сырых файлов (CSV/JSON) в MinIO (S3). -* **02_first_iceberg_table.ipynb** - * Создание первой Iceberg-таблицы через Spark. - * Изучение структуры файлов (data, metadata, manifests) в MinIO. - -## Блок II. Единая точка правды (Catalog + Compute) - -* **03_the_catalog.ipynb** - * Роль JDBC-каталога (PostgreSQL). - * Как разные движки находят таблицы. -* **04_spark_meets_trino.ipynb** - * Разделение ролей (Spark пишет, Trino читает). - * Выполнение SQL-запросов к Iceberg-таблицам через Trino (интеграция вызовов Trino прямо в Jupyter). - -## Блок III. Инженерия данных (Data Pipelines) - -* **05_bronze_layer.ipynb** - * Чтение сырых данных Spark'ом и инжест "как есть" (Raw to Bronze). -* **06_silver_layer_and_schema_evolution.ipynb** - * Очистка данных. - * *Практика:* самостоятельное применение Schema Evolution (добавление/изменение колонок). -* **07_gold_layer_and_partitioning.ipynb** - * Агрегации бизнес-метрик. - * *Практика:* самостоятельное партиционирование таблиц для ускорения запросов (Partition Pruning). - -## Блок IV. Продвинутые фичи Lakehouse - -* **08_time_travel_and_snapshots.ipynb** - * Работа со снапшотами (Snapshots). - * *Практика:* восстановление таблицы после ошибочных `DELETE`/`UPDATE`, чтение "исторических" данных. -* **09_lakehouse_maintenance.ipynb** - * Проблема мелких файлов. - * Компактизация (Compaction) и очистка старых версий (Vacuum). -* **10_final_pipeline.ipynb** - * *Практика:* самостоятельный финальный end-to-end мини-пайплайн (Bronze -> Silver -> Gold), объединяющий все пройденные концепции. \ No newline at end of file diff --git a/docs/course_prd.md b/docs/course_prd.md index a196303..34d0159 100644 --- a/docs/course_prd.md +++ b/docs/course_prd.md @@ -1,4 +1,4 @@ -# Product Requirements Document (PRD): Учебный курс «Введение в Lakehouse» +# Product Requirements Document (PRD): Учебный курс «Lakehouse без магии» ## 1. Product Vision & Value Proposition @@ -56,6 +56,8 @@ 6. Умеет читать одну и ту же таблицу из `Spark` и `Trino` и понимает, почему это возможно без копирования данных. 7. Умеет выполнить базовые безопасные операции с таблицей: изменение схемы, просмотр snapshot-ов, чтение предыдущего состояния, базовый `compaction` и `vacuum`. +Трассировка этих outcomes на модули и checkpoints фиксируется в [course_program.md](./course_program.md). + ## 6. Teaching Principles **Принцип 1. Практика первична.** Курс не должен превращаться в обзорную лекцию. Теория нужна для объяснения того, что студент делает руками. @@ -93,9 +95,10 @@ * базовое schema evolution; * snapshot/time travel на прикладном уровне; * базовый `compaction/vacuum` с параллелями к `Greenplum AppendOnly`; -* набор практик в Jupyter Notebooks с обязательными заданиями и checkpoints. +* набор практик в Jupyter Notebooks с обязательными заданиями и checkpoints; +* стартовая документация до первого ноутбука: prerequisites, запуск стенда, вход в Jupyter и базовый troubleshooting. -Ориентировочная программа курса вынесена в отдельный документ: **[COURSE_PLAN.md](./COURSE_PLAN.md)**. +Ориентировочная программа курса вынесена в отдельный документ: **[course_program.md](./course_program.md)**. ## 9. Dataset Strategy @@ -115,6 +118,15 @@ **Методическое решение:** курс строится вокруг одного домена данных, но не требует жесткого сквозного проекта. Основной формат курса - набор связанных практик на одном и том же наборе данных. +**Механика доставки данных в v1:** + +* raw-датасет не хранится в репозитории целиком; +* стартовая документация должна давать воспроизводимый способ получить фиксированный учебный набор данных (`Default` или `Extended`) из публичного источника; +* `Taxi Zone Lookup` доставляется тем же способом, что и основной датасет; +* перед началом модуля про raw-данные студент должен иметь локальный data bundle на хосте; +* в модуле про raw-ingest студент загружает уже полученные файлы в raw-зону `MinIO`, а не ищет и не скачивает данные вручную прямо из ноутбука; +* ручная загрузка файлов через UI допускается только как fallback-сценарий, а не как основной путь прохождения. + ## 10. User Experience / Learning Flow Курс строится по модели **"объяснение -> демонстрация -> самостоятельное повторение -> checkpoint"**. @@ -128,18 +140,21 @@ **Формат прохождения:** желательно с ментором, но курс должен быть самодостаточным и для самостоятельного изучения. -## 11. Success Metrics & Acceptance Criteria +## 11. Product Targets & Acceptance Criteria -**Цели продукта:** +**Ориентиры продукта:** + +Это целевые ориентиры курса, но не blocking acceptance criteria для материалов. 1. Студент проходит курс за `~12-15 часов` вдумчивой работы. 2. Студент после курса способен безопасно выполнить базовые операции в Lakehouse-стенде без постоянной внешней помощи. 3. Студент может внятно объяснить ключевые архитектурные принципы Lakehouse на уровне junior/middle interview readiness. -**Acceptance Criteria для учебного результата:** +**Acceptance Criteria для учебных материалов и результата:** -1. Студент проходит обязательные `checkpoints` по урокам. -2. Студент самостоятельно выполняет набор практик на одном датасете, включая: +1. В составе курса есть стартовая документация до первого ноутбука, включая prerequisites, запуск стенда, вход в `Jupyter` и получение учебного data bundle. +2. Студент проходит обязательные `checkpoints` по урокам. +3. Студент самостоятельно выполняет набор практик на одном датасете, включая: * загрузку raw-данных; * построение `bronze`; * построение `silver`; @@ -148,7 +163,7 @@ * демонстрацию базового schema evolution; * демонстрацию snapshot/time travel; * демонстрацию базового `compaction/vacuum`. -3. Студент может своими словами объяснить: +4. Студент может своими словами объяснить: * что такое `Lakehouse` и чем он отличается от классической БД; * как разделены `storage`, `catalog`, `compute`; * что такое `Iceberg` в практическом смысле; @@ -161,8 +176,10 @@ * использование существующего `docker-compose.yml` (`Spark`, `Trino`, `MinIO`, `PostgreSQL`, `Jupyter`); * подготовка учебных датасетов и/или инструкций по их загрузке в репозиторий; +* наличие воспроизводимого способа получить учебный data bundle без ручного поиска по внешним сайтам; * поддержка выполнения запросов к `Trino` из ноутбуков; -* подготовка Jupyter Notebooks как основного формата учебных материалов; +* подготовка Jupyter Notebooks как основного формата практической части курса; +* подготовка стартовой документации для входа в курс до первого запуска ноутбуков; * наличие воспроизводимых шагов для старта, сброса и повторного прохождения практик. ## 13. Out of Scope (v1) @@ -172,6 +189,7 @@ * `gold`-слой и полноценные бизнес-витрины; * `Airflow`, `Kafka`, `NiFi`, `streaming`, `CDC`; * сложные `MERGE`-сценарии, row-level deletes и update-heavy кейсы; +* партиционирование и `partition pruning` как отдельная учебная тема первой версии; * глубокий performance tuning; * production security, governance, multi-user setup; * Kubernetes / облачное развертывание; diff --git a/docs/course_program.md b/docs/course_program.md new file mode 100644 index 0000000..5e5491d --- /dev/null +++ b/docs/course_program.md @@ -0,0 +1,287 @@ +# Программа учебного курса: Lakehouse без магии + +Этот документ заменяет предыдущий черновой план и выравнивает программу с PRD из [course_prd.md](./course_prd.md). + +## 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. Состав учебных материалов + +Курс не должен состоять только из ноутбуков. Ноутбуки являются ядром практики, но вход в курс, запуск стенда и правила работы должны быть вынесены в обычную документацию, доступную до старта `Jupyter`. + +### 3.1. Стартовая документация до первого ноутбука + +Этот слой нужен, потому что студент ещё не имеет доступа к ноутбукам, пока не поднят стенд. + +**Минимальный обязательный набор:** + +* `START_HERE.md` или аналогичный стартовый документ с маршрутом прохождения курса; +* инструкция по prerequisites: `Docker`, `Docker Compose`, свободные порты, базовые команды; +* пошаговый гайд по запуску стенда: `build`, `up`, проверка сервисов, открытие UI; +* краткое объяснение, как пользоваться `Jupyter`, где лежат ноутбуки и как читать структуру урока; +* troubleshooting по типовым проблемам старта; +* инструкция по reset/restart стенда для повторного прохождения практик. + +**Что должен закрывать этот слой:** + +* студент понимает, что нужно установить и проверить до начала курса; +* студент может поднять стенд без ментора; +* студент знает, как попасть в `Jupyter`, `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`; +* cheat sheet по типовым командам, адресам сервисов, ключевым путям и точкам входа; +* опционально, отдельные mentor notes для ведения курса с ментором. + +## 4. Трассировка Learning Outcomes на модули + +| Learning Outcome | Основные модули | Где проверяется | +| --- | --- | --- | +| `LO1`. Понимание различий между `storage`, `catalog`, `compute` | 1, 2, 6 | checkpoints модулей 2 и 6 | +| `LO2`. Умение поднять и диагностировать стенд | 1 | checkpoint модуля 1 | +| `LO3`. Умение загрузить 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` + +**Зачем нужен:** студент должен уметь самостоятельно поднять локальный стенд и понять, куда смотреть, если что-то не работает. + +**Содержание:** + +* запуск `docker compose build` и `docker compose up -d`; +* проверка сервисов и веб-интерфейсов; +* базовый smoke test для Spark; +* первый обзор того, где в стенде `MinIO`, `PostgreSQL`, `Spark`, `Trino`, `Jupyter`. + +**Практика студента:** + +* запустить стенд; +* проверить статусы контейнеров и основные 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` + +**Зачем нужен:** показать, как raw-данные попадают в стенд и как с ними безопасно начать работать. + +**Содержание:** + +* работа с заранее подготовленным локальным data bundle из onboarding-документации; +* явная загрузка исходных `PARQUET`-файлов в raw-зону; +* чтение raw-данных через Spark; +* проверка схемы, типов и базового качества данных; +* обсуждение того, почему raw лучше не "чинить на месте" и почему датасет не должен скачиваться "из интернета из ноутбука". + +**Практика студента:** + +* проверить состав локально полученного набора `NYC Taxi`; +* загрузить его в raw-зону `MinIO`; +* прочитать несколько месяцев `NYC Taxi`; +* проверить схему и посчитать базовые метрики; +* найти простые аномалии или проблемные значения. + +**Checkpoint:** студент умеет загрузить учебный набор в raw-зону, прочитать raw-данные, проверить схему и объяснить, почему raw-слой нужен как воспроизводимая точка входа. + +### Модуль 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. Умеет загрузить raw-данные и прочитать их в Spark. +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. правила сброса стенда и повторного прохождения практик.