From d69fec2bf50c9234c2a029e22eabfe2d071c2557 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sat, 7 Mar 2026 01:18:29 +0300 Subject: [PATCH] =?UTF-8?q?docs(plans):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=20=D0=BF=D0=BB=D0=B0=D0=BD=20=D0=9C=D0=BE?= =?UTF-8?q?=D0=B4=D1=83=D0=BB=D1=8F=202=20=D0=B8=20=D0=BE=D0=B1=D0=BD?= =?UTF-8?q?=D0=BE=D0=B2=D0=BB=D0=B5=D0=BD=D1=8B=20=D0=B7=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D1=81=D0=B8=D0=BC=D0=BE=D1=81=D1=82=D0=B8=20=D1=81=D1=82=D0=B5?= =?UTF-8?q?=D0=BD=D0=B4=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - необходимо зафиксировать структуру второго модуля «Ментальная модель Lakehouse» и подготовить инфраструктуру для инспекции компонентов. - Что: - создан файл plans/module-02-lakehouse-mental-model.md с детальным планом работ, целями и чекпоинтом. - в jupyter/Dockerfile добавлены библиотеки boto3 и psycopg2-binary для программного доступа к MinIO и PostgreSQL из ноутбуков. - модуль 2 добавлен в общий индекс планов в plans/README.md. - Проверка: - файл плана соответствует методике курса, в Dockerfile запинены версии библиотек. --- jupyter/Dockerfile | 7 ++- plans/README.md | 1 + plans/module-02-lakehouse-mental-model.md | 64 +++++++++++++++++++++++ 3 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 plans/module-02-lakehouse-mental-model.md diff --git a/jupyter/Dockerfile b/jupyter/Dockerfile index cacf393..9bddc20 100755 --- a/jupyter/Dockerfile +++ b/jupyter/Dockerfile @@ -4,8 +4,11 @@ FROM de-spark-iceberg:3.5.1 USER root ENV DEBIAN_FRONTEND=noninteractive -# Только JupyterLab, без дополнительных пакетов -RUN pip3 install --no-cache-dir "jupyterlab==4.2.5" +# Устанавливаем JupyterLab и пакеты для инспекции стенда (MinIO, PostgreSQL) +RUN pip3 install --no-cache-dir \ + "jupyterlab==4.2.5" \ + "boto3>=1.35,<2" \ + "psycopg2-binary>=2.9,<3" # Создаём непривилегированного пользователя ARG NB_USER=jovyan diff --git a/plans/README.md b/plans/README.md index bcbac09..8d8aa87 100644 --- a/plans/README.md +++ b/plans/README.md @@ -14,3 +14,4 @@ | Модуль | План | Статус | Целевые артефакты | Обновлён | | --- | --- | --- | --- | --- | | 1. Вход в стенд и базовая диагностика | [module-01-environment-and-basic-diagnostics.md](./module-01-environment-and-basic-diagnostics.md) | Ready for validation | `START_HERE.md`, `notebooks/01_environment_and_smoke_test.ipynb`, `src/spark/cluster_smoke.py` | 2026-03-06 | +| 2. Ментальная модель Lakehouse: storage, catalog, compute | [module-02-lakehouse-mental-model.md](./module-02-lakehouse-mental-model.md) | Draft | `notebooks/02_lakehouse_mental_model.ipynb` | 2026-03-07 | diff --git a/plans/module-02-lakehouse-mental-model.md b/plans/module-02-lakehouse-mental-model.md new file mode 100644 index 0000000..ad62844 --- /dev/null +++ b/plans/module-02-lakehouse-mental-model.md @@ -0,0 +1,64 @@ +# Модуль 2. Ментальная модель Lakehouse: storage, catalog, compute + +**Статус:** `Draft` +**Последнее обновление:** `2026-03-07` + +## Цель + +Убрать "магическое" восприятие Lakehouse и связать новую модель с привычным миром классических монолитных СУБД (PostgreSQL/Greenplum). Студент должен на практике увидеть физическое разделение ролей: где лежат данные, где хранятся метаданные, и кто выполняет вычисления. + +## Результат для студента + +После прохождения модуля студент: + +- понимает, что таблица в Lakehouse в практическом смысле — это согласованный набор файлов данных и метаданных; +- может проследить цепочку записи `Spark -> catalog -> MinIO` на примере маленькой demo-таблицы; +- осознает разницу между "одной базой данных" и набором независимых компонентов Lakehouse; +- умеет находить физические артефакты таблицы в объектном хранилище (MinIO); +- умеет находить записи о таблице в каталоге метаданных (PostgreSQL); +- не путает физическое хранение с логической таблицей. + +## Deliverables + +- `notebooks/02_lakehouse_mental_model.ipynb` как основной ноутбук Модуля 2; +- Подготовленные диагностические шаги (например, вспомогательные функции в `src/spark` или запросы/скрипты прямо в ноутбуке) для инспекции MinIO и PostgreSQL; +- Обновление индекса планов в `plans/README.md`. + +## План работ + +1. Подготовить структуру `notebooks/02_lakehouse_mental_model.ipynb` по методике курса: `объяснение -> демонстрация -> самостоятельное повторение -> checkpoint`. +2. Написать короткий теоретический блок с параллелями: классический DWH (Greenplum/Postgres) vs. Lakehouse (Storage + Catalog + Compute). +3. Сделать готовую демонстрацию: создание отдельного namespace (например, `lakehouse.module_02`) и небольшой demo-таблицы через Spark, запись пары строк. Для обеспечения идемпотентности и чистоты при повторном прохождении использовать `CREATE OR REPLACE TABLE` (или очистку таблицы перед записью) и конструкции `IF NOT EXISTS` для namespace. +4. Разработать шаги для инспекции: + - запрос к PostgreSQL (каталогу метаданных), чтобы увидеть регистрацию таблицы; + - запрос к MinIO (например, s3a list или boto3), чтобы увидеть появление файлов данных (parquet) и метаданных (json/avro). +5. Сформулировать самостоятельное задание: студент создает свою таблицу, пишет в нее данные и находит её следы в хранилище и каталоге. +6. Включить в конец ноутбука обязательный шаг очистки (cleanup) — удаление таблиц и namespace `module_02`, чтобы не оставлять мусор для следующих модулей. +7. Описать вопросы для Checkpoint. + +## Checkpoint + +Студент должен уметь: + +- показать конкретные файлы данных и метаданных созданной таблицы в MinIO (через UI или код); +- показать запись о таблице в PostgreSQL и объяснить, на что указывает поле `metadata_location`; +- объяснить, что произойдёт, если удалить файлы из MinIO, но не трогать каталог (или наоборот); +- сопоставить эти наблюдения с ролями `storage` и `catalog`. + +## Acceptance Criteria + +- Ноутбук `02_lakehouse_mental_model.ipynb` полностью раскрывает тему декомпозиции Lakehouse без глубокого погружения в спецификацию Iceberg. +- Демонстрации работают в локальном окружении (Jupyter) и наглядно показывают изменения в MinIO и PostgreSQL. +- Самостоятельное задание выполнимо на базе показанных примеров. +- Модуль 2 добавлен в индекс `plans/README.md`. + +## Риски + +- Излишнее углубление во внутренности Iceberg-манифестов. Нужно держать фокус только на факте их наличия и разделения `data/metadata`. +- Доступность PostgreSQL/MinIO из Jupyter: необходимо убедиться, что в `jupyter/Dockerfile` установлены `boto3` и `psycopg2-binary`, а также учитывать DNS-резолв `postgres-iceberg` из контейнера `jupyter` (сеть `spark-net` это позволяет, но могут быть нюансы). + +## Out of Scope + +- Загрузка и чтение сырых данных (NYC Taxi) — отложено до Модуля 3. +- Сложные трансформации. +- Чтение одной таблицы двумя движками (Spark и Trino) — отложено до Модуля 6 (в этом модуле чтение демо-таблицы будет только через Spark SQL для базовой верификации записи).