Motor de tabla Paimon

Este motor proporciona una integración de solo lectura con tablas existentes de Apache Paimon en Amazon S3, Azure, HDFS y en almacenamiento local. Admite lecturas de instantáneas, lecturas incrementales y poda básica de particiones que proporciona el motor.

Tenga en cuenta que la tabla Paimon ya debe existir en el almacenamiento; este comando no acepta parámetros DDL para crear una tabla nueva. La creación de tablas Paimon* está condicionada por allow_experimental_paimon_storage_engine (desactivado de forma predeterminada), así que actívelo antes de ejecutar CREATE TABLE.

SET allow_experimental_paimon_storage_engine = 1;

CREATE TABLE paimon_table_s3
    ENGINE = PaimonS3(url, [, access_key_id, secret_access_key] [,format] [,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])

La descripción de los argumentos coincide con la de los argumentos de los motores S3, AzureBlobStorage, HDFS y File, respectivamente. format corresponde al formato de los archivos de datos de la tabla Paimon.

Los parámetros del motor se pueden especificar mediante colecciones con nombre

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

Uso de colecciones con nombre:

<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')

• Lecturas de instantáneas a partir de la instantánea más reciente de la tabla.
• Lecturas incrementales basadas en el ID de la instantánea confirmada cuando están habilitadas.
• Poda de particiones cuando use_paimon_partition_pruning está habilitado.
• Actualización opcional de metadatos en segundo plano cuando se configura.
• UUID de tabla estable al usar bases de datos Atomic/Replicated, lo que permite usar macros {uuid} en las rutas de Keeper.

Este motor usa la misma configuración que los motores correspondientes de almacenamiento de objetos y añade ajustes específicos de Paimon:

• allow_experimental_paimon_storage_engine — habilita la creación de los motores de tabla Paimon, PaimonS3, PaimonAzure, PaimonHDFS y PaimonLocal. Valor predeterminado: 0 (deshabilitado).
• use_paimon_metadata_files_cache — habilita la caché de archivos de metadatos de Paimon (almacena en caché listas de manifiestos y manifiestos deserializados). Establézcalo en 1 para habilitarlo y en 0 para deshabilitarlo. Valor predeterminado: 0. La forma en que esta configuración surte efecto difiere entre las funciones de tabla y los motores de tabla persistentes; consulte la nota a continuación.
• paimon_incremental_read — habilita el modo de lectura incremental.
• paimon_metadata_refresh_interval_sec — intervalo, en segundos, de actualización de metadatos en segundo plano. Cuando se establece en un valor superior a 0, una tarea en segundo plano obtiene periódicamente la instantánea y el esquema más recientes desde el almacenamiento de objetos. Valor predeterminado: 30.
• paimon_keeper_path — ruta de Keeper para el estado de lectura incremental. Debe configurarse y ser única para cada tabla; admite macros como {database}, {table}, {uuid}.
• paimon_replica_name — nombre de la réplica para el estado de lectura incremental. Debe configurarse y ser único para cada réplica; admite macros como {replica}.

Ejemplo (habilitar el motor experimental de Paimon y la caché de archivos de metadatos):

SET allow_experimental_paimon_storage_engine = 1;
SET use_paimon_metadata_files_cache = 1;

CREATE TABLE paimon_cached
ENGINE = PaimonS3(paimon_conf, filename = 'paimon_all_types');

Lectura incremental con el estado de 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}';

La siguiente configuración es a nivel de consulta (se pasa mediante SELECT ... SETTINGS, no en CREATE TABLE). Controla el comportamiento de las lecturas incrementales en cada consulta:

• paimon_target_snapshot_id — lee solo el delta de la instantánea especificada. El watermark confirmado en Keeper no avanza, por lo que la misma instantánea puede volver a leerse cualquier número de veces. Valor predeterminado: -1 (deshabilitado).
• max_consume_snapshots — número máximo de instantáneas que se pueden consumir en una sola lectura incremental. Cuando el origen ha acumulado muchas instantáneas sin leer, esto limita cuántas se consumen por consulta para controlar el tamaño del lote. 0 significa sin límite. Valor predeterminado: 0.

Lectura de una instantánea específica — siempre devuelve el delta de la instantánea 1, independientemente del watermark actual:

