Движок таблицы Paimon

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

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

Обратите внимание: таблица Paimon уже должна существовать в хранилище; эта команда не принимает DDL-параметры для создания новой таблицы. Создание таблиц Paimon* требует включённого параметра allow_experimental_paimon_storage_engine (по умолчанию он отключён), поэтому включите его перед выполнением CREATE TABLE.

SET allow_experimental_paimon_storage_engine = 1;

CREATE TABLE paimon_table_s3
    ENGINE = PaimonS3(url,  [, access_key_id, secret_access_key] [,format] [,structure] [,compression])

CREATE TABLE paimon_table_azure
    ENGINE = PaimonAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

CREATE TABLE paimon_table_hdfs
    ENGINE = PaimonHDFS(path_to_table, [,format] [,compression_method])

CREATE TABLE paimon_table_local
    ENGINE = PaimonLocal(path_to_table, [,format] [,compression_method])

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

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

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

Пример

CREATE TABLE paimon_table ENGINE=PaimonS3('http://test.s3.amazonaws.com/clickhouse-bucket/test_table', 'test', 'test')

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

<clickhouse>
    <named_collections>
        <paimon_conf>
            <url>http://test.s3.amazonaws.com/clickhouse-bucket/</url>
            <access_key_id>test</access_key_id>
            <secret_access_key>test</secret_access_key>
        </paimon_conf>
    </named_collections>
</clickhouse>

CREATE TABLE paimon_table ENGINE=PaimonS3(paimon_conf, filename = 'test_table')

Возможности

Чтение данных из последнего снимка таблицы.
Инкрементальное чтение на основе идентификатора зафиксированного снимка, если эта возможность включена.
Отсечение партиций, если включена настройка use_paimon_partition_pruning.
Необязательное фоновое обновление метаданных, если оно настроено.
Стабильный UUID таблицы при использовании баз данных Atomic/Replicated, что позволяет применять макросы {uuid} в путях Keeper.

Settings

Этот движок использует те же настройки, что и соответствующие движки объектного хранилища, а также добавляет настройки, специфичные для Paimon:

allow_experimental_paimon_storage_engine — включает создание движков таблиц Paimon, PaimonS3, PaimonAzure, PaimonHDFS и PaimonLocal. Значение по умолчанию: 0 (отключено).
paimon_incremental_read — включает режим инкрементального чтения.
paimon_metadata_refresh_interval_sec — интервал фонового обновления метаданных в секундах. Если задано значение больше 0, фоновая задача периодически извлекает из объектного хранилища последний снимок и schema. Значение по умолчанию: 30.
paimon_keeper_path — путь в Keeper для состояния инкрементального чтения. Должен быть задан и быть уникальным для каждой таблицы; поддерживает макросы, такие как {database}, {table}, {uuid}.
paimon_replica_name — имя реплики для состояния инкрементального чтения. Должно быть задано и быть уникальным для каждой реплики; поддерживает макросы, такие как {replica}.

Примеры инкрементального чтения

Инкрементальное чтение с состоянием в Keeper:

CREATE TABLE paimon_inc
ENGINE = PaimonS3(paimon_conf, filename = 'paimon_all_types')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/{database}/{uuid}',
    paimon_replica_name = '{replica}';

Настройки на уровне запроса для инкрементального чтения

Следующие настройки действуют на уровне запроса (передаются через SELECT ... SETTINGS, а не в CREATE TABLE). Они управляют поведением инкрементального чтения в рамках отдельного запроса:

paimon_target_snapshot_id — читать только дельту указанного снимка. Зафиксированный watermark в Keeper не сдвигается, поэтому один и тот же снимок можно перечитывать сколько угодно раз. По умолчанию: -1 (отключено).
max_consume_snapshots — максимальное число снимков, считываемых за одно инкрементальное чтение. Если в источнике накопилось много непрочитанных снимков, этот параметр ограничивает, сколько из них будет считано за один запрос, чтобы контролировать размер пакета. 0 означает отсутствие ограничения. По умолчанию: 0.

Чтение целевого снимка — всегда возвращает дельту снимка 1 независимо от текущего watermark:

SELECT count()
FROM paimon_inc
SETTINGS paimon_target_snapshot_id = 1;

Ограничение числа снимков в пакете — если ожидают обработки три новых снимка, обрабатывайте не более двух за один запрос:

SELECT count()
FROM paimon_inc
SETTINGS max_consume_snapshots = 2;

Из Paimon в MergeTree через refreshable materialized view

Вы можете настроить сквозной конвейер, который будет непрерывно синхронизировать данные из таблицы Paimon в таблицу MergeTree с помощью refreshable materialized view в режиме APPEND. В каждом цикле обновления из Paimon считываются только новые инкрементальные данные и добавляются в целевую таблицу.

Шаг 1 — Создайте исходную таблицу Paimon с включёнными инкрементальным чтением и обновлением метаданных.

В примере ниже используется PaimonLocal. В зависимости от используемого бэкенда хранилища замените движок на PaimonS3, PaimonAzure, PaimonHDFS или алиас Paimon:

SET allow_experimental_paimon_storage_engine = 1;

