Primeiros passos com lagos de dados

A forma mais rápida de começar — especialmente para consultas ad hoc ou quando você não usa um catálogo — é a função de tabela icebergS3(). Aponte-a para uma tabela Iceberg no S3 e consulte imediatamente, sem precisar de configuração.

Inspecione o esquema:

DESCRIBE icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

Execute uma consulta:

SELECT
    url,
    count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

O ClickHouse lê os metadados do Iceberg diretamente do S3 e infere o esquema automaticamente. A mesma abordagem funciona para deltaLake(), hudi() e paimon().

Saiba mais: Consultando formatos de tabela abertos diretamente abrange os quatro formatos, variantes de cluster para leituras distribuídas e opções de backend de armazenamento (S3, Azure, HDFS, local).

Se você não usa um catálogo, mas vai consultar o mesmo path repetidamente, crie uma tabela usando o engine de tabela Iceberg para não precisar passar o path todas as vezes. Os dados permanecem no S3 — nenhum dado é duplicado:

CREATE TABLE hits_iceberg
    ENGINE = IcebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

Agora consulte-a como qualquer tabela do ClickHouse:

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

O mecanismo de tabela oferece suporte a cache de dados, cache de metadados, evolução de esquema e time travel. Consulte o guia Consultando diretamente para obter detalhes sobre os recursos do mecanismo de tabela e a matriz de suporte para uma comparação completa dos recursos.

Se a sua organização usa um catálogo de dados, este é o caminho de integração que recomendamos. Os catálogos centralizam os metadados das tabelas e a descoberta — em vez de gerenciar uma definição de tabela para cada path de armazenamento, conecte-se uma vez com o mecanismo de banco de dados DataLakeCatalog. Cada tabela no catálogo aparece como uma tabela do ClickHouse, incluindo tabelas adicionadas upstream depois que você cria a conexão.

Veja um exemplo de conexão com o AWS Glue:

CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = '<your-region>',
    aws_access_key_id = '<your-access-key>',
    aws_secret_access_key = '<your-secret-key>'

Cada tipo de catálogo exige suas próprias configurações de conexão — consulte os guias de Catálogos para ver a lista completa de catálogos compatíveis e suas opções de configuração.

Navegue pelas tabelas e faça consultas:

SHOW TABLES FROM my_lake;

SELECT count(*) FROM my_lake.`<database>.<table>`

Saiba mais: Como se conectar a um catálogo de dados mostra uma configuração completa do Unity Catalog com exemplos de Delta e Iceberg.

Independentemente do método usado acima — função de tabela, engine de tabela ou DataLakeCatalog — o mesmo ClickHouse SQL pode ser usado em todos eles. Em produção, com um catálogo, faça consultas por meio do banco de dados DataLakeCatalog; os outros exemplos continuam úteis para testes rápidos e acesso baseado em path:

-- Table function
SELECT url, count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- Table engine
SELECT url, count() AS cnt
FROM hits_iceberg
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- Catalog
SELECT url, count() AS cnt
FROM my_lake.`<database>.<table>`
GROUP BY url ORDER BY cnt DESC LIMIT 5

A sintaxe da consulta é idêntica — apenas a cláusula FROM muda. Todas as funções, junções e agregações do ClickHouse SQL funcionam da mesma forma, independentemente da fonte de dados.

Consultar o Iceberg diretamente é conveniente, mas o desempenho é limitado pela vazão da rede e pela organização dos arquivos. Para cargas de trabalho analíticas, carregue os dados em uma tabela MergeTree nativa.

Primeiro, execute uma consulta filtrada na tabela Iceberg para obter uma referência inicial:

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Esta consulta percorre todo o conjunto de dados no S3, já que o Iceberg não reconhece o filtro counterid — espere que leve vários segundos.

Agora crie uma tabela MergeTree e carregue os dados:

CREATE TABLE hits_clickhouse
(
    url String,
    eventtime DateTime,
    counterid UInt32
)
ENGINE = MergeTree()
ORDER BY (counterid, eventtime);

INSERT INTO hits_clickhouse
SELECT url, eventtime, counterid
FROM hits_iceberg

Execute novamente a mesma consulta na tabela MergeTree:

SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Como counterid é a primeira coluna da chave ORDER BY, o índice primário esparso do ClickHouse vai direto aos grânulos relevantes — lendo apenas as linhas de counterid = 38 em vez de varrer todas as 100 milhões de linhas. O resultado é uma aceleração drástica.

O guia acelerando análises vai além com tipos LowCardinality, índices de texto completo e chaves de ordenação otimizadas, demonstrando uma melhoria de ~40x em um conjunto de dados com 283 milhões de linhas.

Saiba mais: Acelerando análises com MergeTree aborda a otimização do esquema, a indexação de texto completo e uma comparação completa de desempenho antes/depois.

O ClickHouse também pode gravar dados de volta em tabelas Iceberg, permitindo fluxos de ETL reverso — publicando resultados agregados ou subconjuntos para uso por outras ferramentas (Spark, Trino, DuckDB etc.).

Crie uma tabela Iceberg para a saída:

CREATE TABLE output_iceberg
(
    url String,
    cnt UInt64
)
ENGINE = IcebergS3('https://your-bucket.s3.amazonaws.com/output/', 'access_key', 'secret_key')

Grave resultados agregados:

SET allow_experimental_insert_into_iceberg = 1;

INSERT INTO output_iceberg
SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
GROUP BY url
ORDER BY cnt DESC

A tabela Iceberg resultante pode ser lida por qualquer mecanismo compatível com Iceberg.

Saiba mais: Gravação de dados em formatos de tabela abertos aborda como gravar dados brutos e resultados agregados usando o conjunto de dados UK Price Paid, incluindo considerações sobre esquema ao mapear tipos do ClickHouse para o Iceberg.