From 7c5e9764056139febc9f24865763192020ac9855 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Tue, 15 Sep 2026 09:01:41 -0400 Subject: [PATCH] feat(course): add SparkSession setup practice to module 3 --- README.md | 2 + START_HERE.md | 2 +- docs/course_prd.md | 4 + docs/course_program.md | 18 +- docs/glossary.md | 16 + docs/stack_reference.md | 21 ++ notebooks/03_raw_ingest_and_first_read.ipynb | 343 ++++++++++++++++++- plans/course-roadmap.md | 6 +- plans/issue-2-spark-session-validation.md | 91 +++++ plans/module-03-raw-ingest-and-first-read.md | 42 ++- 10 files changed, 523 insertions(+), 22 deletions(-) create mode 100644 plans/issue-2-spark-session-validation.md diff --git a/README.md b/README.md index 166b9c9..c9feaef 100755 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ Курс рассчитан на `~12-15 часов` самостоятельной работы. Каждый модуль: объяснение, демонстрация, самостоятельное задание, checkpoint. +В начале [модуля 3](notebooks/03_raw_ingest_and_first_read.ipynb) ты настроишь Spark-сессию для кластера и проверишь доступ к Iceberg и MinIO. На эту практику отведено 20–30 минут; общая оценка курса пока предварительная. + ## Стек Всё работает локально в Docker. Никаких облаков, внешних зависимостей и регистраций. diff --git a/START_HERE.md b/START_HERE.md index f4ad300..7bffd46 100644 --- a/START_HERE.md +++ b/START_HERE.md @@ -204,6 +204,6 @@ ls -lh data/nyc_taxi/ - пройти `notebooks/01_environment_and_smoke_test.ipynb`; - пройти `notebooks/02_lakehouse_mental_model.ipynb`; -- подготовить data bundle по инструкции выше и пройти `notebooks/03_raw_ingest_and_first_read.ipynb`; +- подготовить data bundle по инструкции выше и пройти [модуль 3](notebooks/03_raw_ingest_and_first_read.ipynb): сначала настроить Spark-сессию и проверить подключение, затем загрузить и прочитать raw-данные; - свериться с программой курса в `docs/course_program.md`; - после прохождения первых модулей переходить к следующим учебным материалам. diff --git a/docs/course_prd.md b/docs/course_prd.md index 34d0159..7aa53e8 100644 --- a/docs/course_prd.md +++ b/docs/course_prd.md @@ -55,6 +55,7 @@ 5. Умеет реализовать простой поток `raw -> bronze -> silver` с базовыми трансформациями и сохранением воспроизводимости шагов. 6. Умеет читать одну и ту же таблицу из `Spark` и `Trino` и понимает, почему это возможно без копирования данных. 7. Умеет выполнить базовые безопасные операции с таблицей: изменение схемы, просмотр snapshot-ов, чтение предыдущего состояния, базовый `compaction` и `vacuum`. +8. Умеет создать `SparkSession` для кластера с подготовленным каталогом, проверить фактические настройки и объяснить, какие из них можно изменить в работающей сессии, а для каких нужен новый запуск. Трассировка этих outcomes на модули и checkpoints фиксируется в [course_program.md](./course_program.md). @@ -91,6 +92,7 @@ * работа с raw-данными; * построение слоев `bronze` и `silver`; * чтение и запись через `Spark`; +* обязательная практика базовой настройки `SparkSession` в начале модуля 3: источники конфигурации, подключение к кластеру, проверка Iceberg/MinIO и жизненный цикл сессии; * чтение через `Trino`; * базовое schema evolution; * snapshot/time travel на прикладном уровне; @@ -147,6 +149,7 @@ Это целевые ориентиры курса, но не blocking acceptance criteria для материалов. 1. Студент проходит курс за `~12-15 часов` вдумчивой работы. + Практика настройки сессии в модуле 3 рассчитана на 20–30 минут внутри этого диапазона. Это предварительная оценка: машинный прогон не измеряет время самостоятельной работы студента. 2. Студент после курса способен безопасно выполнить базовые операции в Lakehouse-стенде без постоянной внешней помощи. 3. Студент может внятно объяснить ключевые архитектурные принципы Lakehouse на уровне junior/middle interview readiness. @@ -155,6 +158,7 @@ 1. В составе курса есть стартовая документация до первого ноутбука, включая prerequisites, запуск стенда, вход в `Jupyter` и получение учебного data bundle. 2. Студент проходит обязательные `checkpoints` по урокам. 3. Студент самостоятельно выполняет набор практик на одном датасете, включая: + * создание Spark-сессии по шаблону и проверку подключения на отдельной маленькой Iceberg-таблице; * загрузку raw-данных; * построение `bronze`; * построение `silver`; diff --git a/docs/course_program.md b/docs/course_program.md index 149424c..7c5fae0 100644 --- a/docs/course_program.md +++ b/docs/course_program.md @@ -10,6 +10,8 @@ **Ориентир на модуль:** в среднем `~1.5 часа`, но финальная практика может занять дольше. +В модуле 3 дополнительно предусмотрены 20–30 минут на настройку Spark-сессии; ориентир на весь модуль — около 2 часов. Общие `~12-15 часов` пока остаются предварительной оценкой: её нужно уточнить после самостоятельного прохождения студентом. + **Сквозной учебный кейс:** `NYC TLC Yellow Taxi Trip Records` + `Taxi Zone Lookup`. **Методика каждого урока:** `объяснение -> демонстрация -> самостоятельное повторение -> checkpoint`. @@ -74,6 +76,7 @@ | `LO5`. Умение собрать поток `raw -> bronze -> silver` | 4, 5, 8 | checkpoints модулей 5 и 8 | | `LO6`. Умение читать одну таблицу из `Spark` и `Trino` | 6, 8 | checkpoint модуля 6 и финальная практика | | `LO7`. Умение выполнять безопасные операции с таблицей | 7, 8 | checkpoints модулей 7 и 8 | +| `LO8`. Умение настроить Spark-сессию и проверить подключение | 3 | checkpoint практики настройки в начале модуля 3 | ## 5. Верхнеуровневая структура практической части @@ -124,10 +127,15 @@ **Рабочее название ноутбука:** `03_raw_ingest_and_first_read.ipynb` -**Зачем нужен:** показать, как raw-данные попадают в стенд и как с ними безопасно начать работать. +**Зачем нужен:** научить создавать Spark-сессию для нашего кластера, затем загружать и читать raw-данные. **Содержание:** +* обязательная практика «Как настроен Spark в нашем стенде» после ментальной модели модуля 2, до raw-ingest (20–30 минут); +* роли `SparkSession`, `SparkContext`, driver и executors; `master`, `appName`, `getOrCreate`, отличие `local` от кластера; +* настройки из `spark-defaults.conf`, параметров запуска и кода; подготовленный каталог Iceberg и доступ к MinIO; +* проверка фактического master и выбранных несекретных настроек; повторная ячейка, остановка сессии и перезапуск ядра; +* изменение часового пояса с восстановлением исходного значения и смена имени приложения при новом запуске; без подбора памяти, executors, shuffle или GC; * работа с заранее подготовленным локальным data bundle из onboarding-документации; * явная загрузка исходных `PARQUET`-файлов в raw-зону; * чтение raw-данных через Spark; @@ -136,13 +144,18 @@ **Практика студента:** +* выполнить демонстрацию настройки сессии, затем заполнить шаблон с адресом кластера и именем приложения, используя подготовленный каталог; +* проверить подключение на собственной маленькой Iceberg-таблице, прочитать две строки и удалить только эту таблицу; данные модуля 2 не нужны; +* объяснить происхождение настроек и повторить создание сессии после перезапуска ядра; * проверить состав локально полученного набора `NYC Taxi`; * загрузить его в raw-зону `MinIO`; * прочитать несколько месяцев `NYC Taxi`; * проверить схему и посчитать базовые метрики; * найти простые аномалии или проблемные значения. -**Checkpoint:** студент умеет загрузить учебный набор в raw-зону, прочитать raw-данные, проверить схему и объяснить, почему raw-слой нужен как воспроизводимая точка входа. +**Checkpoint настройки:** master равен `spark://spark-master:7077`, имя приложения совпадает с заданным, из собственной Iceberg-таблицы прочитаны строки `0` и `1`, временная таблица удалена. Часовой пояс восстановлен. Студент объясняет, что задал в коде, что взял из стенда, где выполняются вычисления и какие ячейки повторит после перезапуска ядра. + +**Checkpoint raw-ingest:** студент умеет загрузить учебный набор в raw-зону, прочитать raw-данные, проверить схему и объяснить, почему raw-слой нужен как воспроизводимая точка входа. ### Модуль 4. Первая рабочая Iceberg-таблица и слой bronze @@ -261,6 +274,7 @@ 5. Умеет построить простой поток `raw -> bronze -> silver`. 6. Умеет читать одну и ту же таблицу из `Spark` и `Trino`. 7. Умеет выполнять базовые безопасные операции: schema evolution, snapshots/time travel, compaction, vacuum. +8. Создаёт Spark-сессию для кластера, проверяет настройки и понимает, когда нужен новый запуск. ## 7. Что не входит в первую версию курса diff --git a/docs/glossary.md b/docs/glossary.md index f2f1782..1af1833 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -44,6 +44,22 @@ **Параллель с DWH:** в классическом DWH вычислитель один, поэтому проблема не возникает. **Где в курсе:** Модуль 6. +## Spark-сессия и выполнение + +### SparkSession + +Точка входа в DataFrame и Spark SQL: объект `spark` в ноутбуке. Builder задаёт параметры, а `getOrCreate()` создаёт сессию или возвращает уже работающую. + +### SparkContext + +Связывает Spark-приложение с вычислительными ресурсами. Через `spark.sparkContext` можно проверить фактические `master`, `appName` и `applicationId`. Повторный builder не заменяет работающий контекст. + +### Driver и executors + +Driver управляет приложением: выполняет код ноутбука, строит план и отправляет задания. Executors выполняют задания и читают данные. В нашем стенде driver работает в `jupyter`, executors запускаются на Spark worker-ах. Master выделяет приложению ресурсы worker-ов. + +**Где в курсе:** [практика настройки в модуле 3](../notebooks/03_raw_ingest_and_first_read.ipynb). + ## Структура Iceberg-таблицы ### Namespace diff --git a/docs/stack_reference.md b/docs/stack_reference.md index a4e8b3a..2723f10 100644 --- a/docs/stack_reference.md +++ b/docs/stack_reference.md @@ -64,6 +64,27 @@ docker compose down -v или настройки в файле, перезапусти ядро ноутбука и снова выполни ячейки с импортами и созданием сессии. +Практика с объяснением, шаблоном и проверкой подключения находится в начале +[модуля 3](../notebooks/03_raw_ingest_and_first_read.ipynb). +В ней `spark.sparkContext.master` и `.appName` показывают фактический кластер +и имя приложения. Для SQL-настроек используется `spark.conf.get(...)`; +вывод ограничен конкретными несекретными ключами. + +В Spark 3.5.1 `spark.sql.session.timeZone` можно менять через +`spark.conf.set(...)` во время работы, сохранив и восстановив исходное значение. +Повторный builder с другим `appName` использует прежний контекст и не меняет +его фактическое имя. После `spark.stop()` новый контекст получает новое имя; +при смене master или общего файла конфигурации перезапусти ядро. +`stop()` оставляет переменные Python, перезапуск ядра удаляет их. +Оба действия сохраняют таблицы в каталоге и файлы MinIO. + +Параметры обычного нового приложения имеют приоритет: код → параметры +`spark-submit` → `spark-defaults.conf`. Настройки запуска driver-а нужно +передавать до его старта. Вне стенда также потребуются зависимости и конфигурация +Iceberg/S3A/JDBC из [`spark/Dockerfile`](../spark/Dockerfile) и общего файла. +Подробности: [конфигурация Spark 3.5.1](https://github.com/apache/spark/blob/v3.5.1/docs/configuration.md) +и [поведение SparkSession в этой версии](https://github.com/apache/spark/blob/v3.5.1/python/pyspark/sql/session.py). + Пример запуска smoke-скрипта: ```bash diff --git a/notebooks/03_raw_ingest_and_first_read.ipynb b/notebooks/03_raw_ingest_and_first_read.ipynb index e867b9c..0640657 100644 --- a/notebooks/03_raw_ingest_and_first_read.ipynb +++ b/notebooks/03_raw_ingest_and_first_read.ipynb @@ -9,13 +9,14 @@ "\n", "В этом модуле мы разбираем полный первый цикл работы с учебным датасетом в Lakehouse:\n", "\n", + "- создаём Spark-сессию для кластера и проверяем её настройки;\n", "- проверяем заранее скачанный локальный data bundle;\n", "- загружаем исходные файлы в raw-зону `MinIO`;\n", "- читаем raw-данные через `Spark` по `s3a://` пути;\n", "- смотрим схему, типы, базовые метрики и простые аномалии;\n", "- фиксируем, почему raw-слой нужен как воспроизводимая неизменяемая точка входа.\n", "\n", - "После этого ноутбука ты должен уметь объяснить, почему raw-данные не надо «чинить на месте» и почему их не стоит скачивать прямо из ноутбука.\n" + "После этого ноутбука ты должен уметь объяснить, почему raw-данные не надо «чинить на месте» и почему их не стоит скачивать прямо из ноутбука." ] }, { @@ -29,7 +30,8 @@ "\n", "- подними стенд по `START_HERE.md`;\n", "- пройди `notebooks/01_environment_and_smoke_test.ipynb`;\n", - "- желательно пройти `notebooks/02_lakehouse_mental_model.ipynb`;\n", + "- пройди `notebooks/02_lakehouse_mental_model.ipynb`;\n", + "- начни с нового ядра, чтобы настройки не зависели от предыдущих опытов;\n", "- заранее скачай data bundle в `./data/nyc_taxi` по инструкции из `START_HERE.md`.\n", "\n", "В классическом `PostgreSQL / Greenplum` данные часто уже лежат внутри системы. В Lakehouse путь более явный: сначала исходные файлы должны попасть в object storage, и только потом мы начинаем поверх них читать, профилировать и строить таблицы.\n", @@ -38,7 +40,334 @@ "| --- | --- | --- |\n", "| Где стартует работа | Данные уже внутри СУБД | Исходные файлы сначала попадают в storage |\n", "| Первая практическая задача | `SELECT` из готовой таблицы | Загрузить raw и прочитать raw |\n", - "| Что важно не сломать | Таблицу / схему БД | Неизменяемый raw-слой |\n" + "| Что важно не сломать | Таблицу / схему БД | Неизменяемый raw-слой |" + ] + }, + { + "cell_type": "markdown", + "id": "session-intro", + "metadata": {}, + "source": [ + "## 0.1. Как настроен Spark в нашем стенде\n", + "\n", + "Отведи на эту практику 20–30 минут. Сначала разберём готовый пример, затем ты заполнишь шаблон и проверишь подключение. Файлы Taxi понадобятся после практики.\n", + "\n", + "`SparkSession` — объект `spark`, через который мы читаем DataFrame и выполняем SQL. Внутри него `SparkContext` связывает приложение с вычислительными ресурсами. В обычном ядре нашего ноутбука используется один работающий контекст.\n", + "\n", + "| Участник | Что делает в этом стенде |\n", + "| --- | --- |\n", + "| Driver | Работает в контейнере `jupyter`: выполняет Python-код ноутбука, строит план и раздаёт задания |\n", + "| Master | Принимает подключение по `spark://spark-master:7077` и выделяет ресурсы worker-ов |\n", + "| Executors | Запускаются на `spark-worker-1` и `spark-worker-2`, читают данные и выполняют задания |\n", + "\n", + "В режиме `local[*]` Spark выполняет задания локально, используя потоки на машине driver-а. В нашем курсе нужен кластер: успешный `count()` сам по себе ещё не доказывает, что подключение правильное.\n", + "\n", + "### Откуда берутся настройки\n", + "\n", + "Для новой сессии стенд читает `spark/spark-defaults.conf`, смонтированный в Jupyter как `/opt/spark/conf/spark-defaults.conf`. В нём уже заданы master, каталог и доступ к MinIO.\n", + "\n", + "При запуске приложения через `spark-submit` можно передать `--master`, `--name` и `--conf`. В коде похожие настройки задают методы builder-а: `.master(...)`, `.appName(...)`, `.config(...)`. Обычно приоритет такой: код → параметры запуска → файл defaults. Но уже запущенный контекст не перестраивается от нового вызова builder-а, а параметры запуска driver-а надо передавать до его старта.\n", + "\n", + "В нашем Jupyter дополнительные `--master`/`--conf` при запуске не передаются. Готовый пример ниже берёт master из файла, а имя задаёт в коде. Вне стенда понадобятся также библиотеки Iceberg/S3A/JDBC и конфигурация каталога: одного адреса master недостаточно. Пути и состав образа описаны в [справочнике стенда](../docs/stack_reference.md#spark)." + ] + }, + { + "cell_type": "code", + "id": "session-demo", + "metadata": {}, + "source": [ + "from pyspark.sql import SparkSession\n", + "\n", + "spark = (\n", + " SparkSession.builder\n", + " .appName(\"module-03-session-demo\")\n", + " .getOrCreate()\n", + ")\n", + "spark.sparkContext.setLogLevel(\"ERROR\")\n", + "\n", + "print(\"Spark:\", spark.version)\n", + "print(\"Master:\", spark.sparkContext.master)\n", + "print(\"Приложение:\", spark.sparkContext.appName)\n", + "assert spark.sparkContext.master == \"spark://spark-master:7077\", \"Нужен Spark-кластер стенда\"\n", + "print(\"Сумма 0…9:\", spark.range(10).groupBy().sum(\"id\").first()[0])" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "session-config-explanation", + "metadata": {}, + "source": [ + "`appName` — имя приложения, видимое в Spark UI. `getOrCreate()` создаёт сессию, если её ещё нет, или возвращает существующую. `.master(...)` выбирает вычислитель; в демонстрации он не указан, поэтому используется общий файл.\n", + "\n", + "### Что уже подготовлено для Iceberg и MinIO\n", + "\n", + "| Настройка в `spark-defaults.conf` | Назначение |\n", + "| --- | --- |\n", + "| `spark.sql.extensions` | Добавляет команды Iceberg к Spark SQL |\n", + "| `spark.sql.catalog.lakehouse` | Подключает Spark-каталог с именем `lakehouse` |\n", + "| `spark.sql.catalog.lakehouse.catalog-impl` и `.uri` | Выбирает JDBC-каталог в PostgreSQL, где зарегистрированы таблицы |\n", + "| `spark.sql.catalog.lakehouse.warehouse` | Задаёт место для файлов таблиц в MinIO: `s3a://lakehouse/warehouse` |\n", + "| `spark.hadoop.fs.s3a.endpoint` и `.path.style.access` | Направляют S3A-запросы в MinIO внутри Docker-сети |\n", + "\n", + "В том же файле находятся настройки доступа к PostgreSQL и MinIO. Выведем только выбранные несекретные значения. SQL-настройки читаем через `spark.conf`, master и имя — через `spark.sparkContext`. При передаче настроек в Hadoop префикс `spark.hadoop.` снимается." + ] + }, + { + "cell_type": "code", + "id": "session-config", + "metadata": {}, + "source": [ + "for key in (\n", + " \"spark.sql.extensions\",\n", + " \"spark.sql.catalog.lakehouse\",\n", + " \"spark.sql.catalog.lakehouse.catalog-impl\",\n", + " \"spark.sql.catalog.lakehouse.uri\",\n", + " \"spark.sql.catalog.lakehouse.warehouse\",\n", + "):\n", + " print(f\"{key} = {spark.conf.get(key)}\")\n", + "\n", + "hadoop_conf = spark.sparkContext._jsc.hadoopConfiguration()\n", + "for key in (\"fs.s3a.endpoint\", \"fs.s3a.path.style.access\"):\n", + " print(f\"{key} = {hadoop_conf.get(key)}\")" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "session-live-explanation", + "metadata": {}, + "source": [ + "### Что можно изменить во время работы\n", + "\n", + "`spark.sql.session.timeZone` задаёт часовой пояс SQL-сессии. У одной и той же секунды Unix-времени будет разное отображение в UTC и Москве. Это настройка интерпретации времени, без изменения файлов данных.\n", + "\n", + "Сохраним исходное значение и восстановим его в `finally`: оно вернётся даже при ошибке внутри опыта. Для Spark 3.5.1 эта настройка изменяется в работающей сессии." + ] + }, + { + "cell_type": "code", + "id": "session-live-config", + "metadata": {}, + "source": [ + "timezone_key = \"spark.sql.session.timeZone\"\n", + "original_timezone = spark.conf.get(timezone_key)\n", + "assert spark.conf.isModifiable(timezone_key)\n", + "try:\n", + " for timezone in (\"UTC\", \"Europe/Moscow\"):\n", + " spark.conf.set(timezone_key, timezone)\n", + " value = spark.sql(\"SELECT from_unixtime(0) AS displayed_time\").first()[0]\n", + " print(timezone, value)\n", + "finally:\n", + " spark.conf.set(timezone_key, original_timezone)\n", + "\n", + "assert spark.conf.get(timezone_key) == original_timezone\n", + "print(\"Исходный часовой пояс восстановлен:\", original_timezone)" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "session-reuse-explanation", + "metadata": {}, + "source": [ + "### Для чего нужен новый запуск\n", + "\n", + "Проверим `appName`: это имя приложения, которое запущено через `SparkContext`. Попробуем задать другое имя через builder и посмотрим на **фактическое** `spark.sparkContext.appName`.\n", + "\n", + "Повторное выполнение ячейки не останавливает приложение. `getOrCreate()` использует ту же сессию и тот же контекст; это не способ переключиться на другой master или переименовать уже запущенное приложение." + ] + }, + { + "cell_type": "code", + "id": "session-reuse", + "metadata": {}, + "source": [ + "demo_context = spark.sparkContext\n", + "demo_name = demo_context.appName\n", + "same_spark = (\n", + " SparkSession.builder\n", + " .appName(\"module-03-raw-ingest-and-first-read\")\n", + " .getOrCreate()\n", + ")\n", + "assert same_spark is spark\n", + "assert same_spark.sparkContext is demo_context\n", + "assert same_spark.sparkContext.appName == demo_name\n", + "print(\"То же приложение:\", same_spark.sparkContext.appName)" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "session-stop-explanation", + "metadata": {}, + "source": [ + "Теперь остановим демонстрационную сессию. В следующем задании новый контекст получит новое имя.\n", + "\n", + "- **Повторный запуск ячейки** сохраняет переменные Python и может использовать уже работающий контекст.\n", + "- **`spark.stop()`** останавливает сессию и её контекст. Переменные Python остаются, но старые Spark DataFrame больше нельзя использовать. Файлы MinIO и записи каталога сохраняются.\n", + "- **Перезапуск ядра** заново запускает Python и связанный с ним Spark driver. Переменные исчезают; нужно повторить импорты, создание сессии и чтение DataFrame. Данные в MinIO и каталоге от этого не удаляются.\n", + "\n", + "Для смены master или конфигурации файла начинай с нового ядра. Остановка сессии без перезапуска ядра достаточна для нашего опыта с именем, но не заменяет новый процесс для всех стартовых настроек." + ] + }, + { + "cell_type": "code", + "id": "session-stop", + "metadata": {}, + "source": [ + "spark.stop()" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "session-exercise-explanation", + "metadata": {}, + "source": [ + "### Самостоятельно: создай сессию и проверь подключение\n", + "\n", + "Заполни три пропуска в следующей ячейке:\n", + "\n", + "1. Адрес кластера внутри Docker-сети.\n", + "2. Имя приложения `module-03-raw-ingest-and-first-read`.\n", + "3. Вызов builder-а с `.master(...)`, `.appName(...)` и `.getOrCreate()`.\n", + "\n", + "Используй подготовленный каталог из `spark-defaults.conf`: его параметры не нужно копировать в код. Явный `.master(...)` здесь нужен, чтобы ты самостоятельно указал подключение; остальные ноутбуки берут тот же адрес из файла.\n", + "\n", + "Шаблон остановится на `assert`, пока ты его не заполнишь. После заполнения выполни шаблон и ячейку проверки подключения дважды: имя и `applicationId` должны остаться теми же." + ] + }, + { + "cell_type": "code", + "id": "session-exercise", + "metadata": {}, + "source": [ + "from pyspark.sql import SparkSession\n", + "\n", + "CLUSTER_MASTER = ...\n", + "APP_NAME = ...\n", + "assert CLUSTER_MASTER == \"spark://spark-master:7077\", \"Впиши адрес кластера\"\n", + "assert APP_NAME == \"module-03-raw-ingest-and-first-read\", \"Впиши имя приложения\"\n", + "\n", + "# Замени ... цепочкой вызовов SparkSession.builder.\n", + "spark = ...\n", + "assert isinstance(spark, SparkSession), \"Создай SparkSession через builder\"\n", + "spark.sparkContext.setLogLevel(\"ERROR\")" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "session-solution", + "metadata": {}, + "source": [ + "
\n", + "Контрольное решение — открой после своей попытки\n", + "\n", + "```python\n", + "from pyspark.sql import SparkSession\n", + "\n", + "CLUSTER_MASTER = \"spark://spark-master:7077\"\n", + "APP_NAME = \"module-03-raw-ingest-and-first-read\"\n", + "spark = (\n", + " SparkSession.builder\n", + " .master(CLUSTER_MASTER)\n", + " .appName(APP_NAME)\n", + " .getOrCreate()\n", + ")\n", + "spark.sparkContext.setLogLevel(\"ERROR\")\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "code", + "id": "session-connection-check", + "metadata": {}, + "source": [ + "assert spark.sparkContext.master == CLUSTER_MASTER\n", + "assert spark.sparkContext.appName == APP_NAME\n", + "print(\"Master:\", spark.sparkContext.master)\n", + "print(\"Приложение:\", spark.sparkContext.appName)\n", + "print(\"ID приложения:\", spark.sparkContext.applicationId)" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "session-table-explanation", + "metadata": {}, + "source": [ + "### Проверь весь путь: Spark → каталог → MinIO\n", + "\n", + "Одного правильного master недостаточно: проверим запись и чтение через каталог. Ячейка сама создаёт маленькую Iceberg-таблицу с числами `0` и `1`, читает её и удаляет в `finally`. Таблицы модуля 2 не требуются.\n", + "\n", + "У таблицы уникальное имя. `DROP TABLE … PURGE` удаляет именно её запись в каталоге, файлы данных и метаданных. В MinIO могут остаться пустые маркеры каталогов `data/` и `metadata/`; это не данные таблицы. Пока ячейка работает, не перезапускай ядро: при принудительном завершении процесса `finally` не выполнится. Если это произошло, сохрани напечатанное имя для удаления этой таблицы после нового подключения.\n", + "\n", + "Это только проверка подключения; создание рабочей таблицы поездок изучим в модуле 4." + ] + }, + { + "cell_type": "code", + "id": "session-table-check", + "metadata": {}, + "source": [ + "from uuid import uuid4\n", + "\n", + "session_table = f\"lakehouse.default.session_practice_{uuid4().hex}\"\n", + "print(\"Временная таблица:\", session_table)\n", + "try:\n", + " spark.range(2).writeTo(session_table).using(\"iceberg\").create()\n", + " session_rows = [row.id for row in spark.table(session_table).orderBy(\"id\").collect()]\n", + " assert session_rows == [0, 1]\n", + " print(\"Прочитано через Iceberg:\", session_rows)\n", + "finally:\n", + " spark.sql(f\"DROP TABLE IF EXISTS {session_table} PURGE\")\n", + "\n", + "assert not spark.catalog.tableExists(session_table)\n", + "print(\"Временная таблица удалена\")" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "session-checkpoint", + "metadata": {}, + "source": [ + "### Checkpoint настройки\n", + "\n", + "Проверки выше должны подтвердить master `spark://spark-master:7077`, заданное имя приложения, строки `[0, 1]` и удаление временной таблицы. В опыте с часовым поясом исходное значение должно восстановиться.\n", + "\n", + "Ответь своими словами:\n", + "\n", + "1. Какие настройки ты задал в коде, а какие предоставил стенд? Где их найти?\n", + "2. Чем SparkSession отличается от SparkContext? Где работают driver и executors?\n", + "3. Почему повторный `getOrCreate()` не сменил имя демонстрационного приложения, а после `stop()` оно изменилось?\n", + "4. Что останется после перезапуска ядра и что потребуется выполнить заново?\n", + "\n", + "Теперь, когда временная таблица удалена, **перезапусти ядро**. Выполни заполненный шаблон, проверку подключения и ячейку с временной таблицей. Они должны работать без демонстрации и без состояния прошлого ядра; `applicationId` будет новым. Импорт `SparkSession` уже есть в шаблоне.\n", + "\n", + "После этой проверки продолжи ниже: подготовь переменные и MinIO-клиент, затем переходи к raw-данным. Сессию пока не останавливай." + ] + }, + { + "cell_type": "markdown", + "id": "raw-preparation", + "metadata": {}, + "source": [ + "## 0.2. Подготовка к raw-ingest\n", + "\n", + "Сессия из самостоятельного задания продолжает работать. Создадим MinIO-клиент и переменные для исходного сценария модуля." ] }, { @@ -63,10 +392,6 @@ "RAW_URI = f\"s3a://{BUCKET_NAME}/{RAW_PREFIX}\"\n", "ZONE_LOOKUP_RAW_URI = f\"{RAW_URI}taxi_zone_lookup.csv\"\n", "\n", - "spark = SparkSession.builder .appName(\"module-03-raw-ingest-and-first-read\") .getOrCreate()\n", - "\n", - "spark.sparkContext.setLogLevel(\"ERROR\")\n", - "\n", "s3 = boto3.client(\n", " \"s3\",\n", " endpoint_url=\"http://minio:9000\",\n", @@ -127,7 +452,7 @@ "\n", "\n", "print(\"Spark и MinIO-клиент готовы\")\n", - "print(f\"RAW URI: {RAW_URI}\")\n" + "print(f\"RAW URI: {RAW_URI}\")" ] }, { @@ -305,7 +630,7 @@ "- `spark.read.parquet(\"s3a://...\")` читает raw-файлы напрямую по физическому пути;\n", "- `spark.table(\"lakehouse....\")` читает уже зарегистрированную управляемую таблицу через каталог.\n", "\n", - "Сейчас мы ещё не создавали `Iceberg`-таблицу, поэтому работаем именно через `spark.read.parquet(...)`. К `spark.table(...)` вернёмся в Модуле 4.\n" + "Проверочную `Iceberg`-таблицу из практики настройки мы уже удалили. Поездки пока лежат отдельными raw-файлами, поэтому читаем их через `spark.read.parquet(...)`. Рабочую таблицу поездок создадим в Модуле 4." ] }, { diff --git a/plans/course-roadmap.md b/plans/course-roadmap.md index 28a30cc..8313ddf 100644 --- a/plans/course-roadmap.md +++ b/plans/course-roadmap.md @@ -1,6 +1,6 @@ # План развития курса «Lakehouse без магии» -Статус: подключение Spark исправлено; следующая работа — практика настройки сессии. +Статус: подключение Spark исправлено; практика настройки сессии по #2 подготовлена и проверена, ожидает ревью. Последнее обновление: 2026-09-15. Здесь собираем отзывы студентов, выбираем следующие улучшения и объясняем их порядок. Подробные задания, критерии приёмки и актуальный статус исполнения хранятся в [Gitea Issues](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues). @@ -36,7 +36,9 @@ Iceberg-таблицы. Результаты проверок и их огран ### 2. Добавить практику «Как настроен Spark в нашем стенде» -**Статус:** запланировано; можно приступать после завершения #1. +**Статус:** готово к ревью по #2; зависимость #1 закрыта, её итог прочитан. Практика добавлена в начало модуля 3, PRD, программа и справочные материалы обновлены. + +**Результат:** проверены демонстрация, заполненный шаблон и контрольное решение, повторные ячейки, настоящий перезапуск ядра, временная Iceberg-таблица и весь raw-ingest. Машинный прогон — 4 минуты 10 секунд; время самостоятельного прохождения студентом ещё не измерено. Подробности и ограничения — в [отчёте проверки](issue-2-spark-session-validation.md). **Задача:** [#2 — практика базовой настройки SparkSession](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/2). diff --git a/plans/issue-2-spark-session-validation.md b/plans/issue-2-spark-session-validation.md new file mode 100644 index 0000000..00e257e --- /dev/null +++ b/plans/issue-2-spark-session-validation.md @@ -0,0 +1,91 @@ +# Проверка практики SparkSession в модуле 3 + +Дата: 2026-09-15. +Задача: https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/2. +База: `00942c2`, результат закрытой [#1](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/1) прочитан вместе с комментариями. + +## Что проверялось + +Фактические ячейки `notebooks/03_raw_ingest_and_first_read.ipynb` выполнялись +через `jupyter_client.KernelManager` в контейнере `jupyter`, Spark 3.5.1. +Менеджер запускал настоящее IPython-ядро и перезапускал его через +`restart_kernel(now=True)`. Проверка не подменяла создание сессии общим helper-ом. + +Порядок воспроизведения: + +1. Поднять стенд и получить стандартный bundle по `START_HERE.md`. +2. В новом ядре выполнить демонстрацию, вывод настроек, опыт с часовым поясом, + повторный builder и остановку сессии. +3. Заполнить три пропуска шаблона, выполнить его дважды и сравнить контекст + и applicationId. Выполнить опубликованное контрольное решение + (при проверке извлекалось из блока `session-solution`). +4. Выполнить проверку master/appName и дважды создать, прочитать и удалить + временную таблицу. +5. Перезапустить ядро. Убедиться, что переменные `spark` и `CLUSTER_MASTER` + отсутствуют; выполнить контрольное решение, проверку подключения и таблицы. +6. Продолжить исходный raw-ingest до `spark.stop()`, заполнив самостоятельные + упражнения с lookup, top-5 локаций и ещё одной аномалией. +7. Отдельно проверить заполненный шаблон в новом ядре и повторную загрузку + уже существующих raw-файлов. + +## Результаты + +| Проверка | Результат | +| --- | --- | +| Демонстрационная сессия | Master `spark://spark-master:7077`, appName `module-03-session-demo`, сумма 0…9 = 45 | +| Настройки каталога | `SparkCatalog`, `JdbcCatalog`, URI PostgreSQL и warehouse соответствуют общему файлу; Hadoop endpoint `http://minio:9000`, path-style `true` | +| Изменяемая настройка | `spark.sql.session.timeZone` допускает изменение; Unix-время 0 отображается как `1970-01-01 00:00:00` в UTC и `1970-01-01 03:00:00` в Москве | +| Восстановление | В `finally` восстановлено исходное `Etc/UTC`, проверено через assert | +| Повторный builder с другим appName | Тот же объект сессии и контекста, фактическое имя остаётся `module-03-session-demo` | +| Создание после stop | Новое имя `module-03-raw-ingest-and-first-read`, master кластерный | +| Повторение шаблона и контрольного решения | Контекст и applicationId не меняются | +| Заполненный шаблон в отдельном новом ядре | Master и appName верны, распределённая сумма 0…9 = 45 | +| Перезапуск ядра | Переменные исчезли, сессия создана заново; ID изменился с `app-20260915125347-0001` на `app-20260915125511-0002` | +| Iceberg до и после перезапуска | Три независимые таблицы с уникальными именами; каждый раз прочитаны `[0, 1]`, после PURGE таблица отсутствует в каталоге | +| Raw-ingest | Январь: 2 964 624 строки; январь–март: 9 554 778 строк, 19 колонок | +| Профилирование | Схема, null-доли, describe и четыре проверки аномалий выполнены без ошибок | +| Самостоятельное задание raw | Lookup: 265 строк; подсчёт зон по Borough и top-5 pickup с названиями зон выполнены; найдено 180 поездок с отрицательной длительностью | +| Повторная загрузка raw в отдельном ядре | Все четыре файла пропущены с `skipped_same_size`; снимки всех объектов и каталога до/после совпали | + +Код исходного raw-ingest после ячейки подготовки не изменён, что проверено +сравнением ячеек с базовым коммитом. Из подготовки убрано только создание сессии: +она теперь приходит из новой практики. + +## Время и ограничения + +- Машинный прогон блока настройки: **179,27 с**. Сюда вошли дополнительные + повторы шаблона и таблицы, а также настоящий перезапуск ядра. +- Исходная часть модуля, включая заполненные самостоятельные упражнения: + **70,41 с**. Полный основной прогон: **250,02 с** (около 4 минут 10 секунд). +- Запуск контейнеров и скачивание bundle в замер не входят. Это время выполнения + кода; чтение объяснений, самостоятельное заполнение и ответы студента не измерялись. +- Ориентир новой практики **20–30 минут**, модуля целиком **около 2 часов**. + Общую оценку **12–15 часов** оставили предварительной; машинного замера + недостаточно для её уточнения. Нужен самостоятельный проход студента. +- Кнопки Jupyter/VS Code, отображение раскрывающегося решения и UI сервисов + не проверялись. Перезапуск выполнен менеджером ядра через API, а не кнопкой. +- Остальные семь ноутбуков и Trino smoke не выполнялись: runtime-конфигурация + не менялась, проверялся модуль 3. + +## Сохранность данных + +До основного прогона в каталоге было **0 таблиц**, в bucket — **4 объекта**. +После прогона исходные объекты сохранили ETag и размер, состав каталога +не изменился. Это проверка на имевшемся состоянии стенда, а не на копии +заполненного студентом курса. + +Добавлены четыре исходных файла Taxi в `raw/nyc_taxi/`, как предусмотрено уроком; +они оставлены для модуля 4. Локальный bundle сохранён в игнорируемом `data/`. +Файлы данных и метаданных трёх временных таблиц удалены через PURGE. +Hadoop S3A оставил шесть нулевых маркеров `data/` и `metadata/`; +при завершении проверки удалены только эти шесть зафиксированных объектов. +В трёх префиксах практики осталось 0 объектов. Volumes не сбрасывались. +Поднятый для проверки стенд остановлен через `docker compose down` без `-v`. + +## Статические проверки + +- `git diff --check`; +- `docker compose config --quiet`; +- проверка ноутбука через `nbformat.validate` и синтаксиса Python-ячеек через AST; +- относительные ссылки изменённых документов и ноутбука; +- сохранение восьми модулей и маршрута README → START_HERE → программа → ноутбук. diff --git a/plans/module-03-raw-ingest-and-first-read.md b/plans/module-03-raw-ingest-and-first-read.md index fbc2a95..64d21bb 100644 --- a/plans/module-03-raw-ingest-and-first-read.md +++ b/plans/module-03-raw-ingest-and-first-read.md @@ -1,7 +1,11 @@ # Модуль 3. Raw-данные и первое чтение в Spark -**Статус:** `Ready for validation` -**Последнее обновление:** `2026-03-07` +**Статус:** `Ready for review` — код проверен на стенде, время самостоятельного прохождения студентом пока не измерено +**Последнее обновление:** `2026-09-15` + +Дополнение: [#2 — практика настройки SparkSession](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/2), после закрытой [#1](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/1). Новая практика входит в модуль 3; структура курса остаётся из восьми модулей. + +Результаты прогона и ограничения: [проверка #2](issue-2-spark-session-validation.md). ## Цель @@ -11,6 +15,9 @@ После прохождения модуля студент: +- создаёт Spark-сессию для кластера, различает настройки из кода, параметров запуска и общего файла; +- проверяет фактический master, имя приложения, настройки каталога и чтение собственной временной Iceberg-таблицы; +- объясняет повторное использование контекста, остановку сессии и перезапуск ядра; меняет часовой пояс с восстановлением исходного значения; - понимает, как локальный data bundle попадает в raw-зону MinIO; - умеет загружать PARQUET-файлы в MinIO программно через `boto3`; - умеет читать raw-данные из MinIO через Spark (`spark.read.parquet` по `s3a://` пути); @@ -84,6 +91,20 @@ volumes: ### Секция 0: Введение - **[md]** Заголовок, цели модуля, prerequisite (data bundle из `START_HERE.md`). Таблица-сравнение: «Классический DWH: данные уже внутри СУБД» vs «Lakehouse: данные нужно явно доставить в storage». +### Секция 0.1: Как настроен Spark в нашем стенде + +- **Объяснение:** SparkSession, SparkContext, driver в Jupyter, executors на worker-ах; master, appName, getOrCreate; local и кластер. Источники настроек и подготовленный доступ к Iceberg/MinIO. +- **Демонстрация:** сессия с master из общего файла, вычисление суммы 0…9, вывод выбранных несекретных настроек. Изменение `spark.sql.session.timeZone` и восстановление в `finally`. +- **Новый запуск:** повторный builder с другим appName сохраняет фактическое имя контекста; после `stop()` новый контекст получает новое имя. +- **Самостоятельное повторение:** заполнить адрес кластера, имя приложения и builder; контрольное решение в раскрывающемся блоке. Повторить ячейку и проверить неизменный applicationId. +- **Проверка каталога:** создать собственную Iceberg-таблицу с уникальным именем, прочитать `[0, 1]`, удалить только её через `DROP TABLE … PURGE` в `finally`. Учебные таблицы других модулей не используются. +- **Checkpoint:** проверить master и appName, объяснить источники настроек и место вычислений. После удаления временной таблицы перезапустить ядро, повторить заполненный шаблон и проверку Iceberg, затем продолжить raw-ingest. +- **Длительность:** ориентир 20–30 минут; на модуль целиком около 2 часов. Замер машинного выполнения и ограничения проверки фиксируются отдельно от оценки времени студента. + +### Секция 0.2: Подготовка к raw-ingest + +- Импорты, MinIO-клиент, пути и вспомогательные функции исходного урока. Сессия продолжает работать после checkpoint настройки. + ### Секция 1: Проверка data bundle - **[md]** Зачем проверяем; почему не скачиваем из интернета в ноутбуке (воспроизводимость, сетевые ограничения, разделение ответственности onboarding vs практика). - **[code]** `os.listdir("/opt/data/nyc_taxi")`, вывод файлов с размерами, assert на наличие PARQUET-файлов и `taxi_zone_lookup.csv` — оба нужны для полного прохождения модуля (включая самостоятельное задание в Секции 6). Понятное сообщение с отсылкой к `START_HERE.md` при отсутствии любого из компонентов. @@ -96,7 +117,7 @@ volumes: ### Секция 3: Первое чтение в Spark - **[md]** Разница `spark.read.parquet("s3a://...")` (raw-файлы) vs `spark.table(...)` (управляемая Iceberg-таблица). Мы пока на этапе raw, Iceberg-таблица появится в Модуле 4. -- **[code]** Создание SparkSession (паттерн из Module 2 — адрес кластера из `spark-defaults.conf`, `setLogLevel("ERROR")`). +- **[code]** Чтение через сессию, созданную в секции 0.1; повторная инициализация не нужна. - **[code]** Чтение одного файла: `spark.read.parquet("s3a://lakehouse/raw/nyc_taxi/yellow_tripdata_2024-01.parquet")`. - **[code]** Чтение всех файлов wildcard: `yellow_tripdata_*.parquet` (без привязки к конкретному году в wildcard, чтобы код работал с любыми скачанными файлами). @@ -130,12 +151,15 @@ volumes: ### Дизайн-решения по ноутбуку - **Helper-код:** весь код inline в ноутбуке. Отдельный модуль в `src/` не создаётся — студент должен видеть каждый шаг явно (`boto3.upload_file()`, `spark.read.parquet()`, `.printSchema()`). -- **Cleanup:** ноутбук НЕ удаляет raw-данные из MinIO — они нужны Модулю 4 (bronze). Spark-сессия останавливается. Явное пояснение в конце ноутбука. +- **Cleanup:** практика настройки удаляет только свою временную таблицу. Ноутбук НЕ удаляет raw-данные из MinIO — они нужны Модулю 4 (bronze). Spark-сессия останавливается в конце. ## Checkpoint Студент должен уметь: +- создать сессию по заполненному шаблону, подтвердить master `spark://spark-master:7077` и заданное appName; +- прочитать `[0, 1]` из собственной Iceberg-таблицы и подтвердить её удаление; +- объяснить, какие настройки предоставил стенд, где выполняются задания и что повторить после перезапуска ядра; - показать файлы в raw-зоне MinIO (через MinIO Console или через код); - прочитать raw PARQUET через Spark и вывести несколько строк; - назвать схему Yellow Taxi (количество колонок, основные типы); @@ -148,10 +172,11 @@ volumes: - `docker-compose.yml` содержит volume mount `./data:/opt/data:ro` для контейнера `jupyter`, и `docker compose config` проходит без ошибок. - `START_HERE.md` содержит воспроизводимую инструкцию по скачиванию NYC Taxi PARQUET (минимум 3 файла + taxi zone lookup) до запуска Модуля 3. - `.gitignore` содержит `/data/` для исключения датасета из git. -- `notebooks/03_raw_ingest_and_first_read.ipynb` можно выполнить сверху вниз в поднятом Jupyter-окружении при наличии скачанного data bundle. +- `notebooks/03_raw_ingest_and_first_read.ipynb` можно пройти по порядку в поднятом Jupyter-окружении при наличии data bundle, заполнив шаблон и выполнив указанный перезапуск ядра. - Ноутбук следует методике курса: `объяснение -> демонстрация -> самостоятельное повторение -> checkpoint`. -- Ноутбук использует паттерны из Модулей 1-2: `boto3` для MinIO, SparkSession с адресом кластера из `spark-defaults.conf`, `setLogLevel("ERROR")`. -- Raw-данные остаются в MinIO после выполнения ноутбука (cleanup отсутствует намеренно). +- Демонстрация берёт master из `spark-defaults.conf`; самостоятельное задание явно задаёт тот же адрес, сохраняя подготовленную конфигурацию каталога. Шаблон и контрольное решение проверяются в новых ядрах на Spark 3.5.1. +- Проверены повторные ячейки, перезапуск ядра, изменение и восстановление часового пояса, новое имя приложения после остановки контекста. +- Raw-данные остаются в MinIO после выполнения ноутбука; удаляется только временная таблица настройки. - При отсутствии data bundle — понятный assert с отсылкой к `START_HERE.md`. - `docs/stack_reference.md` обновлён: секция JupyterLab содержит `./data` mount. - `plans/README.md` содержит строку Модуля 3 в оглавлении. @@ -166,7 +191,8 @@ volumes: ## Out of Scope -- Создание Iceberg-таблиц — отложено до Модуля 4. +- Создание рабочих Iceberg-таблиц из raw — в Модуле 4. В Модуле 3 есть только маленькая временная таблица для проверки подключения. +- Подбор памяти, числа executors, shuffle, GC и эксперимент с числом партиций. - Трансформации и очистка данных — отложено до Модулей 4-5. - Чтение raw-данных через Trino (Trino не умеет читать произвольные файлы без таблицы) — отложено до Модуля 6. - Партиционирование, MERGE, streaming, gold-слой.