Перейти к основному содержимому
Перейти к основному содержимому

Движок таблиц Iceberg

осторожно

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

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

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

Этот движок предоставляет интеграцию только для чтения с существующими таблицами Apache Iceberg в Amazon S3, Azure, HDFS и локально хранимыми таблицами.

Создание таблицы​

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

Аргументы движка​

Описание аргументов совпадает с описанием аргументов в движках S3, AzureBlobStorage, HDFS и File соответственно. format обозначает формат файлов данных в таблице Iceberg.

Параметры движка могут быть указаны с помощью Именованных Коллекций

Пример​

Использование именованных коллекций:

Псевдонимы​

Движок таблиц Iceberg сейчас является псевдонимом для IcebergS3.

Эволюция схемы​

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

  • int -> long
  • float -> double
  • decimal(P, S) -> decimal(P', S), где P' > P.

В настоящее время невозможно изменить вложенные структуры или типы элементов в массивах и картах.

Чтобы прочитать таблицу, в которой схема изменилась после её создания с динамическим выводом схемы, установите allow_dynamic_metadata_for_data_lakes = true при создании таблицы.

Отсечение партиций​

ClickHouse поддерживает отсечение партиций во время операторов SELECT для таблиц Iceberg, что помогает оптимизировать производительность запросов, пропуская несущественные файлы данных. Чтобы включить отсечение партиций, установите use_iceberg_partition_pruning = 1. Для получения дополнительной информации об отсечении партиций Iceberg обратитесь по адресу https://iceberg.apache.org/spec/#partitioning

Путешествия во времени​

ClickHouse поддерживает путешествия во времени для таблиц Iceberg, позволяя вам запрашивать исторические данные с конкретной меткой времени или идентификатором снимка.

Основное использование​

Примечание: Вы не можете указать параметры iceberg_timestamp_ms и iceberg_snapshot_id в одном и том же запросе.

Важные соображения​

  • Снимки обычно создаются, когда:

    • Новые данные записываются в таблицу
    • Выполняется какая-либо компакция данных

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

Примеры сценариев​

Все сценарии написаны в Spark, так как CH пока не поддерживает запись в таблицы Iceberg.

Сценарий 1: Изменения схемы без новых снимков​

Рассмотрим следующую последовательность операций:

Результаты запроса в разные временные штампы:

  • На ts1 и ts2: Появляются только оригинальные две колонки
  • На ts3: Появляются все три колонки, с NULL для цены первой строки

Сценарий 2: Различия между исторической и текущей схемой​

Запрос путешествия во времени в текущий момент может показать другую схему, чем текущая таблица:

Это происходит потому, что ALTER TABLE не создает новый снимок, но для текущей таблицы Spark берет значение schema_id из последнего файла метаданных, а не из снимка.

Сценарий 3: Историческое состояние таблицы до записи​

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

В ClickHouse поведение согласуется с Spark. Вы можете мысленно заменить запросы выборки Spark на запросы выборки ClickHouse, и это будет работать так же.

Разрешение файла метаданных​

При использовании движка таблиц Iceberg в ClickHouse система должна найти правильный файл metadata.json, который описывает структуру таблицы Iceberg. Вот как работает этот процесс разрешения:

  1. Спецификация прямого пути:

    • Если вы установите iceberg_metadata_file_path, система будет использовать этот точный путь, объединив его с путем к директории таблицы Iceberg.
    • Когда эта настройка предоставлена, все другие настройки разрешения игнорируются.

  2. Сопоставление UUID таблицы:

    • Если указан iceberg_metadata_table_uuid, система будет:
      • Смотреть только на файлы .metadata.json в директории metadata
      • Фильтровать файлы, содержащие поле table-uuid, соответствующее вашему указанному UUID (не учитывая регистр)

  3. Поиск по умолчанию:

    • Если ни одна из вышеуказанных настроек не предоставлена, все файлы .metadata.json в директории metadata становятся кандидатами

Выбор самого последнего файла​

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

  • Если включено iceberg_recent_metadata_file_by_last_updated_ms_field:

    • Выбирается файл с наибольшим значением last-updated-ms

  • В противном случае:

    • Выбирается файл с самым высоким номером версии
    • (Версия отображается как V в именах файлов, отформатированных как V.metadata.json или V-uuid.metadata.json)

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

Примечание: Хотя каталоги Iceberg обычно обрабатывают разрешение метаданных, движок таблиц Iceberg в ClickHouse непосредственно интерпретирует файлы, хранящиеся в S3, как таблицы Iceberg, поэтому понимание этих правил разрешения имеет важное значение.

Кэш данных​

Движок таблиц Iceberg и табличная функция поддерживают кэширование данных аналогично хранилищам S3, AzureBlobStorage, HDFS. См. здесь.

Кэш метаданных​

Движок таблиц Iceberg и табличная функция поддерживают кэш метаданных, хранящий информацию о manifest-файлах, списке манифестов и метаданных JSON. Кэш хранится в памяти. Эта функция управляется установкой use_iceberg_metadata_files_cache, которая включена по умолчанию.

См. также​