iceberg

Fornece uma interface do tipo tabela para tabelas Apache Iceberg no Amazon S3, Azure, HDFS ou armazenadas 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 [,..]])

A descrição dos argumentos é a mesma que a dos argumentos nas funções de tabela s3, azureBlobStorage, HDFS e file, respectivamente. format representa o formato dos arquivos de dados na tabela Iceberg.

Para icebergS3, é possível usar um parâmetro opcional extra_credentials para passar um role_arn para controle de acesso baseado em função no ClickHouse Cloud. Consulte Secure S3 para ver as etapas de configuração.

Uma tabela com a estrutura especificada para ler dados da tabela Iceberg especificada.

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

Veja um exemplo de configuração de uma coleção nomeada para armazenar a URL e as credenciais:

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

As tabelas Iceberg também podem ser usadas com vários catálogos de dados, como o REST Catalog, o AWS Glue Data Catalog e o Unity Catalog.

Para usá-los, crie uma tabela com o engine IcebergS3 e forneça as configurações necessárias.

Por exemplo, usando o REST Catalog com armazenamento MinIO:

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

Ou, usando o AWS Glue Data Catalog com S3:

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

Atualmente, com o CH, é possível ler tabelas Iceberg cujo esquema mudou ao longo do tempo. No momento, oferecemos suporte à leitura de tabelas em que colunas foram adicionadas e removidas, e cuja ordem foi alterada. Também é possível alterar uma coluna em que um valor é obrigatório para outra em que NULL é permitido. Além disso, oferecemos suporte a conversões de tipo permitidas para tipos simples, a saber:  

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

Atualmente, não é possível alterar estruturas aninhadas nem os tipos dos elementos dentro de arrays e maps.

O ClickHouse oferece suporte à poda de partições durante consultas SELECT em tabelas Iceberg, o que ajuda a otimizar o desempenho das consultas ao ignorar arquivos de dados irrelevantes. Para ativar a poda de partições, defina use_iceberg_partition_pruning = 1. Para mais informações sobre partition pruning no Iceberg, acesse https://iceberg.apache.org/spec/#partitioning

O ClickHouse oferece suporte ao recurso de viagem no tempo em tabelas Iceberg, permitindo consultar dados históricos com um timestamp específico ou um ID de snapshot.

O ClickHouse oferece suporte a tabelas Iceberg com exclusões por posição e exclusões por igualdade. As exclusões por igualdade são suportadas a partir da v25.8.

O seguinte método de exclusão não é suportado:

