跳转到主内容
跳转到主内容

直接查询开放表格式

ClickHouse 提供了表函数，可直接查询以开放表格式存储在对象存储中的数据。无需连接外部目录，而是直接在数据所在位置进行查询，类似于 AWS Athena 从 S3 读取数据的方式。

您只需在函数调用中直接传入存储路径和凭证，其余工作由 ClickHouse 处理。所有 ClickHouse SQL 语法和函数均可用，并且查询还可受益于 ClickHouse 的并行执行能力以及高效的原生 Parquet 读取器。

Server, local or chDB

本指南中的步骤可以在现有的 ClickHouse 服务器安装上执行。对于临时查询，您也可以改用 clickhouse-local，无需运行服务器即可完成相同的工作流。只需做少量调整，也可以使用 ClickHouse 的进程内发行版 chDB 完成这一过程。

以下示例使用存储在 S3 中、采用各种 lakehouse 格式的 hits 数据集。对于每种 lakehouse 格式，每个对象存储提供商都有对应的专用函数。

iceberg 表函数 (icebergS3 的别名) 可直接从对象存储中读取 Iceberg 表。针对每种存储后端均有对应的变体：icebergS3、icebergAzure、icebergHDFS 和 icebergLocal。

示例语法：

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])
GCS 支持

S3 系列函数同样适用于 Google Cloud Storage (GCS)。

示例：

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.

集群模式​

icebergS3Cluster 函数可将读取操作分布到 ClickHouse 集群中的多个节点上。发起节点与所有节点建立连接，并动态分发数据文件。每个工作节点请求并处理任务，直至所有文件读取完毕。icebergCluster 是 icebergS3Cluster 的别名。此外，还提供适用于 Azure (icebergAzureCluster) 和 HDFS (icebergHDFSCluster) 的变体版本。

示例语法：

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

示例 (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

表引擎​

除了在每次查询中使用表函数外，您也可以使用 Iceberg 表引擎 创建持久化表。数据仍存储在对象存储中，按需读取——不会有任何数据被复制到 ClickHouse 中。其优势在于，表定义存储在 ClickHouse 中，可跨用户和会话共享，无需每个用户单独指定存储路径和凭据。每种存储后端均有对应的引擎变体：IcebergS3 (或 Iceberg 别名) 、IcebergAzure、IcebergHDFS 和 IcebergLocal。

表引擎和表函数均支持数据缓存，其缓存机制与 S3、AzureBlobStorage 和 HDFS 存储引擎相同。此外，元数据缓存会将清单文件信息存储在内存中，从而减少对 Iceberg 元数据的重复读取。该缓存默认通过 use_iceberg_metadata_files_cache 设置启用。

示例语法：

表引擎 Iceberg 是 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])
GCS 支持

表引擎的 S3 变体可用于 Google Cloud Storage (GCS)。

示例：

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.

有关支持的功能 (包括分区裁剪、Schema 演进、时间旅行、缓存等) ，请参阅支持矩阵。如需完整参考，请参阅 iceberg 表函数和 Iceberg 表引擎文档。