fix(course): исправлена семантика Iceberg snapshots

- Зачем: объяснения CREATE OR REPLACE и rollback расходились с поведением Iceberg 1.10.0 и ломали повторный запуск упражнений.
- Что: исправлены материалы и планы модулей 2, 4, 5, 7 и 8; одноразовые таблицы сбрасываются через DROP TABLE PURGE.
- Проверка: JSON и Python AST валидны; на Spark 3.5.1, Iceberg 1.10.0, JDBC/MinIO и Trino 478 подтверждены rollback, replace, time travel и повторный сброс до одного snapshot-а.

notebooks/02_lakehouse_mental_model.ipynb

@@ -264,9 +264,9 @@
       "metadata": {},
       "outputs": [],
       "source": [
-        "# Удаляем таблицы (это удалит их и из каталога, и из хранилища)\n",
-        "spark.sql(\"DROP TABLE IF EXISTS lakehouse.module_02.demo_table\")\n",
-        "spark.sql(\"DROP TABLE IF EXISTS lakehouse.module_02.my_first_table\")\n",
+        "# PURGE удаляет одноразовые таблицы и из каталога, и из хранилища\n",
+        "spark.sql(\"DROP TABLE IF EXISTS lakehouse.module_02.demo_table PURGE\")\n",
+        "spark.sql(\"DROP TABLE IF EXISTS lakehouse.module_02.my_first_table PURGE\")\n",
         "\n",
         "# Удаляем namespace\n",
         "spark.sql(\"DROP NAMESPACE IF EXISTS lakehouse.module_02\")\n",
@@ -297,4 +297,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 5
-}
+}

notebooks/04_bronze_with_iceberg.ipynb

@@ -216,7 +216,7 @@
    "cell_type": "markdown",
    "id": "350d2087",
    "metadata": {},
-   "source": "## 3. Создание `bronze` namespace и `Iceberg`-таблицы\n\nСначала создаём namespace `lakehouse.bronze`, а затем выполняем `CTAS` (`CREATE OR REPLACE TABLE ... USING iceberg AS SELECT ...`).\n\nЧто такое namespace в `Iceberg`:\n\n- это логический контейнер для таблиц;\n- если ты работал с `PostgreSQL` — это ближайший аналог `schema` внутри базы;\n- запись `lakehouse.bronze.nyc_taxi_yellow` читается как `catalog.namespace.table`.\n\nПочему здесь используем именно `bronze`, а не `module_04`:\n\n- имя сразу отражает роль слоя в пайплайне `raw -> bronze -> silver`;\n- Модуль 5 будет читать именно `lakehouse.bronze.*`, и семантическое имя делает маршрут прозрачным;\n- в отличие от демонстрационного `module_02`, этот слой не временный и будет использоваться в следующих модулях.\n\nЭто удобный учебный компромисс:\n\n- один шаг создаёт таблицу и сразу наполняет её;\n- повторный запуск секции остаётся идемпотентным;\n- минус: `CREATE OR REPLACE` пересоздаёт таблицу и сбрасывает старую историю snapshot-ов.\n\nДля первого `bronze`-слоя это допустимо. В Модуле 7 мы отдельно разберём, почему в рабочих сценариях нужно аккуратнее относиться к истории таблицы."
+   "source": "## 3. Создание `bronze` namespace и `Iceberg`-таблицы\n\nСначала создаём namespace `lakehouse.bronze`, а затем выполняем `CTAS` (`CREATE OR REPLACE TABLE ... USING iceberg AS SELECT ...`).\n\nЧто такое namespace в `Iceberg`:\n\n- это логический контейнер для таблиц;\n- если ты работал с `PostgreSQL` — это ближайший аналог `schema` внутри базы;\n- запись `lakehouse.bronze.nyc_taxi_yellow` читается как `catalog.namespace.table`.\n\nПочему здесь используем именно `bronze`, а не `module_04`:\n\n- имя сразу отражает роль слоя в пайплайне `raw -> bronze -> silver`;\n- Модуль 5 будет читать именно `lakehouse.bronze.*`, и семантическое имя делает маршрут прозрачным;\n- в отличие от демонстрационного `module_02`, этот слой не временный и будет использоваться в следующих модулях.\n\nЭто удобный учебный компромисс:\n\n- один шаг создаёт таблицу и сразу наполняет её;\n- повторный запуск приводит текущее содержимое к тому же результату и не дублирует строки;\n- при каждом запуске `CREATE OR REPLACE` создаёт новый snapshot, а старые snapshot-ы сохраняются для time travel.\n\nВажно: замена может изменить текущие данные, схему и партиционирование таблицы. Новый snapshot не продолжает прежнюю цепочку: у него нет `parent_id`, а старые snapshot-ы больше не являются предками текущего состояния (`is_current_ancestor = false`). Это не отдельная именованная ветка — текущей по-прежнему остаётся `main`. Подробнее эту разницу разберём в Модуле 7."
   },
   {
    "cell_type": "code",
@@ -650,4 +650,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

notebooks/05_silver_layer.ipynb

@@ -280,7 +280,7 @@
     "\n",
     "Используем `CREATE OR REPLACE TABLE ... AS SELECT` (CTAS) в namespace `lakehouse.silver`.\n",
     "\n",
-    "**Важное предупреждение:** `CREATE OR REPLACE` — это полная перезапись таблицы. Все предыдущие данные и история snapshot-ов будут потеряны. В учебном silver это осознанный компромисс ради идемпотентности: повторный запуск ноутбука пересоздаёт таблицу с чистого листа. В Модуле 7 мы увидим, как делать изменения безопаснее.\n",
+    "**Важное предупреждение:** `CREATE OR REPLACE` атомарно заменяет текущее содержимое таблицы и может заменить её схему и партиционирование. При этом Iceberg сохраняет предыдущие snapshot-ы для time travel, но новый snapshot не продолжает их цепочку: старые состояния перестают быть предками текущего. В учебном silver это осознанный компромисс ради воспроизводимого результата без дублирования строк. В Модуле 7 мы разберём эту семантику подробнее.\n",
     "\n",
     "На 3 месяцах данных (~7 млн строк) эта операция может занять 2-4 минуты."
    ]