• Vetores de exclusão (introduzidos na 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

Observação: não é possível especificar os parâmetros iceberg_timestamp_ms e iceberg_snapshot_id na mesma consulta.

• Snapshots normalmente são criados quando:

• Novos dados são gravados na tabela

• Algum tipo de compactação de dados é executado

• Alterações de esquema normalmente não criam snapshots - Isso leva a comportamentos importantes ao usar viagem no tempo com tabelas que passaram por evolução de esquema.

Estes cenários usam Spark para ilustrar alterações de esquema feitas por uma instância externa de gravação do Iceberg.

Considere esta sequência de operações:

 -- Criar uma tabela com duas colunas
  CREATE TABLE IF NOT EXISTS spark_catalog.db.time_travel_example (
  order_number bigint, 
  product_code string
  ) 
  USING iceberg 
  OPTIONS ('format-version'='2')

- - Inserir dados na tabela
  INSERT INTO spark_catalog.db.time_travel_example VALUES 
    (1, 'Mars')

  ts1 = now() // Um trecho de pseudocódigo

- - Alterar a tabela para adicionar uma nova coluna
  ALTER TABLE spark_catalog.db.time_travel_example ADD COLUMN (price double)
 
  ts2 = now()

- - Inserir dados na tabela
  INSERT INTO spark_catalog.db.time_travel_example VALUES (2, 'Venus', 100)

   ts3 = now()

- - Consultar a tabela em cada timestamp
  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 da consulta em diferentes timestamps:

• Em ts1 & ts2: aparecem apenas as duas colunas originais
• Em ts3: aparecem as três colunas, com NULL no preço da primeira linha

Uma consulta de viagem no tempo no momento atual pode mostrar um esquema diferente do da tabela atual:

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

-- Inserir dados iniciais na tabela
  INSERT INTO spark_catalog.db.time_travel_example_2 VALUES (2, 'Venus');

-- Alterar a tabela para adicionar uma nova coluna
  ALTER TABLE spark_catalog.db.time_travel_example_2 ADD COLUMN (price double);

  ts = now();

-- Consultar a tabela no momento atual usando sintaxe de timestamp

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

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

-- Consultar a tabela no momento atual
  SELECT * FROM spark_catalog.db.time_travel_example_2;
    +------------+------------+-----+
    |order_number|product_code|price|
    +------------+------------+-----+
    |           2|       Venus| NULL|
    +------------+------------+-----+

Isso acontece porque ALTER TABLE não cria um novo snapshot; para a tabela atual, o Spark obtém o valor de schema_id do arquivo de metadados mais recente, e não de um snapshot.

A segunda é que, ao usar viagem no tempo, você não consegue obter o estado da tabela antes de qualquer dado ter sido gravado nela:

-- 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.

No ClickHouse, o comportamento é consistente com o do Spark. Você pode imaginar as consultas Select do Spark substituídas por consultas Select do ClickHouse, e isso funcionará da mesma forma.

Ao usar a função de tabela iceberg no ClickHouse, o sistema precisa localizar o arquivo metadata.json correto que descreve a estrutura da tabela Iceberg. Veja como esse processo funciona:

1. Especificação direta do caminho: *Se você definir iceberg_metadata_file_path, o sistema usará exatamente esse caminho, combinando-o com o caminho do diretório da tabela Iceberg.

• Quando essa configuração é fornecida, todas as outras configurações de resolução são ignoradas.

2. Correspondência do UUID da tabela: *Se iceberg_metadata_table_uuid for especificado, o sistema irá: *Considerar apenas os arquivos .metadata.json no diretório metadata *Filtrar os arquivos que contêm um campo table-uuid correspondente ao UUID especificado (sem diferenciar maiúsculas de minúsculas)

3. Busca padrão: *Se nenhuma das configurações acima for fornecida, todos os arquivos .metadata.json no diretório metadata passam a ser candidatos

Após identificar os arquivos candidatos usando as regras acima, o sistema determina qual deles é o mais recente:

• Se iceberg_recent_metadata_file_by_last_updated_ms_field estiver habilitado:

• O arquivo com o maior valor de last-updated-ms é selecionado

• Caso contrário:

• O arquivo com o número de versão mais alto é selecionado

• (A versão aparece como V em nomes de arquivo no formato V.metadata.json ou V-uuid.metadata.json)

Observação: Todas as configurações mencionadas são configurações de função de tabela (não configurações globais nem configurações no nível da consulta) e devem ser especificadas como mostrado abaixo:

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

Observação: Embora os catálogos Iceberg normalmente cuidem da resolução de metadados, a função de tabela iceberg no ClickHouse interpreta diretamente arquivos armazenados no S3 como tabelas Iceberg, por isso é importante entender essas regras de resolução.

O motor de tabela Iceberg e a função de tabela oferecem suporte a um cache de metadados que armazena informações dos arquivos de manifesto, da lista de manifestos e do JSON de metadados. O cache é armazenado na memória. Esse recurso é controlado pela configuração use_iceberg_metadata_files_cache, que vem habilitada por padrão.

A função de tabela iceberg agora é um alias para icebergS3.

• _path — Caminho do arquivo. Tipo: LowCardinality(String).
• _file — Nome do arquivo. Tipo: LowCardinality(String).
• _size — Tamanho do arquivo em bytes. Tipo: Nullable(UInt64). Se o tamanho do arquivo for desconhecido, o valor será NULL.
• _time — Data e hora da última modificação do arquivo. Tipo: Nullable(DateTime). Se esse horário for desconhecido, o valor será NULL.
• _etag — O etag do arquivo. Tipo: LowCardinality(String). Se o etag for desconhecido, o valor será NULL.

A partir da versão 25.7, o ClickHouse oferece suporte a modificações em tabelas Iceberg em backends de armazenamento com suporte a gravação.

Antes de modificar ou manter uma tabela Iceberg, ative a configuração allow_insert_into_iceberg. Algumas operações exigem configurações adicionais, conforme observado abaixo:

SET allow_insert_into_iceberg = 1;

Para criar uma nova tabela Iceberg standalone em um backend gravável, use um motor de tabela Iceberg e especifique o esquema explicitamente. As operações de escrita oferecem suporte a todos os formatos de dados da especificação Iceberg, como Parquet, Avro e ORC.

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

Observação: para criar um arquivo indicador de versão, ative a configuração iceberg_use_version_hint. Se quiser comprimir o arquivo metadata.json, especifique o nome do codec na configuração iceberg_metadata_compression_method.

Após criar uma nova tabela, você pode inserir dados usando a sintaxe padrão do ClickHouse.

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

SELECT *
FROM iceberg_writes_example
FORMAT VERTICAL;

Row 1:
─

A exclusão de linhas excedentes no formato merge-on-read também é compatível com o ClickHouse. Esta consulta criará um novo snapshot com arquivos de exclusão por posição.

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

SELECT *
FROM iceberg_writes_example
FORMAT VERTICAL;

Row 1:
─

O ClickHouse permite adicionar, remover, modificar ou renomear colunas com tipos simples (que não sejam Tuple, Array nem Map).

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

   ┌

O ClickHouse oferece suporte à compactação de tabelas Iceberg. Atualmente, ele pode mesclar arquivos de exclusão por posição aos arquivos de dados enquanto atualiza os metadados. Os IDs de snapshots anteriores e seus timestamps permanecem inalterados, portanto o recurso de viagem no tempo ainda pode ser usado com os mesmos valores.

Como usá-lo:

SET allow_experimental_iceberg_compaction = 1

OPTIMIZE TABLE iceberg_writes_example;

SELECT *
FROM iceberg_writes_example
FORMAT VERTICAL;

Row 1:
─

As tabelas Iceberg acumulam snapshots a cada operação INSERT, DELETE ou UPDATE. Com o tempo, isso pode resultar em um grande número de snapshots e arquivos de dados associados. O comando expire_snapshots remove snapshots antigos e limpa os arquivos de dados que não são mais referenciados por nenhum snapshot retido.

Sintaxe:

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]
);

