From 9d84e15e01573681792bc0391260e34b006c430e Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Fri, 6 Mar 2026 23:45:37 +0300 Subject: [PATCH] =?UTF-8?q?docs(course):=20=D0=B0=D1=80=D1=85=D0=B8=D0=B2?= =?UTF-8?q?=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D0=BD=20legacy=20HOWTO=20=D0=B8?= =?UTF-8?q?=20=D0=BE=D0=B1=D0=BD=D0=BE=D0=B2=D0=BB=D0=B5=D0=BD=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - нужно убрать устаревший учебный маршрут из student-facing документов, но сохранить старые лабораторные как reference-материал. - Что: - HOWTO.md перенесен в docs/archive/legacy_howto.md и помечен как архивный legacy-документ. - README.md больше не отправляет студента в устаревший HOWTO и ссылается на актуальную программу курса. - Проверка: - просмотрен git diff -- README.md HOWTO.md docs/archive/legacy_howto.md. - проверен git diff --cached --stat перед коммитом. --- README.md | 4 +- HOWTO.md => docs/archive/legacy_howto.md | 60 ++++++++++++++++-------- 2 files changed, 42 insertions(+), 22 deletions(-) rename HOWTO.md => docs/archive/legacy_howto.md (75%) mode change 100755 => 100644 diff --git a/README.md b/README.md index 5c51372..85963df 100755 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ graph LR - MinIO Console: `http://localhost:9001` - JupyterLab (если включён): `http://localhost:8888` -4. Для пошаговых лабораторных работ см. файл `HOWTO.md`. +4. Актуальная структура курса описана в `docs/course_program.md`. --- @@ -381,7 +381,7 @@ spark.sql("INSERT INTO lakehouse.default.spark_table VALUES (1, 'Alice'), (2, 'B * Добавить отдельные каталоги Trino (например, `hive`, `tpch`) для демонстрации федеративных запросов. * Добавить пример интеграции с BI-инструментом (DBeaver/Metabase/Superset) поверх Trino. -Для пошаговых учебных сценариев (лабораторных работ) см. файл `HOWTO.md`. +Актуальная структура курса описана в `docs/course_program.md`. Старый `HOWTO` сохранён как архивный материал в `docs/archive/legacy_howto.md`. --- diff --git a/HOWTO.md b/docs/archive/legacy_howto.md old mode 100755 new mode 100644 similarity index 75% rename from HOWTO.md rename to docs/archive/legacy_howto.md index 4be75ef..ed076b5 --- a/HOWTO.md +++ b/docs/archive/legacy_howto.md @@ -1,3 +1,23 @@ +# Legacy HOWTO: ранние лабораторные по Lakehouse-стенду + +Этот документ сохранён как архивный материал и не является актуальным учебным маршрутом для курса `Lakehouse без магии`. + +Зачем он сохранён: + +* в нём есть полезные ранние учебные сценарии и привязка к существующим demo-скриптам; +* он помогает понять, как эволюционировал стенд и какие практики уже когда-то обкатывались; +* его можно использовать как reference при создании новых ноутбуков и стартовой документации. + +Почему это legacy: + +* документ был написан до текущего PRD и новой программы курса; +* он смешивает актуальные темы с темами вне обязательного трека `v1`, например с отдельной лабой про партиционирование; +* он не соответствует новой структуре материалов `README -> START_HERE -> course_program -> notebooks`. + +Ниже сохранено исходное содержимое старого `HOWTO.md` почти без изменений. + +--- + # HOWTO: Учебные лабораторные по Lakehouse-стенду Этот файл описывает пошаговые учебные сценарии (лабораторные работы), которые можно выполнять поверх стенда из `docker-compose.yml`. @@ -6,29 +26,29 @@ Лабораторки опираются на примеры в `src/`: -- `src/spark/cluster_smoke.py` — проверка, что Spark‑кластер жив. -- `src/spark/iceberg_demo.sql` — первая Iceberg‑таблица в Spark. -- `src/spark/iceberg_smoke.py` — Spark создаёт Iceberg‑таблицу и читает её. +- `src/spark/cluster_smoke.py` — проверка, что Spark-кластер жив. +- `src/spark/iceberg_demo.sql` — первая Iceberg-таблица в Spark. +- `src/spark/iceberg_smoke.py` — Spark создаёт Iceberg-таблицу и читает её. - `src/trino/iceberg_smoke.sql` — Trino читает таблицу, созданную в Spark. Все команды ниже выполняются из корня репозитория. Краткая карта лабораторных: -- **Лаба 0** — стенд поднят, Spark‑кластер жив. -- **Лаба 1** — первая Iceberg‑таблица в Spark. +- **Лаба 0** — стенд поднят, Spark-кластер жив. +- **Лаба 1** — первая Iceberg-таблица в Spark. - **Лаба 2** — общий каталог Spark ↔ Trino. - **Лаба 3** — партиционирование и эволюция схемы. -- **Лаба 4** — мини‑ETL поверх Lakehouse (эскиз). +- **Лаба 4** — мини-ETL поверх Lakehouse (эскиз). --- -## Лаба 0. Стенд поднят, Spark‑кластер жив +## Лаба 0. Стенд поднят, Spark-кластер жив **Цель** - Убедиться, что все контейнеры поднялись. -- Проверить, что Spark‑кластер (master + workers) работает. +- Проверить, что Spark-кластер (master + workers) работает. **Предусловия** @@ -52,7 +72,7 @@ Ожидаем, что `spark-master`, `spark-worker-1`, `spark-worker-2` в статусе `Up`. -3. Запустить smoke‑скрипт кластера из контейнера `spark-master`: +3. Запустить smoke-скрипт кластера из контейнера `spark-master`: ```bash docker compose exec spark-master \ @@ -71,11 +91,11 @@ --- -## Лаба 1. Первая Iceberg‑таблица из Spark +## Лаба 1. Первая Iceberg-таблица из Spark **Цель** -- Создать Iceberg‑таблицу с помощью Spark SQL. +- Создать Iceberg-таблицу с помощью Spark SQL. - Посмотреть файлы таблицы в MinIO (`warehouse/default/demo_tbl/...`). **Предусловия** @@ -91,7 +111,7 @@ /opt/spark/bin/spark-sql ``` -2. Выполнить учебный SQL‑скрипт: +2. Выполнить учебный SQL-скрипт: - Внутри интерактивной сессии `spark-sql`: @@ -127,7 +147,7 @@ возвращает данные. -- В MinIO видна структура Iceberg‑таблицы: служебные файлы и файлы данных. +- В MinIO видна структура Iceberg-таблицы: служебные файлы и файлы данных. --- @@ -135,7 +155,7 @@ **Цель** -- Показать, что Spark и Trino используют общий Iceberg‑каталог (метаданные в Postgres, данные в MinIO). +- Показать, что Spark и Trino используют общий Iceberg-каталог (метаданные в Postgres, данные в MinIO). - Создать таблицу из Spark и прочитать её через Trino. **Предусловия** @@ -145,7 +165,7 @@ **Шаги** -1. Создать таблицу и записать данные из Spark (PySpark‑скрипт): +1. Создать таблицу и записать данные из Spark (PySpark-скрипт): ```bash docker compose exec spark-master \ @@ -169,7 +189,7 @@ 3. Прочитать ту же таблицу из Trino: -- Вариант через заранее скопированный SQL‑файл (как в README): +- Вариант через заранее скопированный SQL-файл (как в README): ```bash docker compose cp src/trino/iceberg_smoke.sql trino:/tmp/ @@ -211,7 +231,7 @@ **Подготовленные примеры** -- `src/spark/partitioned_table_demo.sql` — создание партиционированной Iceberg‑таблицы и вставка данных. +- `src/spark/partitioned_table_demo.sql` — создание партиционированной Iceberg-таблицы и вставка данных. - `src/spark/schema_evolution_demo.sql` — демонстрация `ALTER TABLE` и добавления колонок. - `src/trino/schema_evolution_demo.sql` — чтение той же таблицы с эволюцией схемы из Trino. - `notebooks/03_partitioning_and_schema_evolution.ipynb` — интерактивный разбор тех же примеров в Jupyter. @@ -271,7 +291,7 @@ docker compose exec trino trino --file /tmp/schema_evolution_demo.sql ``` -**Вариант B: через Jupyter‑ноутбук** +**Вариант B: через Jupyter-ноутбук** - Открыть `http://localhost:8888` и запустить ноутбук `03_partitioning_and_schema_evolution.ipynb`. - Ноутбук: @@ -281,12 +301,12 @@ --- -## Лаба 4. Мини‑ETL поверх Lakehouse (эскиз) +## Лаба 4. Мини-ETL поверх Lakehouse (эскиз) Идея лабы — собрать end-to-end сценарий: - есть сырые данные (CSV/JSON) в S3/MinIO; -- Spark читает raw‑данные, чистит и пишет в Iceberg‑таблицу; +- Spark читает raw-данные, чистит и пишет в Iceberg-таблицу; - Trino делает поверх неё аналитику. Планируемые компоненты: