Создание таблицы
Обратите внимание, что таблица Paimon уже должна существовать в хранилище; эта команда не поддерживает DDL-параметры для создания новой таблицы. Создание таблицPaimon* регулируется параметром allow_experimental_paimon_storage_engine (по умолчанию он отключен), поэтому включите его перед выполнением CREATE TABLE.
Аргументы движка
Описание аргументов совпадает с описанием аргументов для движковS3, AzureBlobStorage, HDFS и File соответственно.
format обозначает формат файлов данных в таблице Paimon.
Параметры движка можно задавать с помощью именованных коллекций
Пример
Возможности
- Чтение снимка из последнего снимка таблицы.
- Инкрементальное чтение по идентификатору зафиксированного снимка, если эта возможность включена.
- Отсечение партиций, если включен
use_paimon_partition_pruning. - Необязательное фоновое обновление метаданных при соответствующей настройке.
- Стабильный UUID таблицы при использовании баз данных Atomic/Replicated, что позволяет использовать макросы
{uuid}в путях Keeper.
Таблицы с первичным ключом
Слияние при чтении (merge-on-read) не реализовано, поэтому таблицы с первичным ключом прочитать невозможно: считыватель возвращает необработанное объединение файлов данных снимка, в котором остаются версии строк, уже замещённые последующими операциями upsert. Поэтому при чтении таблицы, в схеме которой объявленprimary-key, генерируется исключение.
Таблицы с векторами удаления
Векторы удаления не применяются, поэтому снимки с векторами удаления прочитать нельзя: результат по-прежнему содержал бы строки, удалённые последующими операторамиDELETE и UPDATE. По этой причине чтение снимка, индексный манифест которого содержит
векторы удаления, выбрасывает исключение — даже после отключения deletion-vectors.enabled.
Полная компакция в Paimon (compact_strategy => 'full') применяет векторы удаления, и снимки, созданные после
неё, снова становятся доступны для чтения.
Инкрементальное чтение останавливается на первом необработанном снимке с векторами удаления и остаётся на нём даже после полной
компакции, поскольку все снимки вплоть до этой компакции ссылаются на те же векторы удаления. Курсор при этом не сдвигается.
Чтение возобновится, когда Paimon удалит эти снимки по истечении срока хранения, либо когда от них откажутся, переместив курсор на снимок
полной компакции; при этом все ещё не обработанные снимки до него отбрасываются (см.
Когда снимок не удаётся прочитать):
Настройки
Этот движок использует те же настройки, что и соответствующие движки объектного хранилища, а также добавляет настройки, специфичные для Paimon:allow_experimental_paimon_storage_engine— включает создание движков таблицPaimon,PaimonS3,PaimonAzure,PaimonHDFSиPaimonLocal. По умолчанию:0(отключено).use_paimon_metadata_files_cache— включает кэш файлов метаданных Paimon (кэширует десериализованные списки manifest и manifest-файлы). Установите1, чтобы включить,0— чтобы отключить. По умолчанию:0. Применение этой настройки различается для табличных функций и движков постоянных таблиц — см. примечание ниже.paimon_incremental_read— включает режим инкрементального чтения.paimon_metadata_refresh_interval_sec— интервал фонового обновления метаданных в секундах. Если задано значение больше 0, фоновая задача периодически загружает из объектного хранилища последний снимок и схему. По умолчанию: 30.paimon_keeper_path— путь Keeper для состояния инкрементального чтения. Должен быть задан и быть уникальным для каждой таблицы; поддерживает макросы, такие как{database},{table},{uuid}.paimon_replica_name— имя реплики для состояния инкрементального чтения. Должно быть задано и быть уникальным для каждой реплики; поддерживает макросы, такие как{replica}.
То, как применяется
use_paimon_metadata_files_cache, зависит от способа доступа к таблице Paimon:- Табличные функции (например,
SELECT ... FROM paimonS3(...)): решение об использовании кэша принимается для каждого запроса, поэтомуSETTINGS use_paimon_metadata_files_cache = 1можно передать прямо вSELECT. - Постоянные движки таблиц (
PaimonS3,PaimonAzure,PaimonHDFS,PaimonLocalи псевдонимPaimon): решение об использовании кэша фиксируется один раз при инициализации метаданных таблицы и сохраняется в неизменяемых постоянных компонентах; механизм обновления метаданных намеренно не перечитывает эту настройку. Поэтому передачаSETTINGS use_paimon_metadata_files_cache = 1вSELECTдля уже инициализированной постоянной таблицы не дает эффекта — продолжает использоваться ранее зафиксированное решение. Чтобы изменить его, задайтеuse_paimon_metadata_files_cacheдо инициализации метаданных таблицы или выполнитеDROP, а затем повторныйCREATEтаблицы с нужным значением.
paimon_metadata_files_cache_size) не фиксируется: это настройка runtime, которую можно изменить через SYSTEM RELOAD CONFIG, и она вступает в силу немедленно даже для уже инициализированных таблиц.Примеры инкрементального чтения
Инкрементальное чтение с состоянием в Keeper:Настройки на уровне запроса для инкрементального чтения
Следующие настройки действуют на уровне запроса (передаются черезSELECT ... SETTINGS, а не в CREATE TABLE). Они управляют поведением инкрементального чтения в рамках отдельного запроса:
paimon_target_snapshot_id— считывать только дельту указанного снимка. Зафиксированная водяная метка в Keeper не продвигается, поэтому один и тот же снимок можно перечитывать сколько угодно раз. По умолчанию:-1(отключено).max_consume_snapshots— максимальное число снимков, считываемых за одно инкрементальное чтение. Если в источнике накопилось много непрочитанных снимков, этот параметр ограничивает, сколько из них будет считано за один запрос, чтобы контролировать размер батча.0означает отсутствие ограничений. По умолчанию:0.
Откат хранилища назад
Курсор Keeper по путиpaimon_keeper_path фиксирует, до какого места поток уже прочитан и обработан, а инкрементальное чтение исходит из того, что хранилище всегда движется только вперёд: идентификаторы снимков Paimon монотонно возрастают и никогда не используются повторно. Удалять устаревшие снимки можно: при этом удаляется префикс последовательности, а идентификаторы выше него остаются нетронутыми.
Откат хранилища назад нарушает это допущение. Восстановление хранилища из более старой резервной копии, откат с помощью другого движка, а также удаление и повторное создание таблицы Paimon по тому же пути — всё это возвращает идентификаторы снимков назад, после чего пишущая сторона повторно использует идентификаторы, которые курсор уже прочитал и обработал.
Откат хранилища необходимо выполнять одновременно со сбросом курсора. После повторного использования идентификаторов ClickHouse не может определить, какие снимки потребитель уже получил, поэтому если не сбросить курсор после отката, доставка становится неопределённой: снимки с повторно использованными идентификаторами могут быть пропущены.
Если после отката курсор указывает дальше самого нового снимка хранилища, чтение завершается ошибкой INVALID_STATE, а не сообщает об отсутствии новых данных, и в тексте ошибки указывается команда для восстановления. Данные не читаются, курсор остаётся неизменным, поэтому каждый последующий опрос будет завершаться той же ошибкой, пока проблема не будет устранена:
committed_snapshot в целях восстановления. Отсутствие курсора означает «данные ещё ни разу не читались», поэтому следующее чтение будет полным повторным чтением всей таблицы, а не продолжением с места остановки.
Перед сбросом курсора приостановите всех потребителей, совместно использующих paimon_keeper_path, включая refreshable materialized view, и дождитесь завершения всех in-flight чтений.
Коммит чтения выполняется только при условии, что курсор не изменился с того момента, как чтение его прочитало. Если курсор изменится в промежутке между этим моментом и коммитом, чтение завершится ошибкой INVALID_STATE, ничего не доставит, а установленное вами значение останется в силе. Чтение, которое уже выполнило коммит, может доставить свой пакет и после сброса курсора; в этом случае откат курсора может привести к повторной доставке этого пакета.
Не удаляйте и не заменяйте processing_lock вручную. Это эфемерный узел, принадлежащий сеансу ClickHouse Keeper, в котором выполняется инкрементальное чтение; управление его жизненным циклом не предназначено для восстановления оператором.
Когда снимок не удаётся прочитать
Снимки с истёкшим в Paimon сроком хранения пропускаются автоматически: при истечении срока удаляется префикс идентификаторов снимков, поэтому всё, что ниже самого раннего снимка в хранилище, заведомо отсутствует, и курсор просто перемещается дальше. Любая другая ошибка чтения снимка — временная ошибка объектного хранилища, повреждённый файл снимка состояния — приводит к сбою запроса, а курсор остаётся на месте. Настройки, позволяющей игнорировать такие ошибки, намеренно не предусмотрено. Пропуск непрочитанного снимка означает безвозвратное удаление закоммиченных в нём данных, а постоянно включённый режим «игнорировать ошибки» превращал бы любой будущий кратковременный сбой сети в незаметную потерю данных. Поскольку курсор не сдвигается, временная ошибка вообще не требует вмешательства: при следующем опросе тот же диапазон будет прочитан повторно, и на этот раз успешно. Если снимок действительно невозможно прочитать, а поток должен двигаться дальше, явно откажитесь от него. Нужная команда указана в сообщении об ошибке, но учитывайте последствия: неудачное чтение ничего не вернуло, поэтому перемещение курсора на нечитаемый снимок означает отказ от всех ещё не обработанных снимков вплоть до него включительно, а не только от нечитаемого. Пусть курсор находится на снимке 1, снимки 2, 3 и 4 ожидают обработки, а снимок 3 прочитать невозможно:Из Paimon в MergeTree через refreshable materialized view
Вы можете построить сквозной конвейер, который непрерывно синхронизирует данные из таблицы Paimon в таблицу семейства MergeTree с помощью refreshable materialized view в режимеAPPEND. В каждом цикле обновления считываются только новые инкрементальные данные из Paimon и добавляются в целевую таблицу.
Шаг 1 — Создайте исходную таблицу Paimon с включенными инкрементальным чтением и обновлением метаданных.
В примере ниже используется PaimonLocal. Замените движок на PaimonS3, PaimonAzure, PaimonHDFS или движок Paimon с автоопределением в зависимости от используемого backend-хранилища:
paimon_metadata_refresh_interval_sec задает интервал фонового обновления метаданных в секундах. Если значение больше 0, фоновая задача периодически подтягивает актуальные снимок и схему из Объектного хранилища, чтобы цикл обновления MV мог видеть недавно зафиксированные данные без ожидания запроса, который запустит обновление метаданных. Значение по умолчанию — 30. Используйте с осторожностью при работе с большим числом таблиц, чтобы избежать чрезмерной нагрузки на Объектное хранилище и операции ввода-вывода Keeper.
Шаг 2 — Создайте целевую таблицу MergeTree (схема скопирована из таблицы Paimon):
SELECT * FROM paimon_mv_source, который возвращает только строки, добавленные после последнего зафиксированного снимка, и дописывает их в paimon_mv_dest.
Очистка:
Остановите MV перед удалением, чтобы фоновое обновление не блокировало выполнение DDL-операций.
Ограничения
- Для инкрементального чтения должен быть настроен Keeper (ZooKeeper).
- Для инкрементального чтения параметр
paimon_keeper_pathдолжен быть задан и быть уникальным для каждой таблицы. paimon_replica_nameдолжен быть уникальным для каждой реплики в рамках одного и того же пути Keeper.- Инкрементальное чтение использует доставку не более одного раза: зафиксированный снимок продвигается в момент сбора файлов данных, ещё до фактического чтения данных. Если запрос завершится ошибкой после сбора файлов, пропущенные снимки не будут повторно прочитаны при повторной попытке.
- Движок таблицы работает в режиме только для чтения; изменение данных не поддерживается.
- Инкрементальное чтение не обрабатывает удаление исторических данных из источника Paimon. Если исходные данные Paimon удаляются или обновляются, соответствующие строки, уже записанные в целевую таблицу семейства MergeTree в ClickHouse, не будут автоматически удалены. Чтобы очистить устаревшие данные, необходимо вручную выполнить
ALTER TABLE ... DELETEдля таблицы семейства MergeTree. - Если базовая таблица Paimon удаляется и создаётся заново по тому же пути объектного хранилища (например, через Flink или Spark), необходимо выполнить
DROPи повторноCREATEсоответствующую таблицу ClickHouse. ClickHouse обнаруживает повторное создание, сравнивая временную метку создания schema-0, и выдаёт ошибку; устаревшую таблицу ClickHouse нельзя использовать, пока она не будет создана заново.
Псевдонимы
Движок таблицыPaimon автоматически определяет тип хранилища по настройке disk и в зависимости от этого использует PaimonS3, PaimonAzure или PaimonLocal. Если disk не указан, по умолчанию используется реализация PaimonS3.
Виртуальные столбцы
_path— Путь к файлу. Тип:LowCardinality(String)._file— Имя файла. Тип:LowCardinality(String)._size— Размер файла в байтах. Тип:Nullable(UInt64). Если размер файла неизвестен, значение —NULL._time— Время последнего изменения файла. Тип:Nullable(DateTime). Если время неизвестно, значение —NULL._etag— ETag файла. Тип:LowCardinality(String). Если ETag неизвестен, значение —NULL.
Поддерживаемые типы данных
Поддерживаемые партиции
Типы данных, поддерживаемые в ключах партиционирования Paimon:CHARVARCHARBOOLEANDECIMALTINYINTSMALLINTINTEGERDATETIMETIMESTAMPTIMESTAMP WITH LOCAL TIME ZONEBIGINTFLOATDOUBLE