# Модуль 2. Ментальная модель Lakehouse: storage, catalog, compute

**Статус:** `Ready for validation`
**Последнее обновление:** `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 для базовой верификации записи).