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:
@@ -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).
|
||||
|
||||
## Лицензия
|
||||
|
||||
|
||||
Reference in New Issue
Block a user