From 0ae83cecdb940e55bccb60b3d3a703182651e162 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 8 Mar 2026 01:04:26 +0300 Subject: [PATCH] =?UTF-8?q?docs(course):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D1=8B=20glossary,=20mentor=20notes,=20=D1=88?= =?UTF-8?q?=D0=BF=D0=B0=D1=80=D0=B3=D0=B0=D0=BB=D0=BA=D0=B0=20=D0=B8=20?= =?UTF-8?q?=D0=BF=D0=B5=D1=80=D0=B5=D0=BF=D0=B8=D1=81=D0=B0=D0=BD=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - закрыты 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 --- AGENTS.md | 2 + README.md | 100 +++++++++++----------------- docs/course_program.md | 6 +- docs/glossary.md | 137 +++++++++++++++++++++++++++++++++++++++ docs/maintainer_guide.md | 1 + docs/mentor_notes.md | 108 ++++++++++++++++++++++++++++++ docs/stack_reference.md | 62 +++++++++++++++++- 7 files changed, 350 insertions(+), 66 deletions(-) create mode 100644 docs/glossary.md create mode 100644 docs/mentor_notes.md diff --git a/AGENTS.md b/AGENTS.md index 74065f2..15d9706 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,8 @@ - `docs/stack_reference.md` — технический reference по сервисам, портам, доступу и smoke-тестам. - `docs/course_prd.md` — рамки курса, learning outcomes, scope и out of scope. - `docs/course_program.md` — модульная структура курса и состав учебных материалов. +- `docs/glossary.md` — справочник терминов курса. +- `docs/mentor_notes.md` — заметки для ведения курса с ментором (опционально). - `docs/maintainer_guide.md` — карта репозитория и правила синхронизации изменений. - `plans/` — внутренние living docs; не источник истины для студентского маршрута. - `docs/archive/` — архивные материалы; не использовать как актуальную документацию без явного запроса. diff --git a/README.md b/README.md index 2dd1d0a..eb72f6c 100755 --- a/README.md +++ b/README.md @@ -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). ## Лицензия diff --git a/docs/course_program.md b/docs/course_program.md index 5e5491d..149424c 100644 --- a/docs/course_program.md +++ b/docs/course_program.md @@ -59,9 +59,9 @@ * вспомогательные скрипты в `src/spark` и `src/trino`; * инструкции по загрузке или подготовке учебных датасетов; -* краткий glossary по терминам `storage`, `catalog`, `compute`, `table format`, `namespace`, `metadata`, `manifest`, `snapshot`, `time travel`, `schema evolution`, `compaction`, `vacuum`; -* cheat sheet по типовым командам, адресам сервисов, ключевым путям и точкам входа; -* опционально, отдельные mentor notes для ведения курса с ментором. +* краткий [glossary](./glossary.md) по терминам `storage`, `catalog`, `compute`, `table format`, `namespace`, `metadata`, `manifest`, `snapshot`, `time travel`, `schema evolution`, `compaction`, `vacuum`; +* [шпаргалка](./stack_reference.md#краткая-шпаргалка) по типовым командам, адресам сервисов, ключевым путям и точкам входа (секция в `stack_reference.md`); +* опционально, [заметки для ментора](./mentor_notes.md) для ведения курса с ментором. ## 4. Трассировка Learning Outcomes на модули diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..f2f1782 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,137 @@ +# Глоссарий курса + +Краткий справочник терминов, сгруппированных по темам. Если нужен полный технический reference стенда, используй [stack_reference.md](./stack_reference.md). + +## Архитектура Lakehouse + +### Storage + +Физическое хранилище файлов. Хранит data files, metadata-файлы Iceberg и raw-данные. + +**В этом курсе:** MinIO (`s3a://lakehouse/`). +**Параллель с DWH:** каталог `pg_data` в PostgreSQL, только вынесенный за пределы СУБД. +**Где в курсе:** Модули 1, 2, 3. + +### Catalog + +Реестр метаданных таблиц: какие таблицы существуют, где лежат их данные, какова текущая схема. Не хранит сами данные. + +**В этом курсе:** PostgreSQL (JDBC catalog `lakehouse`). +**Параллель с DWH:** системный каталог `pg_catalog` в PostgreSQL. +**Где в курсе:** Модули 2, 4, 6. + +### Compute + +Вычислительный движок, который читает метаданные из каталога и данные из хранилища для выполнения запросов. Не владеет ни данными, ни метаданными. + +**В этом курсе:** Spark (запись и чтение), Trino (чтение и ad hoc SQL). +**Параллель с DWH:** процесс СУБД PostgreSQL/Greenplum, но в Lakehouse движков может быть несколько одновременно. +**Где в курсе:** Модули 1, 2, 6. + +### Table format + +Спецификация, определяющая, как таблица организована на уровне файлов: какие data files входят в таблицу, где лежат метаданные, как работают snapshot-ы. Это не база данных и не хранилище — это набор правил. + +**В этом курсе:** Apache Iceberg. +**Параллель с DWH:** ближайший аналог — формат хранения таблицы (heap / AppendOnly в Greenplum), но table format в Lakehouse делает больше: он управляет историей, схемой и файлами. +**Где в курсе:** Модули 2, 4. + +### Decoupled compute + +Принцип, при котором вычислительные движки не зависят друг от друга и от хранилища. Один движок может писать, другой — читать те же данные без копирования, потому что оба обращаются к общему каталогу и хранилищу. + +**В этом курсе:** Spark пишет таблицу, Trino читает ту же таблицу через общий JDBC-каталог. +**Параллель с DWH:** в классическом DWH вычислитель один, поэтому проблема не возникает. +**Где в курсе:** Модуль 6. + +## Структура Iceberg-таблицы + +### Namespace + +Логическая группа таблиц внутри каталога. Используется для организации таблиц по слоям или доменам. + +**В этом курсе:** `bronze`, `silver`, `default` — namespace-ы внутри каталога `lakehouse`. +**Параллель с DWH:** `schema` в PostgreSQL. +**Где в курсе:** Модули 4, 5. + +### Metadata + +JSON-файлы, описывающие текущее состояние таблицы: схему, свойства, список snapshot-ов. Лежат в каталоге `metadata/` рядом с data files в хранилище. + +**В этом курсе:** файлы в `s3a://lakehouse/warehouse///metadata/`. +**Параллель с DWH:** системные таблицы `pg_catalog`, но вынесенные в файлы. +**Где в курсе:** Модули 2, 4. + +### Manifest + +Avro-файл со списком data files и их статистиками (количество строк, диапазоны значений колонок). Позволяет движку пропускать ненужные файлы при чтении. + +**В этом курсе:** видны при осмотре структуры таблицы в MinIO. +**Где в курсе:** Модуль 4. + +### Manifest list + +Avro-файл со списком manifest-ов, составляющих один snapshot. Каждый snapshot ссылается на свой manifest list. + +**В этом курсе:** видны как часть внутренней структуры Iceberg при исследовании MinIO. +**Где в курсе:** Модуль 4. + +### Snapshot + +Неизменяемая версия таблицы, зафиксированная в момент операции с данными (INSERT, overwrite, delete). Каждый snapshot определяет, какие data files составляли таблицу в конкретный момент. Как коммит в git. + +**В этом курсе:** `SELECT * FROM table.snapshots` показывает историю snapshot-ов. +**Параллель с DWH:** бэкап или PITR (Point-In-Time Recovery), но значительно легче: snapshot-ы создаются автоматически и не требуют копирования данных. +**Где в курсе:** Модули 4, 7, 8. + +## Операции + +### Time travel + +Чтение таблицы в состоянии на момент определённого snapshot-а. Позволяет сравнить текущие данные с предыдущими или восстановить потерянную информацию. В Spark: `VERSION AS OF `, в Trino: `FOR VERSION AS OF `. + +**В этом курсе:** демонстрация на демо-таблице в Модуле 7. +**Параллель с DWH:** восстановление из бэкапа (pg_dump / PITR), но без остановки сервиса и без восстановления всей базы целиком. +**Где в курсе:** Модуль 7. + +### Schema evolution + +Изменение схемы таблицы (добавление, переименование, удаление колонок) без перезаписи data files. Метаданные обновляются, данные остаются на месте. + +**В этом курсе:** `ALTER TABLE ADD COLUMNS`, `ALTER TABLE RENAME COLUMN`. +**Параллель с DWH:** `ALTER TABLE` в PostgreSQL, но в Iceberg старые data files не перезаписываются — новые колонки возвращают NULL для существующих строк. +**Где в курсе:** Модули 7, 8. + +### Compaction (rewrite_data_files) + +Объединение множества мелких data files в меньшее количество крупных. Решает проблему деградации чтения после множества мелких INSERT-ов. Данные не меняются, только реорганизуются файлы. + +**В этом курсе:** `CALL lakehouse.system.rewrite_data_files(table => '...')`. +**Параллель с DWH:** `ALTER TABLE ... REORGANIZE` в Greenplum AppendOnly. +**Где в курсе:** Модуль 8. + +### Vacuum (expire_snapshots) + +Удаление старых snapshot-ов и связанных с ними data files из хранилища. Освобождает место, но делает невозможным time travel к удалённым snapshot-ам. Необратимая операция. + +**В этом курсе:** `CALL lakehouse.system.expire_snapshots(table => '...', retain_last => N)`. +**Параллель с DWH:** `VACUUM` в PostgreSQL/Greenplum (удаление мёртвых строк). +**Где в курсе:** Модуль 8. + +## Слои данных + +### Raw + +Неизменяемые исходные файлы, загруженные из внешнего источника. Хранятся в S3 как обычные файлы (Parquet, CSV), а не как Iceberg-таблицы. Точка воспроизводимости: если что-то пошло не так на следующих слоях, всегда можно перестроить пайплайн от raw. + +**В этом курсе:** `s3a://lakehouse/raw/nyc_taxi/` — Parquet-файлы NYC Taxi. +**Параллель с DWH:** staging-зона (stg), внешние таблицы. +**Где в курсе:** Модуль 3. + +### Bronze / Silver + +Управляемые Iceberg-таблицы с разным уровнем обработки. Bronze — данные «как есть» из raw, загруженные в Iceberg-таблицу. Silver — очищенные и трансформированные данные, готовые для анализа. + +**В этом курсе:** `lakehouse.bronze.nyc_taxi_yellow` (bronze), `lakehouse.silver.nyc_taxi_yellow` (silver). +**Параллель с DWH:** ODS (bronze) / DDS (silver). +**Где в курсе:** Модули 4 (bronze), 5 (silver), 8 (финальная практика). diff --git a/docs/maintainer_guide.md b/docs/maintainer_guide.md index d85920a..867dbf2 100644 --- a/docs/maintainer_guide.md +++ b/docs/maintainer_guide.md @@ -21,6 +21,7 @@ | Onboarding | `README.md`, `START_HERE.md` | Вход в репозиторий и первый пользовательский маршрут | | Runtime reference | `docs/stack_reference.md` | Технические детали стенда: порты, доступ, команды, smoke-тесты | | Course definition | `docs/course_prd.md`, `docs/course_program.md` | Границы курса, learning outcomes, структура модулей | +| Reference materials | `docs/glossary.md`, `docs/mentor_notes.md` | Справочник терминов и заметки для ментора | | Practice materials | `notebooks/`, `src/` | Практика студента, smoke-скрипты, демонстрации, helper-логика | | Internal planning | `plans/` | Внутренние living docs по разработке материалов | | Archive | `docs/archive/` | Исторические материалы, не входящие в актуальный маршрут | diff --git a/docs/mentor_notes.md b/docs/mentor_notes.md new file mode 100644 index 0000000..72e227a --- /dev/null +++ b/docs/mentor_notes.md @@ -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 нельзя пропускать** даже для опытных студентов. Они содержат ключевые практики, которые отличают «знаю теорию» от «умею делать руками». diff --git a/docs/stack_reference.md b/docs/stack_reference.md index c022fc2..75cf937 100644 --- a/docs/stack_reference.md +++ b/docs/stack_reference.md @@ -172,9 +172,69 @@ docker compose exec spark-master \ /opt/spark/bin/spark-sql -e "DROP TABLE IF EXISTS lakehouse.default.spark_trino_smoke" ``` +## Краткая шпаргалка + +### Ключевые S3-пути курса + +| Путь | Назначение | +| --- | --- | +| `s3a://lakehouse/raw/nyc_taxi/` | raw-зона: исходные Parquet и CSV | +| `s3a://lakehouse/warehouse/bronze/` | bronze-таблицы Iceberg | +| `s3a://lakehouse/warehouse/silver/` | silver-таблицы Iceberg | + +### Основные таблицы курса + +| Таблица | Создаётся в | +| --- | --- | +| `lakehouse.bronze.nyc_taxi_yellow` | Модуль 4 | +| `lakehouse.bronze.taxi_zone_lookup` | Модуль 4 (самостоятельное задание) | +| `lakehouse.silver.nyc_taxi_yellow` | Модуль 5 | + +### Часто используемые Spark SQL + +```sql +-- Просмотр структуры каталога +SHOW TABLES IN lakehouse.bronze; + +-- Метаданные Iceberg +SELECT * FROM
.snapshots; +SELECT * FROM
.files; + +-- Обслуживание (Модуль 8) +CALL lakehouse.system.rewrite_data_files(table => '.
'); +CALL lakehouse.system.expire_snapshots(table => '.
', retain_last => N); + +-- Rollback (Модуль 7) +CALL lakehouse.system.rollback_to_snapshot(table => '.
', snapshot_id => ); + +-- Time travel (Модуль 7) +SELECT * FROM
VERSION AS OF ; +``` + +### Часто используемые Trino SQL + +```sql +SHOW SCHEMAS FROM lakehouse; +SHOW TABLES FROM lakehouse.silver; +DESCRIBE lakehouse.silver.nyc_taxi_yellow; + +-- Time travel (синтаксис Trino) +SELECT * FROM
FOR VERSION AS OF ; +``` + +### Монтирование (хост → контейнер) + +| Хост | Контейнер | Режим | +| --- | --- | --- | +| `./notebooks` | `/opt/work` | read-write | +| `./src` | `/opt/src` | read-only | +| `./data` | `/opt/data` | read-only | + ## Когда какой документ использовать - `README.md` — чтобы понять, что это за репозиторий и куда идти дальше. - `START_HERE.md` — чтобы впервые поднять стенд и пройти Модуль 1. -- `stack_reference.md` — чтобы быстро вспомнить порты, команды, точки доступа и smoke-тесты. +- `stack_reference.md` — чтобы быстро вспомнить порты, команды, точки доступа, шпаргалку и smoke-тесты. - `course_program.md` — чтобы понять учебную траекторию дальше первого модуля. +- `glossary.md` — чтобы вернуться к определению термина (storage, catalog, compute, snapshot и др.). +- `mentor_notes.md` — заметки для ведения курса с ментором (опционально).