Таблицы метаданных

Apache Iceberg отслеживает богатые метаданные, чтобы эффективно управлять своими таблицами. Эти метаданные нужны не только для внутреннего учёта; они также доступны пользователям через особые таблицы метаданных, которые можно запрашивать как обычные таблицы. Таблицы метаданных дают прозрачность физической и логической раскладки таблицы Iceberg, показывая размеры файлов данных, партиции, снимки и многое другое.

Понимание того, как пользоваться этими таблицами, необходимо для мониторинга состояния таблиц, диагностики проблем производительности и автоматизации обслуживания вроде компактизации и истечения снимков. Это приложение даёт обзор таких таблиц, показывает, как запрашивать их из распространённых движков вроде Spark и Dremio, и объясняет, как интерпретировать результаты.

Мы пройдём по каждой из основных таблиц метаданных Iceberg и посмотрим, как их применять в практических сценариях обслуживания. Мы также разберём, как эти таблицы обеспечивают упреждающие процессы оптимизации, служа основой для динамических триггеров обслуживания.

A.1 Запросы к таблицам метаданных Iceberg

Iceberg раскрывает свои метаданные через богатый набор системных таблиц, позволяющих анализировать физические и логические аспекты наборов данных и управлять ими. Эти таблицы метаданных необходимы для понимания эволюции таблиц, раскладки данных и управления снимками. Их можно запрашивать из широкого круга движков и библиотек, включая Spark, Dremio, Trino, PyIceberg и другие. Сами метаданные единообразны, но точный синтаксис обращения к этим таблицам различается по движкам и клиентам, отражая различия диалектов SQL и соглашений API.

В Spark к таблицам метаданных обращаются, добавляя имя таблицы метаданных к имени исходной таблицы:

SELECT * FROM db.table.history;
SELECT * FROM db.table.snapshots;
SELECT * FROM db.table.entries;

В Dremio доступ к таблицам метаданных осуществляется синтаксисом TABLE(<iceberg_metadata>(<table_name>)):

SELECT * FROM TABLE(table_history('my_table'));
SELECT * FROM TABLE(table_snapshot('my_table'));
SELECT * FROM TABLE(table_files('my_table'));

Вот некоторые ключевые таблицы метаданных:

history - показывает временну́ю линию коммитов таблицы, включая метку времени каждого снимка, идентификатор, родителя и признак принадлежности к текущей истории
snapshots - перечисляет все действующие снимки вместе с типами операций (append, overwrite, delete) и списками манифестов
entries - показывает текущие записи манифестов для файлов данных и файлов удалений
files - отображает метаданные текущих файлов данных и удалений в последнем снимке
manifests - перечисляет файлы манифестов, используемые в текущем состоянии таблицы
partitions - даёт подробную статистику метрик на уровне партиций
refs - показывает именованные ссылки вроде веток и тегов, связанные со снимками

Эти таблицы обеспечивают разнообразные диагностические и эксплуатационные процессы:

Аудит изменений - используйте history и snapshots, чтобы отслеживать изменения и восстанавливать прежние состояния
Диагностика шаблонов хранения - запрашивайте files, entries или manifests, чтобы выявить перекос, чрезмерно мелкие файлы или крупные партиции
Путешествия во времени - сочетайте таблицы метаданных с запросами путешествия во времени, чтобы изучить состояние таблицы на прежнем снимке или в прежний момент
Триггеры обслуживания - автоматизируйте компактизацию или очистку по данным из partitions и manifests

A.2 Таблица метаданных history

Таблица метаданных history фиксирует родословную недавних коммитов в таблицу Iceberg, отражая связи «родитель - потомок» между снимками и породившие их операции. Эта таблица полезна для понимания того, как развивалась таблица, включая создание снимков и откаты. Однако она не представляет полную или постоянную историю. Таблица history ограничена и обычно хранит лишь определённое число записей - чаще всего последние 100, - то есть более старая информация о родословной может усекаться по мере новых коммитов. Для долгосрочного аудита или анализа удержания используйте её вместе с метаданными снимков и политиками удержания, а не как исчерпывающий журнал аудита.

Каждая строка таблицы history включает следующие поля:

made_current_at - метка времени, когда снимок стал текущим
snapshot_id - уникальный идентификатор снимка
parent_id - идентификатор снимка, от которого произошёл этот
is_current_ancestor - булев признак того, входит ли снимок в прямую историю текущего состояния таблицы

Такая структура позволяет отслеживать не только текущее состояние, но и любые ветки, откаты и заброшенные пути снимков.

Вот пример запроса в Spark:

SELECT * FROM db.table.history;

А это пример в Dremio:

SELECT * FROM TABLE(table_history('my_table'));

Сценарии использования:

Аудит эволюции таблицы - отслеживание того, когда именно вносились изменения и каким движком или задачей
Отладка откатов - определение, когда и почему произошёл откат, по снимкам, не являющимся предками текущего состояния
Управление снимками - в сочетании с таблицей snapshots позволяет увидеть, какие операции выполнялись в каждом снимке (append, overwrite, delete)

Например:

SELECT
   h.made_current_at,
   s.operation,
   h.snapshot_id,
   h.is_current_ancestor,
   s.summary['spark.app.id']
FROM db.table.history h
JOIN db.table.snapshots s ON h.snapshot_id = s.snapshot_id
ORDER BY h.made_current_at;

Эта таблица фундаментальна для путешествий во времени, стратегий истечения снимков и понимания того, как ваши данные меняются со временем.

A.3 Таблица метаданных snapshots

Таблица метаданных snapshots даёт подробную информацию о каждом снимке в таблице Apache Iceberg. Таблица history описывает родословную изменений, а snapshots раскрывает эксплуатационные и структурные детали каждого события изменения.

Каждая строка таблицы snapshots включает следующие поля:

committed_at - метка времени фиксации снимка
snapshot_id - уникальный идентификатор снимка
parent_id - идентификатор снимка, на котором основан этот
operation - тип операции (append, overwrite, delete и т. д.)
manifest_list - путь к файлу Avro со списком манифестов, использованных в этом снимке
summary - отображение метаданных: число добавленных или удалённых записей, задействованные файлы данных и специфичные для движка метаданные вроде идентификаторов приложений Spark

Вот пример запроса в Spark:

SELECT * FROM db.table.snapshots;

А это пример в Dremio:

SELECT * FROM TABLE(table_snapshot('my_table'));

Сценарии использования:

Понимание изменений таблицы - фильтруя снимки по типу операции, пользователи понимают характер изменений, применённых со временем:

SELECT snapshot_id, operation, committed_at
FROM db.table.snapshots
WHERE operation = 'delete';

Отладка записей - можно выявить неожиданное поведение, сопоставив время снимков с идентификаторами задач и приложений:

SELECT committed_at, operation, snapshot_id, summary['spark.app.id']
FROM db.table.snapshots
ORDER BY committed_at DESC;

Поддержка истечения снимков - эта таблица необходима для определения снимков-кандидатов на удаление, особенно при управлении объёмом хранения или соблюдении политик удержания.

Таблица метаданных snapshots - важнейшее окно в жизненный цикл состояния таблицы, и её часто соединяют с таблицей history, чтобы получить полную картину происхождения и родословной изменений.

A.4 Таблица метаданных metadata_log_entries

Таблица метаданных metadata_log_entries в Apache Iceberg раскрывает эволюцию файлов метаданных таблицы во времени. Каждая запись соответствует новому файлу метаданных, зафиксированному в таблице, давая криминалистический взгляд на то, как менялись структура и состояние таблицы.

Каждая строка включает следующие поля:

timestamp - когда файл метаданных был зафиксирован
file - URI к JSON-файлу метаданных
latest_snapshot_id - идентификатор снимка, связанного с файлом метаданных на момент фиксации
latest_schema_id - идентификатор схемы, действовавшей при фиксации файла
latest_sequence_number - монотонно возрастающее число, отражающее последнюю последовательность изменений

А это пример запроса в Spark:

SELECT * FROM db.table.metadata_log_entries;

А это пример в Dremio:

SELECT * FROM TABLE(table_history('my_table'));

Сценарии использования:

Отслеживание изменений метаданных - позволяет увидеть, как часто фиксируются файлы метаданных и связаны ли изменения с обновлениями схемы, созданием снимков или операциями уровня каталога.
Отладка эволюции таблицы - если таблица внезапно перестала читаться, эта таблица помогает найти последний заведомо корректный файл метаданных и облегчает восстановление, особенно в сценариях аварийного восстановления.
Перекрёстная проверка со снимками - соединив эту таблицу со snapshots или history, можно проанализировать наличие осиротевших файлов метаданных или проверить шаблоны использования снимков и схем.

Например:

SELECT l.timestamp, l.file, s.operation
FROM db.table.metadata_log_entries l
LEFT JOIN db.table.snapshots s
 ON l.latest_snapshot_id = s.snapshot_id;

Поддержание чистой, разумной истории файлов метаданных необходимо для эффективной работы таблицы и диагностики. Истечение снимков закрывает очистку файлов данных, а таблица metadata_log_entries даёт структурный аудиторский след, особенно важный в регулируемых средах и при сопровождении долгоживущих таблиц.

A.5 Таблица метаданных manifests

Таблица метаданных manifests даёт подробную информацию о файлах манифестов, используемых текущим снимком таблицы Apache Iceberg. Файлы манифестов - промежуточные файлы, хранящие ссылки на группы файлов данных или удалений, что делает их критичными для понимания раскладки и характеристик производительности таблицы.

Каждая строка этой таблицы представляет файл манифеста и включает следующие поля:

path - URI к файлу манифеста (обычно файл Avro)
length - размер файла манифеста в байтах
partition_spec_id - идентификатор использованной спецификации партиционирования
added_snapshot_id - снимок, добавивший этот манифест
added_data_files_count, existing_data_files_count, deleted_data_files_count - счётчики изменений файлов
partition_summaries - сводная статистика, например нижние и верхние границы значений партиций

Вот пример запроса в Spark:

SELECT * FROM db.table.manifests;

А это пример в Dremio:

SELECT * FROM TABLE(table_manifests('db.table'));

Сценарии использования:

Состояние компактизации - чрезмерное число мелких файлов манифестов или множество манифестов, ссылающихся лишь на несколько файлов данных, сигнализируют о необходимости компактизации метаданных. Такая фрагментация добавляет издержек планированию и сканированию запросов.
Понимание распределения партиций - анализируя partition_summaries, можно оценить перекос или распределение по партициям, что полезно при настройке стратегий партиционирования.
Отладка поведения снимков - используйте added_snapshot_id, чтобы проследить, какой снимок добавил конкретные манифесты, и сопоставить это с операциями вроде append, overwrite или delete.

Например:

SELECT path, length, added_snapshot_id
FROM db.table.manifests
ORDER BY length DESC
LIMIT 10;

Лучшие практики:

Следите за числом манифестов - рост числа манифестов замедляет планирование. Используйте метрики из этой таблицы, чтобы динамически запускать компактизацию метаданных.
Изучайте сводки по партициям - выявляйте недозагруженные или перекошенные партиции, которым может понадобиться перепартиционирование или лучшая кластеризация.
Отслеживайте раздувание манифестов - со временем манифесты растут в числе или размере, даже если данные не увеличиваются пропорционально. Это может указывать на неэффективные шаблоны записи или отсутствие периодической оптимизации.

A.6 Таблица метаданных partitions

Таблица метаданных partitions в Apache Iceberg даёт представление о том, как данные физически распределены по партициям в текущем снимке. Эти метаданные критичны для понимания распределения хранения, выявления перекоса и оптимизации производительности запросов.

Каждая строка таблицы partitions представляет партицию и включает следующие поля:

partition - ключ партиции (например, дата, регион или составной ключ)
spec_id - идентификатор использованной спецификации партиционирования
record_count - число записей в партиции
file_count - общее число файлов данных
total_data_file_size_in_bytes - суммарный размер файлов данных в партиции
position_delete_record_count, position_delete_file_count, equality_delete_record_count, equality_delete_file_count - метрики файлов удалений
last_updated_at - метка времени последнего изменения
last_updated_snapshot_id - идентификатор снимка, связанного с последним обновлением

Вот пример запроса в Spark:

SELECT * FROM db.table.partitions;

А это пример в Dremio:

SELECT * FROM TABLE(table_partitions('db.table'));

Сценарии использования:

Обнаружение перекоса - сильные дисбалансы record_count или file_count между партициями ухудшают производительность. Выявление таких выбросов помогает нацелить компактизацию или перепартиционирование:

SELECT partition, file_count
FROM db.table.partitions
ORDER BY file_count DESC
LIMIT 5;

Накопление файлов удалений - большое число удалённых файлов в отдельных партициях может указывать на частые обновления или удаления, требующие точечной компактизации или очистки.
Мониторинг хранения - метрика total_data_file_size_in_bytes позволяет командам отслеживать рост данных и использование хранилища по партициям.
Точечная оптимизация - отфильтровав партиции с большим числом файлов или крупным размером, можно выборочно компактизировать или переписать данные ради снижения издержек планирования запросов.

Лучшие практики:

Регулярно проверяйте состояние партиций - используйте эту таблицу для выявления горячих точек и убедитесь, что стратегии партиционирования по-прежнему отвечают меняющимся шаблонам запросов.
Сочетайте с метриками кластеризации - в Dremio дополняйте сведения о партициях метриками состояния кластеризации, чтобы решать, когда запускать OPTIMIZE TABLE.
Отсеивайте устаревшие партиции - выявляйте партиции, давно не обновлявшиеся, и оценивайте их на перенос в холодное хранилище или удаление, если они больше не нужны.

A.7 Таблица метаданных files

Таблица метаданных files даёт исчерпывающее представление обо всех активных файлах данных и удалений в текущем снимке таблицы Apache Iceberg. Эта таблица метаданных необходима для изучения статистики на уровне файлов, оценки состояния таблицы и диагностики проблем производительности, вызванных распределением файлов.

Каждая строка таблицы метаданных files соответствует файлу и включает следующие поля:

content - тип файла (0 - данные, 1 - позиционное удаление, 2 - удаление по равенству)
file_path - полный путь к файлу в хранилище
file_format - формат файла (например, Parquet)
spec_id - идентификатор спецификации партиционирования
record_count - число записей в файле
file_size_in_bytes - размер файла
column_sizes, value_counts, null_value_counts, nan_value_counts - метрики на уровне столбцов
lower_bounds, upper_bounds - диапазоны значений столбцов
split_offsets, equality_ids, sort_order_id
readable_metrics - сводка статистики файла в удобочитаемом виде

Вот пример запроса в Spark:

SELECT * FROM db.table.files;

А это пример в Dremio:

SELECT * FROM TABLE(table_files('db.table'));

Сценарии использования:

Обнаружение мелких файлов - выявляйте файлы меньше вашего порога компактизации, чтобы нацелить на них переписывание:

SELECT file_path, file_size_in_bytes
FROM db.table.files
WHERE file_size_in_bytes <134217728;

Фильтрация по типу содержимого - отличайте файлы данных от файлов удалений, чтобы диагностировать деградацию производительности Merge-on-Read (MOR):

SELECT file_path, content
FROM db.table.files
WHERE content != 0;

Анализ на уровне столбцов - изучайте число null или распределение значений по столбцам, чтобы понять качество данных и шаблоны кластеризации:

SELECT readable_metrics
FROM db.table.files
WHERE file_path LIKE '%parquet';

Проверка порядка сортировки и партиционирования - используйте lower_bounds и upper_bounds, чтобы проверить эффективность кластеризации и группировки данных.

Лучшие практики:

Регулярный осмотр - периодически запрашивайте таблицу files, чтобы следить за размерами файлов и их сбалансированностью, особенно при потоковых или высоконагруженных на запись сценариях.
Фильтруйте по типу файла - отдельно нацеливайтесь на файлы удалений ради очистки или расследования, особенно в сценариях MOR.
Оптимизация на уровне столбцов - по метрикам выявляйте столбцы с избытком null или перекосом и при необходимости корректируйте партиционирование или порядок сортировки ради производительности.

A.8 Таблица метаданных position_deletes

Таблица метаданных position_deletes отслеживает файлы позиционных удалений, которые указывают Iceberg пропускать конкретные позиции строк внутри файлов данных. Эти файлы критичны для поддержки поведения MOR, особенно в операциях upsert и удаления.

Каждая строка представляет одно действие удаления и включает следующие поля:

file_path - путь к исходному файлу данных
pos - позиция строки, подлежащей удалению
row - данные удалённой строки (необязательно)
partition - значения ключа партиции
spec_id - идентификатор спецификации партиционирования
delete_file_path - путь к файлу удаления, где находится инструкция

Вот пример запроса в Spark:

SELECT * FROM db.table.position_deletes;

А это пример в Dremio:

SELECT * FROM TABLE(table('db.table').position_deletes);

Сценарии использования:

Понимание стоимости upsert-операций - по мере роста числа upsert-операций в режиме MOR растёт и число записей об удалении, что ухудшает производительность чтения. Используйте эту таблицу, чтобы измерить и локализовать эффект:

SELECT COUNT(*) FROM db.table.position_deletes;

Нацеливание компактизации - определяйте, в каких партициях или файлах накопилось много позиционных удалений:

SELECT partition, COUNT(*) AS delete_count
FROM db.table.position_deletes
GROUP BY partition
ORDER BY delete_count DESC;

Аудит и отладка - изучайте, какие строки были удалены и когда, чтобы проверить транзакционную целостность или разобраться с неожиданными результатами.

Лучшие практики:

Следите за накоплением - файлы позиционных удалений читаются при каждом запросе к таблицам MOR. Наблюдение за этой таблицей помогает понять, когда нужна компактизация, чтобы слить удаления в новые базовые файлы.
Продуманное истечение снимков - поскольку удаления вычищаются только после истечения соответствующих снимков, согласование объёма файлов удалений с политиками удержания снимков - ключ к управлению производительностью.
Избегайте усиления чтения - избыток файлов удалений заставляет читателей Iceberg выполнять несколько дисковых чтений на строку. Используйте эти метаданные, чтобы сдерживать рост числа файлов удалений плановыми переписываниями.

A.9 Таблица метаданных all_data_files

Таблица метаданных all_data_files даёт более широкий взгляд на файлы данных, чем таблица files, поскольку включает файлы, достижимые через текущую историю снимков Iceberg и семантику путешествий во времени, а не только те, на которые ссылается последний снимок. В отличие от files, отражающей лишь текущее состояние таблицы, all_data_files показывает файлы данных, связанные со снимками, ещё пригодными для путешествий во времени. Однако это не постоянная запись обо всех когда-либо записанных файлах: как только снимки истекают и их файлы становятся недостижимы из любого оставшегося снимка, тега или ветки, эти файлы перестают появляться в all_data_files.

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

file_path - полный путь к файлу данных
file_format - формат файла: Parquet, Avro, ORC
partition - значения партиции (если таблица партиционирована)
record_count - число строк в файле
file_size_in_bytes - размер файла на диске
column_sizes, value_counts, null_value_counts, lower_bounds, upper_bounds - статистика, полезная для настройки, анализа и оптимизации
spec_id, sort_order_id - структурные метаданные для интерпретации файла в контексте таблицы
split_offsets - используются для деления файлов при параллельном чтении

Вот пример запроса в Spark:

SELECT * FROM db.table.all_data_files;

А это пример в Dremio:

SELECT * FROM TABLE(table_all_data_files('db.table'));

Сценарии использования:

Криминалистическая отладка - когда файл исчезает из таблицы files, хотя раньше присутствовал, all_data_files помогает проследить, когда он был добавлен и, возможно, удалён.
Анализ исторической оптимизации - измеряйте, как менялись размеры файлов и распределение по партициям:

SELECT
 partition,
 MAX(file_size_in_bytes) AS max_size,
 MIN(file_size_in_bytes) AS min_size
FROM db.table.all_data_files
GROUP BY partition;

Регуляторный аудит - в процессах комплаенса (например, GDPR) понимание жизненного цикла конкретных файлов критично. Эта таблица даёт нужную прослеживаемость.
Диагностика производительности - можно выявить старые файлы, пропущенные процедурами компактизации или сохранившиеся из-за отставания истечения снимков.

Лучшие практики:

Соединяйте со снимками - сочетайте эту таблицу с метаданными снимков, чтобы построить полную временну́ю линию действий с файлами.
Используйте в автоматизации - применяйте эту таблицу в конвейерах планирования компактизации для обнаружения устаревших или чрезмерно крупных файлов, всё ещё занимающих место.
Балансируйте с удержанием - таблица ценна, но объём данных в all_data_files может значительно расти. Убедитесь, что политики истечения снимков настроены так, чтобы избежать неконтролируемых издержек на метаданные.

A.10 Таблица метаданных all_delete_files

Таблица метаданных all_delete_files даёт более широкий взгляд на файлы удалений, чем delete_files, поскольку включает файлы удалений, достижимые через текущую историю снимков Iceberg и семантику путешествий во времени, а не только те, на которые ссылается последний снимок. Она включает и позиционные удаления, и удаления по равенству, на которые ссылается хотя бы один действующий снимок, тег или ветка. Однако это не постоянная запись обо всех когда-либо записанных файлах удалений: как только снимки истекают и файлы удалений, на которые они ссылались, становятся недостижимы, эти файлы перестают появляться в all_delete_files. Таблица полезна для диагностики поведения удержания, аудита операций удаления и понимания текущего объёма нагрузок, основанных на файлах удалений.

Каждая строка соответствует файлу удаления и включает такие метаданные:

file_path - полный путь к файлу удаления
file_format - обычно Parquet
partition - сведения о партиции для строк, на которые нацелен файл удаления
record_count - число строк, помеченных к удалению в файле
file_size_in_bytes - размер файла удаления на диске
column_sizes, value_counts, null_value_counts - статистика, описывающая содержимое файла удаления
lower_bounds, upper_bounds - диапазоны значений, затронутые файлом удаления
split_offsets - используются для параллельного чтения при планировании сканирования
content - различает позиционное удаление и удаление по равенству

Вот пример запроса в Spark:

SELECT * FROM db.table.all_delete_files;

А это пример в Dremio:

SELECT * FROM TABLE(table_all_delete_files('db.table'));

Сценарии использования:

Мониторинг накопления при MOR - нагрузки MOR со временем накапливают файлы удалений. Эта таблица помогает измерить накопление и его влияние на производительность запросов:

SELECT COUNT(*) AS num_delete_files,
      SUM(record_count) AS total_deleted_rows
FROM db.table.all_delete_files;

Аудит соответствия требованиям - проверяйте, были ли удаления, запрошенные ради соблюдения норм (например, GDPR или CCPA), зафиксированы и сохранены должным образом.
Готовность к компактизации - по наличию и объёму файлов удалений определяйте, когда пора компактизировать таблицу ради восстановления производительности.
Происхождение файлов и отладка - отслеживайте, когда и как применялись удаления во времени, и выявляйте удаления, которые могли быть пропущены или применены неверно.

Лучшие практики:

Истечение снимков - обеспечьте регулярное истечение снимков, чтобы Iceberg мог очищать устаревшие файлы удалений и предотвращать лишние сканирования данных.
Мониторинг размеров - удерживайте размер и число файлов удалений в разумных пределах, чтобы не ухудшать производительность запросов. Используйте эти метрики для запуска фоновых задач обслуживания.
Внимание к MOR - в таблицах MOR следите за тем, как долго файлы удалений остаются активными, и планируйте периодические переписывания ради снижения издержек при чтении.

A.11 Таблица метаданных all_entries

Таблица метаданных all_entries даёт самый детальный взгляд на эволюцию таблицы Iceberg на уровне файлов, показывая записи манифестов по всем снимкам, ещё достижимым для путешествий во времени. Она включает записи и о файлах данных, и о файлах удалений вместе со статусом каждой записи (например, был ли файл добавлен или удалён в конкретном снимке) и контекстом, нужным, чтобы проследить, как менялся набор файлов таблицы со временем. Однако это не безграничная история: записи, связанные только со снимками, которые истекли и стали недостижимы, в all_entries не появятся.

Каждая строка в all_entries представляет запись манифеста и включает следующее:

status - обозначает состояние жизненного цикла файла:
0 - существующий файл из предыдущего снимка
1 - добавлен в текущем снимке
2 - удалён в текущем снимке
snapshot_id - снимок, в котором запись была добавлена или удалена
sequence_number и file_sequence_number - помогают определить порядок операций
data_file - структура с метаданными вроде пути к файлу, формата, партиции и числа строк
readable_metrics - удобочитаемая разбивка статистики по столбцам для быстрой диагностики

Вот пример запроса в Spark:

SELECT * FROM db.table.all_entries;

А это пример в Dremio:

SELECT * FROM TABLE(table_all_entries('db.table'));

Сценарии использования:

Отслеживание происхождения - эта таблица идеальна для построения подробной родословной того, когда каждый файл был добавлен и удалён. Она помогает отвечать на вопросы вроде «Какой снимок добавил этот файл?» и «Когда его заменили?».
Аудит и отладка - соединив all_entries со snapshots, можно воссоздать жизненный цикл файла и выяснить, как и когда файл данных или удаления менял состояние:

SELECT e.status, e.snapshot_id, s.committed_at, e.data_file.file_path
FROM db.table.all_entries e
JOIN db.table.snapshots s ON e.snapshot_id = s.snapshot_id
ORDER BY s.committed_at;

Захват изменений (CDC) - там, где нужно детальное отслеживание изменений, эта таблица даёт основу для анализа различий на уровне файлов между снимками.
Анализ влияния - при планировании истечения снимков или компактизации эта таблица помогает оценить масштаб и избыточность использования файлов между версиями.

Лучшие практики:

Учитывайте истечение снимков - поскольку таблица включает записи из всех снимков, она может стать большой. Регулярно удаляйте старые снимки, чтобы объём метаданных оставался управляемым.
Проверяйте эффективность манифестов - ищите избыточные картины, например одни и те же файлы, появляющиеся во множестве снимков, и оценивайте необходимость оптимизации.
Пишите диагностические скрипты - создавайте скрипты оповещений, выявляющие картины вроде множества удалённых файлов, сохраняющихся между снимками, что указывает на необходимость обслуживания.

A.12 Таблица метаданных all_manifests

Таблица метаданных all_manifests в Apache Iceberg даёт полное историческое представление обо всех файлах манифестов, когда-либо связанных с таблицей во всех действующих снимках, а не только в текущем. Это делает её критически важным ресурсом для понимания долгосрочной эволюции и состояния метаданных таблицы.

Каждая строка в all_manifests даёт метаданные об одном файле манифеста, включая следующее:

content - тип хранимого содержимого: 0 - файлы данных, 1 - файлы позиционных удалений, 2 - файлы удалений по равенству
path - полный URI к файлу манифеста
length - размер манифеста в байтах
partition_spec_id - идентификатор спецификации партиционирования, связанной с манифестом
added_snapshot_id - снимок, добавивший этот манифест
added_data_files_count, existing_data_files_count, deleted_data_files_count - показывают, как менялся манифест
partition_summaries - сводная статистика по партициям, представленным в этом манифесте
reference_snapshot_id - необязательное поле со ссылкой на снимок, создавший манифест

Вот пример запроса в Spark:

SELECT * FROM db.table.all_manifests;

А это пример в Dremio:

SELECT * FROM TABLE(table_all_manifests('db.table'));

Сценарии использования:

Анализ объёма метаданных - изучая, сколько манифестов существует и каков их размер, можно следить за разрастанием метаданных - распространённой причиной деградации производительности запросов.
Отслеживание изменений - понимайте, как менялось число файлов данных и удалений со временем, сравнивая записи манифестов между снимками.
Сведения о партициях - partition_summaries помогают увидеть меняющееся распределение данных и направить изменения спецификации партиционирования.
Историческая отладка - если производительность таблицы ухудшилась, запрос к all_manifests поможет проследить, не появилось ли внезапно большое число файлов удалений или данных.

Лучшие практики:

Триггеры компактизации - используйте added_data_files_count и deleted_data_files_count, чтобы отмечать манифесты, регулярно накапливающие множество мелких файлов или удалений, что сигнализирует о необходимости компактизации.
Истечение снимков - как и другие таблицы метаданных «all», all_manifests отражает полную историю. Удаление старых снимков сокращает её размер и повышает производительность запросов.
Мониторинг сводок по партициям - автоматизируйте проверки partition_summaries, чтобы выявлять перекос, дублирование данных между партициями или чрезмерно фрагментированное партиционирование.

A.13 Таблица метаданных refs

Таблица метаданных refs даёт представление обо всех именованных ссылках, связанных с таблицей Iceberg, включая ветки и теги. Эта возможность вытекает из нативной поддержки ветвления и тегирования в Iceberg, которая привносит версионируемые процессы работы с данными, напоминающие привычные конструкции систем контроля версий.

В Apache Iceberg каждая таблица ведёт журнал снимков ради путешествий во времени и изоляции снимков. Традиционно пользователи могли ссылаться на эти снимки лишь косвенно - по метке времени или идентификатору. Но ветвление и тегирование расширяют эту модель, позволяя создавать именованные ссылки на конкретные снимки, каждая со своим жизненным циклом:

Теги - неизменяемые ссылки на конкретный снимок. Они полезны для фиксации исторических состояний ради аудита, комплаенса или отслеживания происхождения данных. Например, снимок на конец года можно пометить тегом EOY-2024 и хранить бессрочно.
Ветки - изменяемые ссылки, развивающиеся вместе с новыми снимками. Они позволяют параллельно развивать независимые истории снимков. Это особенно полезно для экспериментальных конвейеров, процессов write-audit-publish или регуляторных песочниц.

У каждой ссылки может быть своя политика удержания, определяющая, как долго она сохраняется и сколько снимков должна удерживать.

Таблица метаданных refs содержит по одной строке на ссылку и даёт следующие поля:

name - имя ветки или тега
type - либо BRANCH, либо TAG
snapshot_id - идентификатор снимка, на который сейчас указывает ссылка
max_reference_age_in_ms - максимальный возраст (в миллисекундах), в течение которого ссылка может сохраняться
min_snapshots_to_keep - для веток: минимальное число снимков, которое должно сохраняться
max_snapshot_age_in_ms - максимальный возраст отдельных снимков, сохраняемых под этой ссылкой

Эти свойства удержания учитываются при истечении снимков, определяя, какие файлы метаданных и данных можно безопасно удалить.

А это пример запроса в Spark:

SELECT * FROM db.table.refs;

Таблица refs необходима для управления продвинутыми сценариями жизненного цикла:

Проверяемость и комплаенс - сохраняйте снимки, значимые для юридических или регуляторных расследований, долгоживущими тегами.
Экспериментальные процессы - изолируйте записи на отдельных ветках, не затрагивая промышленные данные.
Восстановление данных - безопасно путешествуйте во времени или восстанавливайте состояние таблицы по помеченным тегами или ветками снимкам.

С помощью таблицы refs можно динамически оценивать, какие снимки защищены от истечения, и обеспечивать сохранность критически важных ссылок согласно политикам бизнеса.

A.14 Мониторинг состояния таблиц с помощью таблиц метаданных

Сопровождение lakehouse на Iceberg на масштабе требует упреждающего мониторинга состояния таблиц. К счастью, таблицы метаданных Iceberg дают мощный набор инструментов для оценки раскладки данных, оборачиваемости снимков и разрастания числа файлов. Опираясь на них, можно проектировать автоматические процессы, запускающие компактизацию, истечение снимков и другие работы по обслуживанию исходя из наблюдаемых метрик, а не по фиксированному расписанию.

Особенно полезны для оценки состояния таблиц следующие таблицы метаданных:

files - анализ распределения размеров файлов и группировки данных. Большое число мелких файлов может указывать на необходимость компактизации.
manifests - наблюдение за числом манифестов и числом файлов на манифест. Растущее число манифестов может сигнализировать о чрезмерной оборачиваемости снимков.
snapshots - оценка частоты и объёма создания снимков. Частые снимки с минимальными изменениями могут указывать на неэффективные шаблоны записи.
refs - проверка того, что критически важные ветки и теги не удалены по неосторожности при очистке снимков. Регулярно запрашивая эти таблицы, можно получить ответы на вопросы вроде следующих:
Сколько файлов не дотягивает до целевого порога размера?
Хорошо ли файлы согласованы с партиционированием и порядками сортировки?
Не накапливаются ли осиротевшие или «висящие» файлы удалений?
Сколько снимков было создано за последние 24 часа?

Эти вопросы помогают перейти от ручных операций к разумной автоматизации.

A.14.1 Пример: запуск компактизации на основе файловых метрик

Предположим, вы хотите запускать компактизацию, когда более 10% файлов таблицы меньше 128 МБ. Можно выполнить примерно такой запрос:

SELECT COUNT(*) AS total_files,
      SUM(CASE WHEN file_size_in_bytes <134217728 THEN 1 ELSE 0 END) AS small_files
FROM db.table.files;

Затем эти метрики можно использовать вместе с инструментами оркестрации вроде Apache Airflow, dbt или собственных задач Spark, чтобы решать, когда запускать rewrite_data_files.

A.14.2 Пример: мониторинг частоты создания снимков

Чтобы оценить, не создаются ли снимки слишком часто, можно выполнить такой запрос:

SELECT COUNT(*) AS snapshots_last_24h
FROM db.table.snapshots
WHERE committed_at >CURRENT_TIMESTAMP() - INTERVAL 1 DAY;

Это помогает диагностировать избыточные операции обновления или неверно настроенные процессы приёма.

A.14.3 Автоматизация обслуживания на основе полученных данных

Задавая пороги и отслеживая тренды этих метрик, можно автоматизировать следующее:

Компактизацию - когда число мелких файлов превышает порог
Истечение снимков - когда число или возраст снимков выходит за пределы
Очистку файлов-сирот - когда использование хранилища расходится с отслеживаемыми файлами

В сочетании с ветвлением, тегированием и истечением с учётом удержания автоматизация на основе метаданных обеспечивает производительность и компактность вашего lakehouse на Iceberg даже при тяжёлых и меняющихся нагрузках.