Primeiros passos com lagos de dados

ResumoUm passo a passo prático para consultar tabelas de lago de dados, acelerá-las com MergeTree e gravar os resultados de volta no Iceberg. Todas as etapas usam conjuntos de dados públicos e funcionam tanto no Cloud quanto no OSS.

As capturas de tela neste guia são do ClickHouse Cloud Console SQL. Todas as consultas funcionam tanto no Cloud quanto em implantações autogerenciadas. O ClickHouse oferece três maneiras de ler formatos de tabela abertos: funções de tabela, motores de tabela e o motor de banco de dados DataLakeCatalog. Se as suas tabelas estiverem em um catálogo de dados (Glue, Unity Catalog, REST e outros), conecte-se com DataLakeCatalog para acessar todas as suas tabelas Iceberg/Delta por meio de uma única função. As seções abaixo sobre função de tabela e motor de tabela são mais indicadas para consultas ad hoc ou quando você conhece um caminho de armazenamento específico e não usa um catálogo.

Consulte dados do Iceberg diretamente

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

Crie um engine de tabela persistente

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.

Conectar a um catálogo

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.

Recomendado quando você usa um catálogoUse DataLakeCatalog para cargas de trabalho de produção com Glue, Unity Catalog, REST e outros catálogos compatíveis. As funções de tabela e os motores de tabela funcionam quando você conhece um path específico, mas não permanecem sincronizados à medida que seu catálogo cresce e exigem credenciais ou paths separados para cada tabela.

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

Os backticks são obrigatórios em <database>.<table> porque o ClickHouse não oferece suporte nativo a mais de um espaço de nomes.

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.

Faça uma consulta

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.

Carregar um subconjunto no ClickHouse

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.

Gravar de volta em Iceberg

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.

Próximos passos

Agora que você viu todo o fluxo de trabalho, aprofunde-se em cada área:

Conectando-se a catálogos — Recomendado para workloads com suporte de catálogo; passo a passo completo do Unity Catalog com Delta e Iceberg
Consultas diretas — Os quatro formatos, variantes de cluster, motores de tabela, cache
Acelerando analytics — Otimização de schema, indexação, demo de ganho de velocidade de ~40x
Gravando em lagos de dados — Escritas brutas, escritas agregadas, mapeamento de tipos
Matriz de suporte — Comparação de recursos entre formatos e backends de armazenamento
Boas práticas — Seleção do método de acesso, configurações de desempenho e padrões de workload

Guias do ClickHouse

Guias de casos de uso

Próximos passos

​Próximos passos

Próximos passos