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:
2026-03-08 01:04:26 +03:00
co-authored by Claude Opus 4.6
parent 4bea2af9d2
commit 0ae83cecdb
7 changed files with 350 additions and 66 deletions
+38 -62
View File
@@ -1,16 +1,23 @@
# Lakehouse без магии: локальный стенд и учебные материалы
# Lakehouse без магии
Этот репозиторий объединяет:
Практический курс, после которого ты будешь уверенно работать с Lakehouse-стеком: поднимать стенд, строить пайплайн `raw -> bronze -> silver`, читать одну таблицу из двух движков и не бояться изменений в данных.
- локальный Lakehouse-стенд на `Spark + Trino + Iceberg + MinIO + PostgreSQL`;
- учебный курс `Lakehouse без магии`, который использует этот стенд как практическую среду;
- стартовые ноутбуки и demo-скрипты для первых экспериментов.
## Что ты получишь
Репозиторий рассчитан не на «универсальную платформу для всего», а на понятную локальную песочницу, где можно руками пройти путь от запуска стенда до чтения одной и той же Iceberg-таблицы из `Spark` и `Trino`.
После прохождения 8 модулей ты умеешь:
## Архитектура
1. **Поднимать и диагностировать** локальный Lakehouse-стенд — не по инструкции, а с пониманием, что и зачем работает.
2. **Объяснять архитектуру** `storage + catalog + compute` — и видеть, как знакомые концепции из PostgreSQL/Greenplum ложатся на новый стек.
3. **Строить пайплайн** `raw -> bronze -> silver` на реальном датасете NYC Taxi — с проверками качества и воспроизводимостью.
4. **Работать с двумя движками** — записывать данные через Spark, читать через Trino, и понимать, почему это работает без копирования.
5. **Безопасно менять таблицы** — schema evolution, time travel, rollback к предыдущему состоянию вместо паники.
6. **Обслуживать таблицы** — compaction и expire_snapshots, с пониманием параллелей к VACUUM/REORGANIZE.
Ниже показана упрощённая рабочая схема стенда: пользователь входит через `JupyterLab` и `Trino UI / CLI`, а `Spark` и `Trino` независимо работают поверх общего `storage` и общего `catalog`.
Курс рассчитан на `~12-15 часов` самостоятельной работы. Каждый модуль: объяснение, демонстрация, самостоятельное задание, checkpoint.
## Стек
Всё работает локально в Docker. Никаких облаков, внешних зависимостей и регистраций.
```mermaid
graph TB
@@ -41,23 +48,21 @@ graph TB
T --> M
```
Коротко по ролям:
- `MinIO` хранит данные и служебные файлы Iceberg.
- `PostgreSQL` хранит метаданные JDBC-каталога `lakehouse`.
- `Spark` и `Trino` работают как два compute-движка поверх одного storage и одного catalog.
- `JupyterLab` служит основной точкой входа в практическую часть курса.
- `Trino UI / CLI` даёт отдельную точку входа для ad hoc SQL и проверки таблиц.
| Компонент | Роль в стенде |
| --- | --- |
| `MinIO` | Storage — хранит данные и служебные файлы Iceberg |
| `PostgreSQL` | Catalog — метаданные JDBC-каталога `lakehouse` |
| `Spark` | Compute — ETL, запись и чтение Iceberg-таблиц |
| `Trino` | Compute — ad hoc SQL, чтение тех же таблиц |
| `JupyterLab` | Точка входа — практические ноутбуки курса |
## С чего начать
Если ты заходишь в репозиторий впервые, используй такой маршрут:
1. Открой [START_HERE.md](./START_HERE.md) — запуск стенда, диагностика, первый ноутбук.
2. Пройди `notebooks/01_environment_and_smoke_test.ipynb`.
3. Дальше по порядку: [docs/course_program.md](./docs/course_program.md).
1. Открой [START_HERE.md](./START_HERE.md) для первого запуска стенда и базовой диагностики.
2. После старта стенда выполни `notebooks/01_environment_and_smoke_test.ipynb`.
3. Для структуры курса смотри [docs/course_program.md](./docs/course_program.md).
Если нужен только краткий запуск, из корня репозитория достаточно:
Краткий запуск из корня репозитория:
```bash
docker compose build
@@ -65,54 +70,25 @@ docker compose up -d
docker compose ps
```
Основные UI после старта:
После старта:
- Spark Master UI: `http://localhost:8080`
- Trino UI: `http://localhost:8090`
- MinIO Console: `http://localhost:9001`
- JupyterLab: `http://localhost:8888`
Полный onboarding, диагностика и reset-сценарии находятся в `START_HERE.md`.
## Как устроен репозиторий
| Где | Что лежит |
| UI | Адрес |
| --- | --- |
| `docker-compose.yml` | состав сервисов стенда, порты, сети, init-контейнеры |
| `spark/` | Dockerfile и конфиг Spark для Iceberg + MinIO |
| `trino/` | каталог `lakehouse` и настройки Trino |
| `jupyter/` | образ JupyterLab на базе Spark-образа |
| `notebooks/` | практические ноутбуки курса |
| `src/` | smoke-скрипты, SQL-демо и helper-логика |
| `docs/` | PRD, программа курса, reference-документы |
| `plans/` | внутренние living docs по развитию материалов |
| JupyterLab | `http://localhost:8888` |
| Spark Master | `http://localhost:8080` |
| Trino | `http://localhost:8090` |
| MinIO Console | `http://localhost:9001` |
## Основные документы для прохождения
## Документы для прохождения
- [START_HERE.md](./START_HERE.md) — первый маршрут для студента.
- [START_HERE.md](./START_HERE.md) — первый маршрут: prerequisites, запуск, диагностика.
- [docs/course_program.md](./docs/course_program.md) — модульная структура и состав учебных материалов.
- [docs/stack_reference.md](./docs/stack_reference.md) — технический reference по сервисам, портам, конфигам и smoke-тестам.
- [docs/stack_reference.md](./docs/stack_reference.md) — порты, команды, конфиги, шпаргалка.
- [docs/glossary.md](./docs/glossary.md) — справочник терминов (storage, catalog, compute, snapshot и др.).
## Что уже можно делать в стенде
## Менторство
- поднять локальный кластер `Spark` с двумя worker-ами;
- создать Iceberg-таблицу из `Spark`;
- прочитать ту же таблицу из `Trino`;
- пройти базовый smoke test через ноутбук или demo-скрипты;
- использовать стенд как основу для следующих модулей курса.
## Куда смотреть за техническими деталями
- [docs/stack_reference.md](./docs/stack_reference.md) — сервисы, порты, доступ, reset, smoke tests;
- [spark/spark-defaults.conf](./spark/spark-defaults.conf) — конфигурация Spark-каталога `lakehouse`;
- [trino/catalog/lakehouse.properties](./trino/catalog/lakehouse.properties) — конфигурация каталога Trino;
- [docker-compose.yml](./docker-compose.yml) — фактический состав стенда.
## Автор и менторство
Этот репозиторий и материалы курса можно проходить самостоятельно, но при желании их можно разбирать вместе с автором как с ментором по `Data Engineering`.
Если хочешь глубже пройти темы `Spark`, `Trino`, `Iceberg`, `Lakehouse` и связанные практики по `DE`, напиши: [@dementev_dev](https://t.me/dementev_dev).
Курс рассчитан на самостоятельное прохождение, но если хочешь разобрать темы глубже с ментором по Data Engineering — напиши: [@dementev_dev](https://t.me/dementev_dev).
## Лицензия