@@ -610,4 +610,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

notebooks/07_safe_table_changes.ipynb

@@ -153,7 +153,7 @@
     "- `operation` — тип операции (append, overwrite).\n",
     "- `summary` — краткая статистика (added-data-files, total-records и т.д.).\n",
     "\n",
-    "Если вы не перезапускали Модуль 5 через CREATE OR REPLACE, у silver будет 1 snapshot (от CTAS).\n",
+    "После первого запуска Модуля 5 у silver будет 1 snapshot от CTAS. Каждый повторный `CREATE OR REPLACE` добавит ещё один snapshot: прежние состояния сохранятся, хотя перестанут быть предками текущего.\n",
     "В Greenplum такой истории нет: после `INSERT` предыдущее состояние таблицы недоступно без бэкапа.\n"
    ]
   },
@@ -211,7 +211,7 @@
     "Колонка добавлена. Данные не изменились — Iceberg не перезаписывал data files. \n",
     "В рабочем сценарии `loaded_at` заполнялся бы при следующих INSERT-ах: `INSERT INTO ... SELECT ..., current_timestamp() AS loaded_at FROM ...`. Существующие строки остаются с NULL — это нормальная практика эволюции схемы. Заполнение существующих строк (UPDATE) — отдельная тема, требующая перезаписи файлов.\n",
     "\n",
