iceberg

Proporciona una interfaz de tipo tabla de solo lectura para tablas Apache Iceberg en Amazon S3, Azure, HDFS o almacenadas localmente.

icebergS3(url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method] [,extra_credentials])
icebergS3(named_collection[, option=value [,..]])

icebergAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])
icebergAzure(named_collection[, option=value [,..]])

icebergHDFS(path_to_table, [,format] [,compression_method])
icebergHDFS(named_collection[, option=value [,..]])

icebergLocal(path_to_table, [,format] [,compression_method])
icebergLocal(named_collection[, option=value [,..]])

La descripción de los argumentos coincide con la de los argumentos de las funciones de tabla s3, azureBlobStorage, HDFS y file, respectivamente. format se refiere al formato de los archivos de datos de la tabla Iceberg.

Para icebergS3, se puede usar un parámetro opcional extra_credentials para pasar un role_arn para acceso basado en roles en ClickHouse Cloud. Consulte Secure S3 para ver los pasos de configuración.

Una tabla con la estructura especificada para leer datos de la tabla Iceberg especificada.

SELECT * FROM icebergS3('http://test.s3.amazonaws.com/clickhouse-bucket/test_table', 'test', 'test')

Aquí tienes un ejemplo de cómo configurar una colección con nombre para almacenar la URL y las credenciales:

<clickhouse>
    <named_collections>
        <iceberg_conf>
            <url>http://test.s3.amazonaws.com/clickhouse-bucket/</url>
            <access_key_id>test</access_key_id>
            <secret_access_key>test</secret_access_key>
            <format>auto</format>
            <structure>auto</structure>
        </iceberg_conf>
    </named_collections>
</clickhouse>

SELECT * FROM icebergS3(iceberg_conf, filename = 'test_table')
DESCRIBE icebergS3(iceberg_conf, filename = 'test_table')

Las tablas Iceberg también se pueden usar con varios catálogos de datos, como REST Catalog, AWS Glue Data Catalog y Unity Catalog.

Para usarlos, cree una tabla con el motor IcebergS3 y proporcione la configuración necesaria.

Por ejemplo, al usar REST Catalog con almacenamiento MinIO:

CREATE TABLE `database_name.table_name`
ENGINE = IcebergS3(
  'http://minio:9000/warehouse-rest/table_name/',
  'minio_access_key',
  'minio_secret_key'
)

O bien, con AWS Glue Data Catalog y S3:

CREATE TABLE `my_database.my_table`  
ENGINE = IcebergS3(
  's3://my-data-bucket/warehouse/my_database/my_table/',
  'aws_access_key',
  'aws_secret_key'
)

Por el momento, con la ayuda de CH, puedes leer tablas Iceberg cuyo esquema ha ido cambiando con el tiempo. Actualmente admitimos la lectura de tablas en las que se han añadido o eliminado columnas y se ha modificado su orden. También puedes cambiar una columna en la que se requiere un valor por otra en la que se permite NULL. Además, admitimos la conversión de tipos permitida para tipos simples, concretamente:  