SELECT count()
FROM paimon_inc
SETTINGS paimon_target_snapshot_id = 1;

Limitar las instantáneas por lote — si hay tres instantáneas nuevas pendientes, consuma como máximo dos por consulta:

SELECT count()
FROM paimon_inc
SETTINGS max_consume_snapshots = 2;

Puede crear un pipeline de extremo a extremo que sincronice continuamente datos de una tabla Paimon a una tabla MergeTree mediante una vista materializada actualizable en modo APPEND. Cada ciclo de actualización lee solo los datos incrementales nuevos de Paimon y los añade a la tabla de destino.

Paso 1 — Cree la tabla de origen de Paimon con la lectura incremental y la actualización de metadatos habilitados.

En el ejemplo siguiente se usa PaimonLocal. Sustituya el motor por PaimonS3, PaimonAzure, PaimonHDFS o el motor Paimon con detección automática, según corresponda para su backend de almacenamiento:

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 (the `Paimon` engine defaults to the S3 implementation when no `disk` is specified)
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 establece el intervalo, en segundos, de actualización de metadatos en segundo plano. Cuando es mayor que 0, una tarea en segundo plano obtiene periódicamente la instantánea y el esquema más recientes del almacenamiento de objetos, para que el ciclo de actualización de la MV pueda ver los datos recién confirmados sin esperar a que una consulta active la actualización de metadatos. El valor predeterminado es 30. Úselo con cautela en muchas tablas para evitar un exceso de E/S en el almacenamiento de objetos y en Keeper.

Paso 2 — Cree la tabla de destino MergeTree (con el esquema clonado de la tabla Paimon):

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

Paso 3 — Crear la vista materializada actualizable:

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

Cada 10 segundos, la MV ejecuta un SELECT * FROM paimon_mv_source, que devuelve solo las filas añadidas desde la última instantánea confirmada y las agrega a paimon_mv_dest.

Limpieza:

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;

• La lectura incremental requiere que Keeper (ZooKeeper) esté configurado.
• La lectura incremental requiere que paimon_keeper_path esté configurado y sea único para cada tabla.
• paimon_replica_name debe ser único para cada réplica dentro de la misma ruta de Keeper.
• La lectura incremental usa entrega como máximo una vez: la instantánea confirmada avanza cuando se recopilan los archivos de datos, antes de que los datos se consuman realmente. Si la consulta falla después de la recopilación de archivos, las instantáneas omitidas no se volverán a leer en un reintento.
• El motor de tabla es de solo lectura; no se admite la modificación de datos.
• La lectura incremental no gestiona las eliminaciones de datos históricos del origen Paimon. Si los datos upstream de Paimon se eliminan o actualizan, las filas correspondientes ya escritas en una tabla de destino MergeTree de ClickHouse no se eliminarán automáticamente. Debe ejecutar manualmente ALTER TABLE ... DELETE en la tabla MergeTree para limpiar los datos obsoletos.
• Si la tabla Paimon subyacente se elimina y se vuelve a crear en la misma ruta de almacenamiento de objetos (por ejemplo, mediante Flink o Spark), debe ejecutar DROP y volver a ejecutar CREATE en la tabla de ClickHouse correspondiente. ClickHouse detecta la recreación comparando la marca de tiempo de creación de schema-0 y genera un error; la tabla de ClickHouse obsoleta no puede usarse hasta que se vuelva a crear.

El motor de tabla Paimon detecta automáticamente el backend de almacenamiento según la configuración de disk y selecciona PaimonS3, PaimonAzure o PaimonLocal según corresponda. Si no se especifica ningún disk, usa de forma predeterminada la implementación PaimonS3.

• _path — Ruta del archivo. Tipo: LowCardinality(String).
• _file — Nombre del archivo. Tipo: LowCardinality(String).
• _size — Tamaño del archivo en bytes. Tipo: Nullable(UInt64). Si se desconoce el tamaño del archivo, el valor es NULL.
• _time — Fecha y hora de la última modificación del archivo. Tipo: Nullable(DateTime). Si se desconoce la fecha y hora, el valor es NULL.
• _etag — El etag del archivo. Tipo: LowCardinality(String). Si se desconoce el etag, el valor es NULL.

Tipos de datos compatibles en las claves de partición de Paimon:

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