Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Consultando formatos abertos de tabela diretamente

View as MarkdownEdit this pageReport an issueSet up docs MCP

O ClickHouse fornece funções de tabela para consultar dados armazenados em formatos de tabela abertos diretamente no armazenamento de objetos. Isso não exige conexão com um catálogo externo — os dados são consultados onde estão, de forma semelhante a como o AWS Athena lê do S3.

Você informa o caminho de armazenamento e as credenciais diretamente na chamada da função, e o ClickHouse cuida do restante. Toda a sintaxe e as funções do ClickHouse SQL estão disponíveis, e as consultas se beneficiam da execução paralelizada do ClickHouse e do eficiente leitor nativo de Parquet.

Os exemplos a seguir usam o conjunto de dados hits armazenado em cada formato lakehouse no S3. Para cada formato lakehouse, existem funções dedicadas para cada provedor de armazenamento de objetos.

A table function iceberg (alias de icebergS3) lê tabelas Iceberg diretamente do armazenamento de objetos. Existem variantes para cada backend de armazenamento: icebergS3, icebergAzure, icebergHDFS e icebergLocal.

Exemplo de sintaxe:

icebergS3(url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method])

icebergAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

icebergLocal(path_to_table, [,format] [,compression_method])

Exemplo:

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
┌─url────────────────────────────────────────────────┬─────cnt─┐
│ http://liver.ru/belgorod/page/1006.jки/доп_приборы │ 3288173 │ -- 3.29 million
│ http://kinopoisk.ru                                │ 1625250 │ -- 1.63 million
│ http://bdsm_po_yers=0&with_video                   │  791465 │
│ http://video.yandex                                │  582400 │
│ http://smeshariki.ru/region                        │  514984 │
└────────────────────────────────────────────────────┴─────────┘

5 rows in set. Elapsed: 3.375 sec. Processed 100.00 million rows, 9.98 GB (29.63 million rows/s., 2.96 GB/s.)
Peak memory usage: 10.48 GiB.

Variante de cluster

A função icebergS3Cluster distribui leituras entre múltiplos nós em um cluster ClickHouse. O nó iniciador estabelece conexões com todos os nós e despacha os arquivos de dados dinamicamente. Cada nó worker solicita e processa tarefas até que todos os arquivos sejam lidos. icebergCluster é um alias para icebergS3Cluster. Também existem variantes para Azure (icebergAzureCluster) e HDFS (icebergHDFSCluster).

Exemplo de sintaxe:

icebergS3Cluster(cluster_name, url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method])
-- icebergCluster is an alias for icebergS3Cluster

icebergAzureCluster(cluster_name, connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

Exemplo (ClickHouse Cloud):

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

Engine de tabela

Como alternativa ao uso da table function em cada consulta, você pode criar uma tabela persistente utilizando o motor de tabela Iceberg. Os dados continuam residindo no armazenamento de objetos e são lidos sob demanda — nenhum dado é copiado para o ClickHouse. A vantagem é que a definição da tabela fica armazenada no ClickHouse e pode ser compartilhada entre usuários e sessões, sem que cada usuário precise especificar o caminho de armazenamento e as credenciais. Existem variantes do motor para cada backend de armazenamento: IcebergS3 (ou o alias Iceberg), IcebergAzure, IcebergHDFS e IcebergLocal.

Tanto o motor de tabela quanto a função de tabela suportam cache de dados, utilizando o mesmo mecanismo de cache dos motores de armazenamento S3, AzureBlobStorage e HDFS. Além disso, um metadata cache armazena informações do manifest file em memória, reduzindo leituras repetidas de metadados do Iceberg. Esse cache é habilitado por padrão por meio da configuração use_iceberg_metadata_files_cache.

Exemplo de sintaxe:

O mecanismo de tabela Iceberg é um alias de IcebergS3.

CREATE TABLE iceberg_table
    ENGINE = IcebergS3(url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method])

CREATE TABLE iceberg_table
    ENGINE = IcebergAzure(connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression])

CREATE TABLE iceberg_table
    ENGINE = IcebergLocal(path_to_table, [,format] [,compression_method])

Exemplo:

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

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
GROUP BY url
ORDER BY cnt DESC
LIMIT 5
┌─url────────────────────────────────────────────────┬─────cnt─┐
│ http://liver.ru/belgorod/page/1006.jки/доп_приборы │ 3288173 │
│ http://kinopoisk.ru                                │ 1625250 │
│ http://bdsm_po_yers=0&with_video                   │  791465 │
│ http://video.yandex                                │  582400 │
│ http://smeshariki.ru/region                        │  514984 │
└────────────────────────────────────────────────────┴─────────┘

5 rows in set. Elapsed: 2.737 sec. Processed 100.00 million rows, 9.98 GB (36.53 million rows/s., 3.64 GB/s.)
Peak memory usage: 10.53 GiB.

Para os recursos suportados, incluindo partition pruning, evolução de schema, time travel, caching e mais, consulte a matriz de suporte. Para referência completa, consulte a documentação da função de tabela iceberg e do motor de tabela Iceberg.

Navigation