-    "Примечание: если вы повторно запустите Модуль 5 после Модуля 7, `CREATE OR REPLACE TABLE` пересоздаст silver без колонки `loaded_at`. Это ещё одна иллюстрация того, почему `CREATE OR REPLACE` опасен в рабочих сценариях — он стирает все изменения, включая schema evolution.\n"
+    "Примечание: если вы повторно запустите Модуль 5 после Модуля 7, `CREATE OR REPLACE TABLE` заменит текущую схему silver, поэтому колонка `loaded_at` исчезнет из текущего состояния. Предыдущие snapshot-ы при этом сохранятся для time travel, но перестанут быть предками текущего snapshot-а.\n"
    ]
   },
   {
@@ -288,9 +288,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Демо-таблица одноразовая: удаляем её вместе с историей,\n",
+    "# чтобы при повторном запуске снова получить ровно один snapshot.\n",
+    "spark.sql(f\"DROP TABLE IF EXISTS {DEMO_TABLE} PURGE\")\n",
+    "\n",
     "# Создание демо-таблицы\n",
     "spark.sql(f\"\"\"\n",
-    "    CREATE OR REPLACE TABLE {DEMO_TABLE}\n",
+    "    CREATE TABLE {DEMO_TABLE}\n",
     "    USING iceberg AS\n",
     "    SELECT VendorID, tpep_pickup_datetime, tpep_dropoff_datetime,\n",
     "           passenger_count, trip_distance, fare_amount, total_amount,\n",
@@ -504,7 +508,7 @@
    "outputs": [],
    "source": [
     "# Посмотрим на 3-й snapshot (нашу ошибку)\n",
-    "spark.sql(f\"SELECT snapshot_id, operation FROM {DEMO_TABLE}.snapshots\").show(truncate=False)\n"
+    "spark.sql(f\"SELECT snapshot_id, parent_id, operation FROM {DEMO_TABLE}.snapshots\").show(truncate=False)\n"
    ]
   },
   {
@@ -563,23 +567,32 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "spark.sql(f\"SELECT snapshot_id, operation FROM {DEMO_TABLE}.snapshots\").show(truncate=False)\n"
+    "print(\"Сохранённые snapshot-ы:\")\n",
+    "spark.sql(f\"SELECT snapshot_id, parent_id, operation FROM {DEMO_TABLE}.snapshots\").show(truncate=False)\n",
+    "\n",
+    "print(\"История переключений текущего состояния:\")\n",
+    "spark.sql(\n",
+    "    f\"SELECT made_current_at, snapshot_id, parent_id, is_current_ancestor \"\n",
+    "    f\"FROM {DEMO_TABLE}.history ORDER BY made_current_at\"\n",
+    ").show(truncate=False)\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Теперь в истории 4 записи. Четвёртый snapshot — это результат rollback, но его данные (набор файлов) в точности соответствуют snapshot 2.\n",
+    "В `.snapshots` по-прежнему три записи: rollback **не создал четвёртый snapshot**. Он переключил текущее состояние таблицы на уже существующий `snapshot_2`.\n",
     "\n",
-    "Rollback **не удаляет историю** и **не удаляет файлы**. Он создаёт новый snapshot, указывающий на данные предыдущего состояния. Аналогия:\n",
+    "В `.history` появилась ещё одна запись о переключении текущего состояния. Она снова указывает на `snapshot_2`; snapshot с «плохими» строками сохранился, но больше не является предком текущего состояния (`is_current_ancestor = false`).\n",
     "\n",
-    "| | git | Iceberg |\n",
+    "| Свойство | `rollback_to_snapshot` | `CREATE OR REPLACE TABLE ... AS SELECT` |\n",
     "|---|---|---|\n",
-    "| Откат с сохранением истории | `git revert` (новый коммит) | `rollback_to_snapshot` (новый snapshot) |\n",
-    "| Откат с удалением истории | `git reset --hard` | `CREATE OR REPLACE` (уничтожает snapshot-ы) |\n",
+    "| Создаёт новый snapshot | Нет | Да |\n",
+    "| Что становится текущим | Существующий snapshot-предок | Новый snapshot с результатом `SELECT` |\n",
+    "| Что происходит со старыми snapshot-ами | Сохраняются | Сохраняются для time travel |\n",
+    "| Цепочка предков | Возвращаемся к предку | Новый snapshot не имеет `parent_id`; прежние snapshot-ы перестают быть предками текущего |\n",
     "\n",
-    "Старые data files (включая файлы с «плохими» строками) остаются в хранилище (MinIO) до процедуры `expire_snapshots` — это тема Модуля 8. Rollback не чистит storage, он только меняет указатель текущего snapshot-а.\n"
+    "При `CREATE OR REPLACE` отдельная именованная ветка автоматически не создаётся: текущей остаётся ветка `main`. Старые data files сохраняются до `expire_snapshots` — эту процедуру разберём в Модуле 8.\n"
    ]
   },
   {
@@ -649,7 +662,7 @@
     "### Секция 10: Типичные ошибки новичка\n",
     "\n",
     "**Ошибка 1: Слепой `CREATE OR REPLACE`.**\n",
-    "В Модулях 4 и 5 мы использовали `CREATE OR REPLACE TABLE ... AS SELECT` (CTAS) для создания bronze и silver. Это был осознанный компромисс: первичная загрузка, нет предыдущей истории, которую нужно сохранять. Но в рабочих сценариях `CREATE OR REPLACE` — **деструктивная операция**: она уничтожает ВСЮ snapshot-историю таблицы. Если у таблицы было 100 snapshot-ов, после `CREATE OR REPLACE` останется один. Time travel к предыдущим состояниям станет невозможен.\n",
+    "В Модулях 4 и 5 мы использовали `CREATE OR REPLACE TABLE ... AS SELECT` для воспроизводимой полной загрузки bronze и silver. В `SparkCatalog` эта операция атомарно создаёт новый snapshot и сохраняет прежние snapshot-ы для time travel. Но она заменяет текущее содержимое, схему и партиционирование таблицы. Новый snapshot не имеет `parent_id`, поэтому прежние snapshot-ы перестают быть предками текущего состояния. Слепая замена может неожиданно убрать колонку, изменить раскладку данных или усложнить обычный rollback к прежней цепочке. Если нужно перезаписать данные, сохранив текущую схему и партиционирование, используй `INSERT OVERWRITE`.\n",
     "\n",
     "**Ошибка 2: Изменение схемы без проверки downstream.**\n",
     "Мы только что видели, как `RENAME COLUMN` ломает запросы со старым именем. `ALTER COLUMN TYPE` (расширение INT -> BIGINT) безопасен для данных, но downstream-системы могут интерпретировать новый тип по-другому и сломаться на своей стороне. Перед любым изменением схемы нужно понимать, кто читает эту таблицу.\n",
@@ -664,7 +677,7 @@
    "source": [
     "### Секция 11: Самостоятельное задание\n",
     "\n",
-    "Пересоздадим демо-таблицу с чистого листа. После демонстраций выше её схема изменена, а история содержит учебные эксперименты. Для самостоятельной работы нужна чистая таблица.\n"
+    "Подготовим демо-таблицу с чистого листа. После демонстраций выше её схема изменена, а история содержит учебные эксперименты. Поскольку `CREATE OR REPLACE` сохраняет старые snapshot-ы, для одноразовой учебной таблицы явно используем `DROP TABLE ... PURGE`, а затем новый `CREATE TABLE`. Так самостоятельная работа снова начнётся ровно с одного snapshot-а.\n"
    ]
   },
   {
@@ -673,9 +686,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Пересоздаем демо-таблицу (это удалит всю ее snapshot-историю - Ошибка 1 в действии!)\n",
+    "# Эта таблица одноразовая: PURGE удаляет её данные и snapshot-историю.\n",
+    "spark.sql(f\"DROP TABLE IF EXISTS {DEMO_TABLE} PURGE\")\n",
+    "\n",
+    "# Создаём новую таблицу с одним начальным snapshot-ом.\n",
     "spark.sql(f\"\"\"\n",
-    "    CREATE OR REPLACE TABLE {DEMO_TABLE}\n",
+    "    CREATE TABLE {DEMO_TABLE}\n",
     "    USING iceberg AS\n",
     "    SELECT VendorID, tpep_pickup_datetime, tpep_dropoff_datetime,\n",
     "           passenger_count, trip_distance, fare_amount, total_amount,\n",
@@ -683,7 +699,9 @@
     "    FROM {SILVER_TABLE}\n",
     "    LIMIT 1000\n",
     "\"\"\")\n",
-    "print(f\"Демо-таблица пересоздана начисто: {spark.table(DEMO_TABLE).count()} строк, 1 snapshot.\")\n"
+    "practice_snapshot_count = spark.sql(f\"SELECT * FROM {DEMO_TABLE}.snapshots\").count()\n",
+    "assert practice_snapshot_count == 1, f\"Ожидался 1 snapshot, получено {practice_snapshot_count}\"\n",
+    "print(f\"Демо-таблица создана начисто: {spark.table(DEMO_TABLE).count()} строк, 1 snapshot.\")\n"
    ]
   },
   {
@@ -804,7 +822,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "**Задача 5 (ответ).** Ответь текстом в ячейке ниже: чем `rollback_to_snapshot` отличается от `CREATE OR REPLACE TABLE ... AS SELECT * FROM table VERSION AS OF <snapshot_id>`? Что происходит с историей snapshot-ов в каждом случае?\n"
+    "**Задача 5 (ответ).** Сравни `rollback_to_snapshot` и `CREATE OR REPLACE TABLE ... AS SELECT * FROM table VERSION AS OF <snapshot_id>`. Какая операция создаёт новый snapshot? Что происходит с текущим состоянием, старыми snapshot-ами и цепочкой `parent_id`?\n"
    ]
   },
   {
@@ -843,7 +861,7 @@
     "3. Чем `ADD COLUMN` отличается от `RENAME COLUMN` по влиянию на downstream?\n",
     "4. Как прочитать предыдущее состояние таблицы? (назови два способа)\n",
     "5. Что делает `rollback_to_snapshot`? Теряется ли при этом snapshot-история?\n",
-    "6. Почему `CREATE OR REPLACE` опаснее, чем `INSERT INTO` с последующим rollback?\n",
+    "6. Какие риски остаются у `CREATE OR REPLACE`, хотя старые snapshot-ы сохраняются?\n",
     "7. Какой аналог time travel в классических СУБД (PostgreSQL/Greenplum) и почему он сложнее в использовании?\n"
    ]
   },
@@ -862,8 +880,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "spark.sql(f\"DROP TABLE IF EXISTS {DEMO_TABLE}\")\n",
-    "print(\"Демо-таблица удалена.\")\n"
+    "spark.sql(f\"DROP TABLE IF EXISTS {DEMO_TABLE} PURGE\")\n",
+    "print(\"Демо-таблица и её учебные данные удалены.\")\n"
    ]
   },
   {
@@ -874,7 +892,7 @@
     "- Schema evolution (`ADD COLUMN`) — безопасная metadata-only операция, которая мгновенно видна из всех движков через общий каталог.\n",
     "- Snapshot-ы — автоматическая история изменений данных, встроенная в Iceberg.\n",
     "- Time travel — чтение предыдущих состояний без бэкапов.\n",
-    "- Rollback — восстановление после ошибки с сохранением истории.\n",
+    "- Rollback — переключение текущего состояния на существующий snapshot-предок без создания нового snapshot-а.\n",
     "\n",
     "В финальном Модуле 8 мы изучим базовое обслуживание таблиц: compaction (решение проблемы множества мелких файлов) и `expire_snapshots` (очистка старых файлов данных, оставшихся после time travel и rollback, которые мы научились применять в этом модуле).\n"
    ]
@@ -901,4 +919,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

