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

直接查询开放表格式表

ClickHouse 提供表函数，用于直接在对象存储中查询以开放表格式存储的数据。这样无需连接到外部目录——它会就地查询数据，类似于 AWS Athena 从 S3 读取数据的方式。

你可以在函数调用中直接传入存储路径和凭证，其余由 ClickHouse 处理。可以使用全部 ClickHouse SQL 语法和函数，查询还能受益于 ClickHouse 的并行执行以及高效的原生 Parquet 读取器。

Server, local or chDB

本指南中的步骤可以使用现有的 ClickHouse server 安装来执行。对于临时查询，你也可以使用 clickhouse-local，在不运行 server 的情况下完成相同的工作流。经过少量调整后，该流程也可以使用 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 表引擎文档。