Timeline Architecture и Storage Layout

Apache Hudi (Hadoop Upserts Deletes Incrementals) — это открытый формат транзакционного lakehouse-хранилища, изначально созданный в Uber для инкрементальной обработки петабайтных датасетов. В отличие от Delta Lake (единый _delta_log/) и Apache Iceberg (каталог + дерево metadata файлов), Hudi использует timeline-based архитектуру: каждая операция над таблицей записывается как instant на временной шкале, а данные организованы в FileGroup/FileSlice иерархию.

В Модуле 11 и Модуле 12 мы разобрали подходы Delta Lake и Iceberg. Hudi — третий major формат, и его архитектура ближе к LSM-дереву, чем к append-only логу.

Структура .hoodie/

Каждая Hudi-таблица содержит директорию .hoodie/ в корне — аналог _delta_log/ в Delta Lake. Это метаданные, описывающие весь жизненный цикл таблицы:

hoodie.properties — конфигурация таблицы

Файл hoodie.properties — неизменяемый после создания для ключевых полей. Он определяет фундаментальные характеристики таблицы:

# Тип таблицы — COPY_ON_WRITE или MERGE_ON_READ
hoodie.table.type=MERGE_ON_READ
# Версия формата таблицы (8 в Hudi 1.0+)
hoodie.table.version=8
# Имя таблицы
hoodie.table.name=orders
# Поле первичного ключа
hoodie.table.recordkey.fields=order_id
# Поле для разрешения конфликтов (precombine)
hoodie.table.precombine.field=updated_at
# Тип payload (слияние записей)
hoodie.compaction.payload.class=org.apache.hudi.common.model.OverwriteWithLatestAvroPayload
# Partitioning
hoodie.table.partition.fields=dt
# Checksum для валидации
hoodie.table.checksum=3847592

Что не хранится в .hoodie/

В отличие от Delta Lake, где _delta_log/ содержит полную схему данных, Hudi хранит текущую схему внутри каждого commit instant (в Avro-формате), а не в отдельном schema registry. Partition metadata лежит внутри каждой партиции в файлах .hoodie_partition_metadata.

Timeline: временная шкала операций

Timeline — центральная абстракция Hudi. Каждое действие над таблицей создаёт instant — запись на временной шкале с тремя атрибутами:

Каждый instant представлен файлами в .hoodie/. Имя файла кодирует все три атрибута:

20240115120000000.commit ← completed commit
20240115120000000.commit.inflight ← inflight commit
20240115120000000.commit.requested ← requested commit
20240115130000000.deltacommit ← completed deltacommit (MOR)
20240115140000000.compaction.requested ← scheduled compaction
20240115140000000.compaction.inflight ← running compaction
20240115140000000.compaction ← completed compaction

Жизненный цикл instant

Типы action

Timeline Server

Timeline Server — это in-process кэширующий прокси, который хранит timeline и file listing в памяти Java-процесса. Без Timeline Server каждый task в Spark/Flink-задаче вызывал бы LIST на object storage для каждого обращения к timeline.

Конфигурация Timeline Server:

# Включён по умолчанию для Spark
hoodie.embed.timeline.server=true
# Порт (по умолчанию 26754)
hoodie.embed.timeline.server.port=26754
# Размер кэша file listing
hoodie.filesystem.view.remote.timeout.secs=300

Архивированный Timeline

Активный timeline (файлы .hoodie/*.commit, *.deltacommit и т.д.) растёт с каждой операцией. Hudi автоматически архивирует старые instants:

# Минимальное количество instants на активном timeline
hoodie.keep.min.commits=20
# Максимальное — после этого архивация запускается
hoodie.keep.max.commits=30

LSM-стиль архива (Hudi 1.0)

До Hudi 1.0 архив хранил каждый instant как отдельный файл в .hoodie/.archived/ — при миллионах коммитов это порождало миллионы мелких файлов на object storage. В Hudi 1.0 архивированный timeline использует LSM-формат: instants группируются в compacted Avro-файлы, аналогично тому как LSM-дерево сливает уровни.

FileGroup и FileSlice: модель хранения данных

Данные в Hudi организованы в двухуровневую иерархию — FileGroup и FileSlice:

FileGroup

FileGroup — это логическая группа файлов с фиксированным идентификатором (UUID). Ключевые свойства:

• Каждая запись (record) навсегда принадлежит одному FileGroup — определяется при первой вставке через индекс
• FileGroup содержит цепочку FileSlice — по одному на каждый instant, затронувший эту группу
• File Group ID — UUID, записанный в имени файла: fg-001_0_20240115120000000.parquet

FileSlice

FileSlice — это снимок FileGroup на конкретный instant. Состав зависит от типа таблицы:

Анатомия имени файла

Каждый файл данных в Hudi содержит метаинформацию прямо в имени:

{file_group_id}_{write_token}_{instant_time}.parquet ← base файл
.{file_group_id}_{instant_time}.log.{version} ← log файл (точка в начале!)

Анатомия Base File

Base file — это стандартный Parquet-файл с дополнительными Hudi-метаданными в каждой строке:

Мета-колонки _hoodie_* — это цена Hudi: ~50-100 байт overhead на каждую запись. Для широких таблиц (сотни колонок) overhead незначителен, но для узких (2-3 колонки) может увеличить размер на 10-20%.

Анатомия Log File

Log-файлы — специфика MOR-таблиц. Каждый log-файл содержит последовательность блоков:

Каждый блок начинается с magic bytes (#HUDI#) для валидации целостности. Если блок повреждён (неполная запись из-за crash), reader обнаружит это по несовпадению magic и пропустит блок.

Log Block Header:
├── instant_time: "20240115130000000"
├── schema: "{"type":"record","name":"orders",...}"
├── record_count: 1500
├── content_length: 245760
├── block_type: DATA_BLOCK | DELETE_BLOCK | ROLLBACK_BLOCK
└── log_version: 1

Полная картина: от записи до чтения

Соединим все части в единую схему read path для snapshot-запроса:

Сравнение с Delta Lake и Iceberg

Итоги

• .hoodie/ — центральная директория метаданных, аналог _delta_log/
• Timeline — упорядоченная последовательность typed instants (commit, deltacommit, compaction, clean, rollback, savepoint)
• Каждый instant проходит lifecycle: requested → inflight → completed
• hoodie.properties задаёт необратимые решения: тип таблицы, record key, partition fields
• Timeline Server — in-memory кэш на driver, убирающий LIST-запросы к object storage
• Архивированный timeline (LSM в Hudi 1.0) — бесконечный time-travel без мелких файлов
• FileGroup — логическая единица данных с постоянным UUID; запись навсегда привязана к одному FileGroup
• FileSlice — snapshot FileGroup на instant: base file (Parquet) + опциональные log files (MOR)
• Base file = Parquet + 5 мета-колонок _hoodie_* + Bloom filter в footer
• Log file = последовательность блоков (Data, Delete, Rollback) с magic bytes для валидации

В следующем уроке мы разберём два типа таблиц — COW и MOR — в деталях: write path, read path, и когда выбирать каждый.