Primeiros passos com formatos de tabela abertos

Uma introdução prática para consultar, acelerar e gravar novamente dados em formatos de tabela abertos com ClickHouse.

​

Primeiros passos com lagos de dados

TL;DR

Um passo a passo prático para consultar tabelas em 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 deste guia são do Console SQL do ClickHouse Cloud. Todas as consultas funcionam tanto no Cloud quanto em implantações autogerenciadas.

1. ​

   Consulte dados do Iceberg diretamente

   A forma mais rápida de começar é com 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).

2. ​

   Crie um engine de tabela persistente

   Para acessos recorrentes, crie uma tabela usando o engine de tabela Iceberg para que você não precise passar o path toda vez. 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.

3. ​

   Conectar a um catálogo

   A maioria das organizações gerencia tabelas Iceberg por meio de um catálogo de dados para centralizar os metadados das tabelas e a descoberta de dados. O ClickHouse oferece suporte à conexão com seu catálogo usando o mecanismo de banco de dados DataLakeCatalog, expondo todas as tabelas do catálogo como um banco de dados no ClickHouse. Essa é a opção mais escalável, pois, à medida que novas tabelas Iceberg são criadas, elas ficam sempre acessíveis no ClickHouse sem exigir trabalho adicional.

   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.

4. ​

   Faça uma consulta

   Independentemente do método usado acima — função de tabela, engine de tabela ou catálogo — o mesmo ClickHouse SQL pode ser usado em todos eles:

   -- Função de tabela
   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
   
   -- Engine de tabela
   SELECT url, count() AS cnt
   FROM hits_iceberg
   GROUP BY url ORDER BY cnt DESC LIMIT 5
   
   -- Catálogo
   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.

5. ​

   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.

6. ​

   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 o fluxo de trabalho completo, aprofunde-se em cada área:

• Consulta direta — Os quatro formatos, variantes de cluster, motores de tabela, cache
• Conexão com catálogos — Passo a passo completo do Unity Catalog com Delta e Iceberg
• Acelerando análises — Otimização de esquema, indexação, demo de ganho de desempenho 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