跳到主要内容
跳到主要内容

s3 表函数

提供一个类似表的接口，用于选择/插入 Amazon S3 和 Google Cloud Storage，这个表函数类似于 hdfs 函数，但提供 S3 特定的功能。

如果您的集群中有多个副本，可以使用 s3Cluster 函数 来并行化插入。

在使用 s3 表函数 与 INSERT INTO...SELECT 时，数据会以流式的方式进行读取和插入。仅有少量数据块驻留在内存中，而数据块会持续从 S3 中读取并推送到目标表中。

语法

GCS

S3 表函数通过使用 GCS XML API 和 HMAC 密钥与 Google Cloud Storage 集成。有关端点和 HMAC 的更多详细信息，请参见 Google 互操作性文档。

对于 GCS，将 HMAC 密钥和 HMAC 秘钥替换为您看到的 access_key_id 和 secret_access_key。

参数

s3 表函数支持以下普通参数：

  • url — 指向文件的存储桶 URL。支持以下通配符的只读模式：*、**、?、{abc,def} 和 {N..M}，其中 N、M 为数字，'abc'、'def' 为字符串。有关更多信息，请参见 此处。
    GCS

    GCS URL 的格式为：

而不是 ~~https://storage.cloud.google.com~~。 :::

  • NOSIGN — 如果在凭证位置提供这个关键词，则所有请求将不会被签名。
  • access_key_id 和 secret_access_key — 指定要与给定端点一起使用的凭证的密钥。可选。
  • session_token - 要与给定密钥一起使用的会话令牌。传递密钥时可选。
  • format — 文件的 格式。
  • structure — 表的结构。格式为 'column1_name column1_type, column2_name column2_type, ...'。
  • compression_method — 参数可选。支持的值：none、gzip 或 gz、brotli 或 br、xz 或 LZMA、zstd 或 zst。默认情况下，它会根据文件扩展名自动检测压缩方法。
  • headers - 参数可选。允许在 S3 请求中传递头信息。以 headers(key=value) 格式传递，例如 headers('x-amz-request-payer' = 'requester')。

参数还可以使用 命名集合 进行传递。在这种情况下，url、access_key_id、secret_access_key、format、structure、compression_method 的工作方式相同，并支持一些额外参数：

  • filename — 如果指定，将附加到 URL。
  • use_environment_credentials — 默认启用，允许使用环境变量 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI、AWS_CONTAINER_CREDENTIALS_FULL_URI、AWS_CONTAINER_AUTHORIZATION_TOKEN、AWS_EC2_METADATA_DISABLED 传递额外参数。
  • no_sign_request — 默认禁用。
  • expiration_window_seconds — 默认值为 120。

返回值

一个具有指定结构的表，用于读取或写入指定文件中的数据。

示例

从 S3 文件 https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv 中选择前 5 行：

备注

ClickHouse 使用文件名扩展名来确定数据的格式。例如，我们可以运行以下命令而不使用 CSVWithNames：

ClickHouse 还可以确定文件的压缩方法。例如，如果文件以 .csv.gz 扩展名压缩，ClickHouse 会自动解压缩该文件。

用法​

假设我们在 S3 上有几个文件，其 URI 如下：

统计以数字 1 到 3 结尾的文件中的行数：

统计这两个目录中所有文件的总行数：

提示

如果文件列表中包含前导零的数字范围，请分别为每个数字使用大括号构造，或使用 ?。

统计文件名为 file-000.csv、file-001.csv、...、file-999.csv 的文件中的总行数：

将数据插入文件 test-data.csv.gz：

从现有表中将数据插入文件 test-data.csv.gz：

可以使用 ** 进行递归目录遍历。考虑下面的示例，它将递归地获取 my-test-bucket-768 目录中的所有文件：

下面从 my-test-bucket 目录中的任何文件夹中递归地获取所有 test-data.csv.gz 文件：

注意。可以在服务器配置文件中指定自定义 URL 映射器。例如：

URL 's3://clickhouse-public-datasets/my-test-bucket-768/**/test-data.csv.gz' 将被替换为 'http://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/**/test-data.csv.gz'

自定义映射器可以添加到 config.xml 中：

对于生产用例，建议使用 命名集合。以下是示例：

分区写入​

如果您在插入数据到 S3 表时指定了 PARTITION BY 表达式，将为每个分区值创建一个单独的文件。将数据拆分为单独的文件有助于提高读取操作的效率。

示例

  1. 使用分区 ID 作为键创建单独的文件：

结果，数据被写入三个文件：file_x.csv、file_y.csv 和 file_z.csv。

  1. 将分区 ID 用于存储桶名称，可以在不同的存储桶中创建文件：

结果，数据被写入三个不同的存储桶中的文件：my_bucket_1/file.csv、my_bucket_10/file.csv 和 my_bucket_20/file.csv。

访问公共存储桶​

ClickHouse 尝试从多种不同类型的源获取凭证。 有时，这可能会导致访问某些公共存储桶时客户端返回 403 错误码。 通过使用 NOSIGN 关键字，可以避免此问题，该关键字强制客户端忽略所有凭证，并不签名请求。

使用 S3 凭证 (ClickHouse Cloud)​

对于非公共存储桶，用户可以将 aws_access_key_id 和 aws_secret_access_key 传递给函数。例如：

这种方法适合一次性访问或凭证易于轮换的场合。然而，不建议将其作为重复访问或处理敏感凭证的长期解决方案。在这种情况下，我们建议用户依赖基于角色的访问。

ClickHouse Cloud 中 S3 的基于角色的访问文档见 此处。

配置完后，可以通过 extra_credentials 参数将 roleARN 传递给 s3 函数。例如：

更多示例请见 此处

处理归档​

假设我们在 S3 上有几个归档文件，其 URI 如下：

可以使用 :: 从这些归档中提取数据。在 URL 部分以及 :: 之后的部分（负责归档内文件名的部分）都可以使用通配符。

备注

ClickHouse 支持三种归档格式： ZIP TAR 7Z 在任何受支持的存储位置均可访问 ZIP 和 TAR 归档，而 7Z 归档只能从安装 ClickHouse 的本地文件系统读取。

虚拟列​

  • _path — 文件路径。类型：LowCardinality(String)。在归档的情况下，显示格式为："{path_to_archive}::{path_to_file_inside_archive}"
  • _file — 文件名。类型：LowCardinality(String)。在归档的情况下，显示为归档内文件的名称。
  • _size — 文件大小（以字节为单位）。类型：Nullable(UInt64)。如果文件大小未知，则值为 NULL。在归档的情况下，显示归档内文件的未压缩大小。
  • _time — 文件的最后修改时间。类型：Nullable(DateTime)。如果时间未知，值为 NULL。

Hive 风格分区​

当设置 use_hive_partitioning 为 1 时，ClickHouse 将检测路径中 Hive 风格的分区 (/name=value/) 并允许在查询中使用分区列作为虚拟列。这些虚拟列将与分区路径中的名称相同，但以 _ 开头。

示例

使用 Hive 风格分区创建的虚拟列

访问请求者付费的存储桶​

要访问请求者付费的存储桶，必须在任何请求中传递头部 x-amz-request-payer = requester。这可以通过将参数 headers('x-amz-request-payer' = 'requester') 传递给 s3 函数来实现。例如：

存储设置​

另见