• int -> long
• float -> double
• decimal(P, S) -> decimal(P', S) donde P' > P.

Actualmente, no es posible modificar estructuras anidadas ni los tipos de los elementos dentro de arrays y maps.

ClickHouse admite la poda de particiones en las consultas SELECT de tablas Iceberg, lo que ayuda a optimizar el rendimiento al omitir archivos de datos irrelevantes. Para habilitar la poda de particiones, establece use_iceberg_partition_pruning = 1. Para obtener más información sobre la poda de particiones de Iceberg, consulta https://iceberg.apache.org/spec/#partitioning

ClickHouse admite el viaje en el tiempo en las tablas Iceberg, lo que permite consultar datos históricos con una marca de tiempo o un ID de instantánea específicos.

ClickHouse admite tablas Iceberg con eliminaciones por posición y eliminaciones por igualdad. Las eliminaciones por igualdad se admiten a partir de la v25.8.

No se admite el siguiente método de eliminación:

• Vectores de eliminación (introducidos en v3)

 SELECT * FROM example_table ORDER BY 1 
 SETTINGS iceberg_timestamp_ms = 1714636800000

 SELECT * FROM example_table ORDER BY 1 
 SETTINGS iceberg_snapshot_id = 3547395809148285433

Nota: No puede especificar a la vez los parámetros iceberg_timestamp_ms e iceberg_snapshot_id en la misma consulta.

• Las instantáneas suelen crearse cuando:

• Se escriben datos nuevos en la tabla

• Se realiza algún tipo de compactación de datos

• Los cambios en el esquema normalmente no crean instantáneas - Esto da lugar a comportamientos importantes al usar viaje en el tiempo con tablas que han pasado por una evolución del esquema.

Estos escenarios usan Spark para ilustrar cambios de esquema realizados por un escritor externo de Iceberg.

Considere esta secuencia de operaciones:

 -- Crear una tabla con dos columnas
  CREATE TABLE IF NOT EXISTS spark_catalog.db.time_travel_example (
  order_number bigint, 
  product_code string
  ) 
  USING iceberg 
  OPTIONS ('format-version'='2')

- - Insertar datos en la tabla
  INSERT INTO spark_catalog.db.time_travel_example VALUES 
    (1, 'Mars')

  ts1 = now() // Un fragmento de pseudocódigo

- - Modificar la tabla para agregar una nueva columna
  ALTER TABLE spark_catalog.db.time_travel_example ADD COLUMN (price double)
 
  ts2 = now()

- - Insertar datos en la tabla
  INSERT INTO spark_catalog.db.time_travel_example VALUES (2, 'Venus', 100)

   ts3 = now()

- - Consultar la tabla en cada marca de tiempo
  SELECT * FROM spark_catalog.db.time_travel_example TIMESTAMP AS OF ts1;

+------------+------------+
|order_number|product_code|
+------------+------------+
|           1|        Mars|
+------------+------------+
  SELECT * FROM spark_catalog.db.time_travel_example TIMESTAMP AS OF ts2;

+------------+------------+
|order_number|product_code|
+------------+------------+
|           1|        Mars|
+------------+------------+

  SELECT * FROM spark_catalog.db.time_travel_example TIMESTAMP AS OF ts3;

+------------+------------+-----+
|order_number|product_code|price|
+------------+------------+-----+
|           1|        Mars| NULL|
|           2|       Venus|100.0|
+------------+------------+-----+

Resultados de la consulta en diferentes marcas de tiempo:

• En ts1 & ts2: Solo se muestran las dos columnas originales
• En ts3: Se muestran las tres columnas, con NULL en el precio de la primera fila

Una consulta de viaje en el tiempo realizada en el momento actual podría mostrar un esquema distinto del de la tabla actual:

-- Crear una tabla
  CREATE TABLE IF NOT EXISTS spark_catalog.db.time_travel_example_2 (
  order_number bigint, 
  product_code string
  ) 
  USING iceberg 
  OPTIONS ('format-version'='2')

-- Insertar datos iniciales en la tabla
  INSERT INTO spark_catalog.db.time_travel_example_2 VALUES (2, 'Venus');

-- Modificar la tabla para añadir una nueva columna
  ALTER TABLE spark_catalog.db.time_travel_example_2 ADD COLUMN (price double);

  ts = now();

-- Consultar la tabla en el momento actual usando sintaxis de marca de tiempo

  SELECT * FROM spark_catalog.db.time_travel_example_2 TIMESTAMP AS OF ts;

    +------------+------------+
    |order_number|product_code|
    +------------+------------+
    |           2|       Venus|
    +------------+------------+

-- Consultar la tabla en el momento actual
  SELECT * FROM spark_catalog.db.time_travel_example_2;
    +------------+------------+-----+
    |order_number|product_code|price|
    +------------+------------+-----+
    |           2|       Venus| NULL|
    +------------+------------+-----+

Esto ocurre porque ALTER TABLE no crea una nueva instantánea, sino que, para la tabla actual, Spark toma el valor de schema_id del archivo de metadatos más reciente, no de una instantánea.

La segunda es que, al usar viaje en el tiempo, no puedes obtener el estado de la tabla antes de que se escribiera ningún dato en ella:

-- Create a table
  CREATE TABLE IF NOT EXISTS spark_catalog.db.time_travel_example_3 (
  order_number bigint, 
  product_code string
  ) 
  USING iceberg 
  OPTIONS ('format-version'='2');

  ts = now();

-- Query the table at a specific timestamp
  SELECT * FROM spark_catalog.db.time_travel_example_3 TIMESTAMP AS OF ts; -- Finises with error: Cannot find a snapshot older than ts.

En ClickHouse, el comportamiento es consistente con el de Spark. Puedes sustituir mentalmente las consultas Select de Spark por las de ClickHouse y funcionará igual.

Al usar la función de tabla iceberg en ClickHouse, el sistema necesita localizar el archivo metadata.json correcto que describe la estructura de la tabla Iceberg. A continuación, se explica cómo funciona este proceso de resolución:

1. Especificación directa de la ruta: *Si establece iceberg_metadata_file_path, el sistema usará esta ruta exacta combinándola con la ruta del directorio de la tabla Iceberg.

• Cuando se proporciona este ajuste, se ignoran todos los demás ajustes de resolución.

2. Coincidencia del UUID de la tabla: *Si se especifica iceberg_metadata_table_uuid, el sistema: *Buscará solo archivos .metadata.json en el directorio metadata *Filtrará los archivos que contengan un campo table-uuid que coincida con el UUID especificado (sin distinguir entre mayúsculas y minúsculas)

3. Búsqueda predeterminada: *Si no se proporciona ninguno de los ajustes anteriores, todos los archivos .metadata.json del directorio metadata pasan a ser candidatos

Después de identificar los archivos candidatos mediante las reglas anteriores, el sistema determina cuál es el más reciente:

• Si iceberg_recent_metadata_file_by_last_updated_ms_field está habilitado:

• Se selecciona el archivo con el valor last-updated-ms más alto

• En caso contrario:

• Se selecciona el archivo con el número de versión más alto

• (La versión aparece como V en nombres de archivo con formato V.metadata.json o V-uuid.metadata.json)

Nota: Todas las configuraciones mencionadas son configuraciones de la función de tabla (no configuraciones globales ni a nivel de consulta) y deben especificarse como se muestra a continuación:

SELECT * FROM iceberg('s3://bucket/path/to/iceberg_table', 
    SETTINGS iceberg_metadata_table_uuid = 'a90eed4c-f74b-4e5b-b630-096fb9d09021');

Nota: Aunque los catálogos de Iceberg suelen encargarse de la resolución de metadatos, la función de tabla iceberg de ClickHouse interpreta directamente los archivos almacenados en S3 como tablas de Iceberg, por lo que es importante entender estas reglas de resolución.

El motor de tabla y la función de tabla Iceberg admiten una caché de metadatos para almacenar la información de los archivos de manifiesto, la lista de manifiestos y el JSON de metadatos. La caché se guarda en memoria. Esta función está controlada por la configuración use_iceberg_metadata_files_cache, que está habilitada de forma predeterminada.

La función de tabla iceberg ahora es un alias de icebergS3.

• _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 — Hora de la última modificación del archivo. Tipo: Nullable(DateTime). Si se desconoce la hora, el valor es NULL.
• _etag — El etag del archivo. Tipo: LowCardinality(String). Si se desconoce el etag, el valor es NULL.

A partir de la versión 25.7, ClickHouse admite modificaciones en tablas Iceberg en backends de almacenamiento que permiten escritura.

Antes de modificar o realizar tareas de mantenimiento en una tabla Iceberg, habilite la configuración allow_insert_into_iceberg. Algunas operaciones requieren configuraciones adicionales, como se indica a continuación:

SET allow_insert_into_iceberg = 1;

Para crear una nueva tabla Iceberg standalone en un backend con permisos de escritura, usa un motor de tabla Iceberg y especifica el esquema de forma explícita. Las operaciones de escritura admiten todos los formatos de datos de la especificación de Iceberg, como Parquet, Avro y ORC.

CREATE TABLE iceberg_writes_example
(
    x Nullable(String),
    y Nullable(Int32)
)
ENGINE = IcebergLocal('/home/scanhex12/iceberg_example/')

Nota: Para crear un archivo de sugerencia de versión, habilite la configuración iceberg_use_version_hint. Si desea comprimir el archivo metadata.json, especifique el nombre del códec en la configuración iceberg_metadata_compression_method.

Después de crear una tabla nueva, puede insertar datos con la sintaxis habitual de ClickHouse.

INSERT INTO iceberg_writes_example VALUES ('Pavel', 777), ('Ivanov', 993);

SELECT *
FROM iceberg_writes_example
FORMAT VERTICAL;

Row 1:
─

ClickHouse también admite eliminar filas adicionales en el formato merge-on-read. Esta consulta creará un nuevo snapshot con archivos de eliminación por posición.

ALTER TABLE iceberg_writes_example DELETE WHERE x != 'Ivanov';

SELECT *
FROM iceberg_writes_example
FORMAT VERTICAL;

Row 1:
─

ClickHouse le permite agregar, eliminar, modificar o renombrar columnas con tipos simples (que no sean Tuple, Array ni Map).

ALTER TABLE iceberg_writes_example MODIFY COLUMN y Nullable(Int64);
SHOW CREATE TABLE iceberg_writes_example;

   ┌

ClickHouse admite la compactación de tablas Iceberg. Actualmente, puede fusionar archivos de eliminación por posición en archivos de datos mientras actualiza los metadatos. Los ID y las marcas de tiempo de instantáneas anteriores no cambian, por lo que la función de viaje en el tiempo puede seguir usándose con los mismos valores.

Cómo usarlo:

SET allow_experimental_iceberg_compaction = 1

OPTIMIZE TABLE iceberg_writes_example;

SELECT *
FROM iceberg_writes_example
FORMAT VERTICAL;

Row 1:
─

Las tablas Iceberg acumulan instantáneas con cada operación INSERT, DELETE o UPDATE. Con el tiempo, esto puede dar lugar a una gran cantidad de instantáneas y archivos de datos asociados. El comando expire_snapshots elimina las instantáneas antiguas y limpia los archivos de datos que ya no están referenciados por ninguna instantánea conservada.

Sintaxis:

ALTER TABLE iceberg_table EXECUTE expire_snapshots(
    ['timestamp']
    [, expire_before = 'timestamp']
    [, retention_period = '3d']
    [, retain_last = 100]
    [, snapshot_ids = [1, 2, 3, 4]]
    [, dry_run = 1]
);

De forma predeterminada, qué instantáneas se conservan lo determina la política de retención (las propiedades de la tabla min-snapshots-to-keep, max-snapshot-age-ms y las anulaciones por referencia). Cuando se especifica snapshot_ids, se omite la política de retención y solo las instantáneas indicadas se consideran para su expiración.

Argumentos:

• 'timestamp' (posicional) o expire_before = 'timestamp' — una cadena de fecha y hora (p. ej., '2024-06-01 00:00:00') interpretada en la zona horaria del servidor. Actúa como mecanismo de seguridad: las instantáneas cuyo timestamp-ms sea igual o posterior a este valor quedan protegidas frente a la expiración, incluso si la política de retención normalmente las expiraría. Puede combinarse con snapshot_ids; en ese caso, las instantáneas indicadas con esa marca de tiempo o una posterior no expiran.
• retention_period = '<duration>' — anula history.expire.max-snapshot-age-ms a nivel de tabla solo para esta invocación. Las instantáneas anteriores a esta duración (medida desde ahora) pasan a ser candidatas para la expiración. El valor es una cadena de duración compuesta por uno o más pares {number}{unit} concatenados. Unidades admitidas: y (365 días), w (7 días), d (24 horas), h (60 minutos), m (60 segundos), s (1 segundo), ms (1 milisegundo). Las unidades pueden combinarse, p. ej., '3d', '12h', '1d12h30m', '500ms'.
• retain_last = N — anula history.expire.min-snapshots-to-keep a nivel de tabla solo para esta invocación. Siempre se conservan al menos N instantáneas, independientemente de su antigüedad.
• snapshot_ids = [id1, id2, ...] — expira exactamente los ID de instantánea indicados (excepto las instantáneas a las que hace referencia la instantánea actual, las ramas o las etiquetas). Este modo omite por completo la política de retención y no puede combinarse con retention_period ni con retain_last.
• dry_run = 1 — calcula qué expiraría y devuelve métricas sin escribir metadatos nuevos ni eliminar archivos.

Ejemplo:

SET allow_insert_into_iceberg = 1;

-- Crear algunas instantáneas insertando datos
INSERT INTO iceberg_table VALUES (1);
INSERT INTO iceberg_table VALUES (2);
INSERT INTO iceberg_table VALUES (3);

-- Expirar usando solo la política de retención
ALTER TABLE iceberg_table EXECUTE expire_snapshots();

-- Expirar con fusible de seguridad: proteger las instantáneas más recientes que la marca de tiempo (sintaxis posicional)
ALTER TABLE iceberg_table EXECUTE expire_snapshots('2025-01-01 00:00:00');

-- Lo mismo usando la forma de argumento con nombre
ALTER TABLE iceberg_table EXECUTE expire_snapshots(expire_before = '2025-01-01 00:00:00');

-- Sobreescribir los parámetros de retención para una ejecución
ALTER TABLE iceberg_table EXECUTE expire_snapshots(retention_period = '3d', retain_last = 10);

-- Expirar instantáneas explícitas
ALTER TABLE iceberg_table EXECUTE expire_snapshots(snapshot_ids = [101, 102, 103]);

-- Vista previa en modo simulado (sin actualizaciones de metadatos ni eliminación de archivos)
ALTER TABLE iceberg_table EXECUTE expire_snapshots(retention_period = '1d', dry_run = 1);

Salida:

El comando devuelve una tabla con dos columnas (metric_name String, metric_value Int64) que contiene una fila por cada métrica. Los nombres de las métricas siguen la especificación de Iceberg:

El comando realiza los siguientes pasos:

1. Evalúa la política de retención (consulte a continuación) para determinar qué instantáneas deben conservarse
2. Si se proporcionó un argumento de marca de tiempo, también protege todas las instantáneas en esa marca de tiempo o posteriores
3. Expira las instantáneas que no se conservan según la política ni están protegidas por la salvaguarda de marca de tiempo
4. Calcula qué archivos están asociados exclusivamente a instantáneas expiradas
5. En modo normal: genera metadatos nuevos sin las instantáneas expiradas
6. En modo normal: elimina físicamente las listas de manifiestos, los archivos de manifiesto y los archivos de datos inaccesibles
7. En el modo dry_run = 1: omite los pasos 5 y 6 y solo devuelve las métricas calculadas

El comando expire_snapshots respeta la política de retención de instantáneas de Iceberg. La retención se configura mediante propiedades de tabla de Iceberg y anulaciones por referencia:

Cada referencia de instantánea (refs en los metadatos de Iceberg) puede sobrescribir estos valores con campos por referencia: min-snapshots-to-keep, max-snapshot-age-ms y max-ref-age-ms.

Evaluación de la retención:

• Para cada rama (incluida main): se recorre la cadena de ancestros a partir de la cabecera de la rama. Las instantáneas se conservan mientras se cumpla cualquiera de estas condiciones:
  • La instantánea es una de las primeras min-snapshots-to-keep de la cadena
  • La antigüedad de la instantánea está dentro de max-snapshot-age-ms (es decir, now - timestamp-ms <= max-snapshot-age-ms)
• Para las etiquetas: la instantánea etiquetada se conserva, salvo que la etiqueta haya superado su max-ref-age-ms, en cuyo caso se elimina la referencia de la etiqueta
• Las referencias distintas de main cuya antigüedad supera max-ref-age-ms se eliminan por completo (la rama main nunca se elimina)
• Las referencias colgantes que apuntan a instantáneas inexistentes se eliminan con una advertencia
• La instantánea actual siempre se conserva, independientemente de la configuración de retención

Privilegios requeridos:

Se requiere el privilegio ALTER TABLE EXECUTE, que es un privilegio secundario de ALTER TABLE en la jerarquía de control de acceso de ClickHouse. Puede concederlo específicamente o a través del privilegio principal:

-- Otorgar solo el permiso EXECUTE
GRANT ALTER TABLE EXECUTE ON my_iceberg_table TO my_user;

-- O conceder todos los permisos de ALTER TABLE (incluye ALTER TABLE EXECUTE)
GRANT ALTER TABLE ON my_iceberg_table TO my_user;

Los archivos huérfanos son archivos almacenados a los que no hace referencia ninguna instantánea en los metadatos de la tabla Iceberg. Se acumulan por escrituras fallidas, limpiezas parciales tras la compactación y operaciones interrumpidas, lo que provoca un crecimiento ilimitado del almacenamiento. El comando remove_orphan_files identifica y elimina estos archivos huérfanos.

Sintaxis:

-- Forma posicional: argumento older_than sin nombre
ALTER TABLE iceberg_table EXECUTE remove_orphan_files('timestamp')

-- Forma con nombre
ALTER TABLE iceberg_table EXECUTE remove_orphan_files(
    older_than = 'timestamp',
    location = 'path',
    dry_run = 0|1
)

-- Sin argumentos: usar todos los valores predeterminados (older_than = hace 3 días)
ALTER TABLE iceberg_table EXECUTE remove_orphan_files()

Parámetros:

Ejemplos:

-- Eliminar archivos huérfanos más antiguos que una marca de tiempo específica
ALTER TABLE iceberg_table EXECUTE remove_orphan_files('2026-03-01 00:00:00');

-- Dry run: previsualizar qué archivos se eliminarían
ALTER TABLE iceberg_table EXECUTE remove_orphan_files(dry_run = 1);

-- Analizar solo el directorio de datos
ALTER TABLE iceberg_table EXECUTE remove_orphan_files(
    older_than = '2026-03-01 00:00:00',
    location = 'data/'
);

-- Combinar older_than posicional con argumentos con nombre
ALTER TABLE iceberg_table EXECUTE remove_orphan_files(
    '2026-03-01 00:00:00',
    dry_run = 1
);

Salida:

El comando devuelve una tabla con las columnas metric_name y metric_value, que muestran el número de archivos eliminados (o que se eliminarían en el modo dry_run) por categoría. Las categorías de archivos se clasifican mediante heurísticas basadas en convenciones de nomenclatura; los archivos que no coinciden con ningún patrón específico se asignan por defecto a deleted_data_files_count:

Configuración:

• motor de Iceberg
• función de tabla de clúster de Iceberg