Por padrão, quais snapshots devem ser mantidos são definidos pela política de retenção (propriedades da tabela min-snapshots-to-keep, max-snapshot-age-ms e substituições por ref). Quando snapshot_ids é especificado, a política de retenção é ignorada e apenas os snapshots listados são considerados para expiração.

Argumentos:

• 'timestamp' (posicional) ou expire_before = 'timestamp' — uma string de data e hora (por exemplo, '2024-06-01 00:00:00') interpretada no fuso horário do servidor. Funciona como uma trava de segurança: snapshots cujo timestamp-ms seja igual ou posterior a esse valor ficam protegidos contra expiração, mesmo que a política de retenção, de outra forma, os expirasse. Pode ser combinado com snapshot_ids; nesse caso, snapshots listados com timestamp igual ou mais recente que esse valor não expiram.
• retention_period = '<duration>' — substitui o history.expire.max-snapshot-age-ms no nível da tabela apenas nesta invocação. Snapshots mais antigos do que essa duração (medida a partir de agora) tornam-se candidatos à expiração. O valor é uma string de duração composta por um ou mais pares {number}{unit} concatenados. Unidades aceitas: y (365 dias), w (7 dias), d (24 horas), h (60 minutos), m (60 segundos), s (1 segundo), ms (1 milissegundo). As unidades podem ser combinadas, por exemplo: '3d', '12h', '1d12h30m', '500ms'.
• retain_last = N — substitui o history.expire.min-snapshots-to-keep no nível da tabela apenas nesta invocação. Pelo menos N snapshots são sempre mantidos, independentemente da idade.
• snapshot_ids = [id1, id2, ...] — expira exatamente os IDs de snapshot listados (exceto snapshots referenciados pelo snapshot atual, branches ou tags). Esse modo ignora completamente a política de retenção e não pode ser combinado com retention_period nem com retain_last.
• dry_run = 1 — calcula o que seria expirado e retorna métricas sem gravar novos metadados nem excluir arquivos.

Exemplo:

SET allow_insert_into_iceberg = 1;

-- Cria alguns snapshots inserindo dados
INSERT INTO iceberg_table VALUES (1);
INSERT INTO iceberg_table VALUES (2);
INSERT INTO iceberg_table VALUES (3);

-- Expira usando apenas a política de retenção
ALTER TABLE iceberg_table EXECUTE expire_snapshots();

-- Expira com fusível de segurança: protege snapshots mais recentes que o timestamp (sintaxe posicional)
ALTER TABLE iceberg_table EXECUTE expire_snapshots('2025-01-01 00:00:00');

-- O mesmo usando a forma de argumento nomeado
ALTER TABLE iceberg_table EXECUTE expire_snapshots(expire_before = '2025-01-01 00:00:00');

-- Substitui os parâmetros de retenção para uma execução
ALTER TABLE iceberg_table EXECUTE expire_snapshots(retention_period = '3d', retain_last = 10);

-- Expira snapshots explícitos
ALTER TABLE iceberg_table EXECUTE expire_snapshots(snapshot_ids = [101, 102, 103]);