-- Local storage
CREATE TABLE paimon_mv_source
ENGINE = PaimonLocal('/path/to/paimon/table')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/tables/{uuid}',
    paimon_replica_name = '{replica}',
    paimon_metadata_refresh_interval_sec = 1;

-- S3 storage (Paimon is an alias for PaimonS3)
CREATE TABLE paimon_mv_source
ENGINE = Paimon('http://minio:9000/bucket/path/to/table', 'access_key', 'secret_key')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/tables/{uuid}',
    paimon_replica_name = '{replica}',
    paimon_metadata_refresh_interval_sec = 1;

paimon_metadata_refresh_interval_sec задаёт интервал фонового обновления метаданных в секундах. Если значение больше 0, фоновая задача периодически извлекает из Объектного хранилища последний снимок и schema, чтобы цикл обновления MV мог видеть недавно зафиксированные данные, не дожидаясь, пока запрос инициирует обновление метаданных. Значение по умолчанию — 30. Используйте с осторожностью при работе со множеством таблиц, чтобы избежать чрезмерной нагрузки на Объектное хранилище и операций ввода-вывода Keeper.

Шаг 2 — Создайте целевую таблицу MergeTree (schema клонирована из таблицы Paimon):

CREATE TABLE paimon_mv_dest AS paimon_mv_source
ENGINE = MergeTree()
ORDER BY tuple();

Шаг 3 — Создайте refreshable materialized view:

CREATE MATERIALIZED VIEW paimon_mv
REFRESH EVERY 10 SECOND
APPEND
TO paimon_mv_dest
AS SELECT * FROM paimon_mv_source;

Каждые 10 секунд MV выполняет запрос SELECT * FROM paimon_mv_source, который возвращает только строки, добавленные с момента последнего зафиксированного снимка, и добавляет их в paimon_mv_dest.

Очистка:

SYSTEM STOP VIEW paimon_mv;
DROP VIEW IF EXISTS paimon_mv SYNC;
DROP TABLE IF EXISTS paimon_mv_dest SYNC;
DROP TABLE IF EXISTS paimon_mv_source SYNC;

Примечание

Перед удалением остановите MV, чтобы фоновое обновление не блокировало DDL-операции.

Ограничения

Для инкрементального чтения требуется настроить Keeper (ZooKeeper).
Для инкрементального чтения параметр paimon_keeper_path должен быть задан и быть уникальным для каждой таблицы.
paimon_replica_name должен быть уникальным для каждой реплики в пределах одного пути Keeper.
Инкрементальное чтение использует доставку не более одного раза: зафиксированный снимок продвигается при сборе файлов данных, до того как данные будут фактически прочитаны. Если запрос завершается ошибкой после сбора файлов, пропущенные снимки не будут повторно прочитаны при повторной попытке.
Движок таблицы доступен только для чтения; изменение данных не поддерживается.
Инкрементальное чтение не учитывает удаление исторических данных из источника Paimon. Если данные в вышестоящем Paimon удаляются или обновляются, соответствующие строки, уже записанные в целевую таблицу ClickHouse MergeTree, не будут удалены автоматически. Чтобы очистить устаревшие данные, необходимо вручную выполнить ALTER TABLE ... DELETE для таблицы MergeTree.

Псевдонимы

Движок таблицы Paimon теперь — псевдоним PaimonS3.

Виртуальные столбцы

_path — Путь к файлу. Тип: LowCardinality(String).
_file — Имя файла. Тип: LowCardinality(String).
_size — Размер файла в байтах. Тип: Nullable(UInt64). Если размер файла неизвестен, значение — NULL.
_time — Время последнего изменения файла. Тип: Nullable(DateTime). Если время неизвестно, значение — NULL.
_etag — ETag файла. Тип: LowCardinality(String). Если ETag неизвестен, значение — NULL.

Поддерживаемые типы данных

Тип данных Paimon	Тип данных ClickHouse
BOOLEAN	Int8
TINYINT	Int8
SMALLINT	Int16
INTEGER	Int32
BIGINT	Int64
FLOAT	Float32
DOUBLE	Float64
STRING,VARCHAR,BYTES,VARBINARY	String
DATE	Date
TIME(p),TIME	Time('UTC')
TIMESTAMP(p) WITH LOCAL TIME ZONE	DateTime64
TIMESTAMP(p)	DateTime64('UTC')
CHAR	FixedString(1)
BINARY(n)	FixedString(n)
DECIMAL(P,S)	Decimal(P,S)
ARRAY	Array
MAP	Map

Поддерживаемые партиции

Типы данных, поддерживаемые в ключах партиций Paimon:

CHAR
VARCHAR
BOOLEAN
DECIMAL
TINYINT
SMALLINT
INTEGER
DATE
TIME
TIMESTAMP
TIMESTAMP WITH LOCAL TIME ZONE
BIGINT
FLOAT
DOUBLE

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

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

Пример​

Возможности​

Settings​

Примеры инкрементального чтения​

Настройки на уровне запроса для инкрементального чтения​

Из Paimon в MergeTree через refreshable materialized view​

Ограничения​

Псевдонимы​

Виртуальные столбцы​

Поддерживаемые типы данных​

Поддерживаемые партиции​