notebooks/08_maintenance_and_final_lab.ipynb

@@ -135,7 +135,7 @@
     "\n",
     "Каждый `INSERT INTO` в Iceberg создаёт новые data files. Если вставлять данные мелкими порциями (частые микробатчи, ручные INSERT-ы, инкрементальные загрузки), таблица накапливает множество мелких файлов. Это замедляет чтение: движку приходится открывать и читать каждый файл отдельно. \n",
     "\n",
-    "Создадим демо-таблицу и сымитируем эту проблему: один изначальный `CTAS` (500 строк) и 8 маленьких `INSERT INTO` (по 100 строк).\n",
+    "Создадим демо-таблицу и сымитируем эту проблему: один изначальный `CTAS` (500 строк) и 8 маленьких `INSERT INTO` (по 100 строк). Перед созданием удалим одноразовую таблицу через `DROP TABLE ... PURGE`, чтобы при повторном запуске история снова начиналась с одного snapshot-а.\n",
     "*(Внимание: 8 INSERT-ов могут занять 1-2 минуты)*\n"
    ]
   },
@@ -145,9 +145,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Создание демо-таблицы (создаст 1 файл)\n",
+    "# Демо-таблица одноразовая: удаляем данные и старую snapshot-историю,\n",
+    "# чтобы повторный запуск дал те же 9 snapshot-ов.\n",
+    "spark.sql(f\"DROP TABLE IF EXISTS {DEMO_TABLE} PURGE\")\n",
+    "\n",
+    "# Создание демо-таблицы (создаст 1 файл и 1 snapshot)\n",
     "spark.sql(f\"\"\"\n",
-    "    CREATE OR REPLACE TABLE {DEMO_TABLE}\n",
+    "    CREATE TABLE {DEMO_TABLE}\n",
     "    USING iceberg AS\n",
     "    SELECT VendorID, tpep_pickup_datetime, tpep_dropoff_datetime,\n",
     "           passenger_count, trip_distance, fare_amount, total_amount,\n",
@@ -529,8 +533,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "spark.sql(f\"DROP TABLE IF EXISTS {DEMO_TABLE}\")\n",
-    "print(\"Демо-таблица удалена.\")\n",
+    "spark.sql(f\"DROP TABLE IF EXISTS {DEMO_TABLE} PURGE\")\n",
+    "print(\"Демо-таблица и её учебные данные удалены.\")\n",
     "\n"
    ]
   },
@@ -784,4 +788,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}