-- Pré-visualização em modo dry-run (sem atualizações de metadados, sem exclusão de arquivos)
ALTER TABLE iceberg_table EXECUTE expire_snapshots(retention_period = '1d', dry_run = 1);

Saída:

O comando retorna uma tabela com duas colunas (metric_name String, metric_value Int64), contendo uma linha por métrica. Os nomes das métricas seguem a especificação do Iceberg:

O comando executa as seguintes etapas:

1. Avalia a política de retenção (veja abaixo) para determinar quais snapshots devem ser preservados
2. Se um argumento de timestamp tiver sido fornecido, também protege todos os snapshots nesse timestamp ou posteriores
3. Expira os snapshots que não forem retidos pela política nem protegidos pelo limite de timestamp
4. Calcula quais arquivos estão associados exclusivamente a snapshots expirados
5. No modo normal: gera novos metadados sem os snapshots expirados
6. No modo normal: exclui fisicamente listas de manifesto, arquivos de manifesto e arquivos de dados inacessíveis
7. No modo dry_run = 1: ignora as etapas 5 e 6 e retorna apenas as métricas calculadas

O comando expire_snapshots respeita a política de retenção de snapshots do Iceberg. A retenção é configurada por meio de propriedades da tabela Iceberg e de substituições específicas por referência:

Cada referência de snapshot (refs nos metadados do Iceberg) pode substituir esses valores com campos específicos por referência: min-snapshots-to-keep, max-snapshot-age-ms e max-ref-age-ms.

Avaliação da retenção:

• Para cada branch (incluindo main): a cadeia ancestral é percorrida a partir do head da branch. Os snapshots são mantidos enquanto qualquer uma destas condições for verdadeira:
  • O snapshot está entre os primeiros min-snapshots-to-keep da cadeia
  • A idade do snapshot está dentro de max-snapshot-age-ms (ou seja, now - timestamp-ms <= max-snapshot-age-ms)
• Para tags: o snapshot marcado pela tag é mantido, a menos que a tag tenha excedido seu max-ref-age-ms, caso em que a referência da tag é removida
• Referências diferentes de main cuja idade exceda max-ref-age-ms são removidas por completo (a branch main nunca é removida)
• Referências órfãs que apontam para snapshots inexistentes são removidas com um aviso
• O snapshot atual é sempre preservado, independentemente das configurações de retenção

Privilégios necessários:

O privilégio ALTER TABLE EXECUTE é necessário, e ele é um privilégio filho de ALTER TABLE na hierarquia de controle de acesso do ClickHouse. Você pode concedê-lo especificamente ou por meio do privilégio pai:

-- Conceder apenas a permissão EXECUTE
GRANT ALTER TABLE EXECUTE ON my_iceberg_table TO my_user;

-- Ou conceder todas as permissões de ALTER TABLE (inclui ALTER TABLE EXECUTE)
GRANT ALTER TABLE ON my_iceberg_table TO my_user;

Arquivos órfãos são arquivos no armazenamento que não são referenciados por nenhum snapshot nos metadados da tabela Iceberg. Eles se acumulam devido a gravações com falha, limpeza parcial após a compactação e operações interrompidas, causando crescimento descontrolado do armazenamento. O comando remove_orphan_files identifica e remove esses arquivos órfãos.

Sintaxe:

-- Forma posicional: único argumento older_than sem nome
ALTER TABLE iceberg_table EXECUTE remove_orphan_files('timestamp')

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

-- Sem argumentos: usa todos os padrões (older_than = 3 dias atrás)
ALTER TABLE iceberg_table EXECUTE remove_orphan_files()

Parâmetros:

Exemplos:

-- Remove arquivos órfãos mais antigos que um timestamp específico
ALTER TABLE iceberg_table EXECUTE remove_orphan_files('2026-03-01 00:00:00');

-- Dry run: visualize quais arquivos seriam excluídos
ALTER TABLE iceberg_table EXECUTE remove_orphan_files(dry_run = 1);

-- Escanear apenas o diretório de dados
ALTER TABLE iceberg_table EXECUTE remove_orphan_files(
    older_than = '2026-03-01 00:00:00',
    location = 'data/'
);

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

Saída:

O comando retorna uma tabela com as colunas metric_name e metric_value, mostrando a contagem de arquivos excluídos (ou que seriam excluídos no modo dry_run) por categoria. As categorias de arquivos são classificadas com base em heurísticas de melhor esforço, seguindo convenções de nomenclatura de arquivos; arquivos que não correspondem a nenhum padrão específico são contabilizados por padrão em deleted_data_files_count:

Configurações:

• motor Iceberg
• função de tabela cluster do Iceberg