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

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

Обратите внимание, что таблица 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}.
Пример (включение экспериментального движка Paimon и кэша файлов метаданных):
То, как применяется 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.
Чтение указанного снимка — всегда возвращает дельту снимка 1 независимо от текущей водяной метки:
Ограничение числа снимков в батче — если ожидают обработки три новых снимка, обрабатывайте не более двух за один запрос:

Откат хранилища назад

Курсор 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):
Шаг 3 — Создайте refreshable Materialized View:
Каждые 10 секунд MV выполняет 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:
  • CHAR
  • VARCHAR
  • BOOLEAN
  • DECIMAL
  • TINYINT
  • SMALLINT
  • INTEGER
  • DATE
  • TIME
  • TIMESTAMP
  • TIMESTAMP WITH LOCAL TIME ZONE
  • BIGINT
  • FLOAT
  • DOUBLE