将 Amazon S3 集成到 ClickHouse Cloud

将您的对象存储无缝接入 ClickHouse Cloud。

S3 ClickPipe 提供了一种全托管且具备高韧性的方式，可将 Amazon S3 和兼容 S3 的对象存储中的数据摄取到 ClickHouse Cloud。它同时支持 一次性 和 持续摄取，并具备精确一次语义。

S3 ClickPipes 既可以通过 ClickPipes UI 手动部署和管理，也可以通过 OpenAPI 和 Terraform 以编程方式部署和管理。

​

支持的数据源

名称	徽标	详情
Amazon S3		默认情况下，持续摄取要求按词典序进行，但也可配置为按任意顺序摄取文件。
Cloudflare R2 兼容 S3		持续摄取要求按词典序进行。不支持无序模式。
DigitalOcean Spaces 兼容 S3		持续摄取要求按词典序进行。不支持无序模式。
OVH Object Storage 兼容 S3		持续摄取要求按词典序进行。不支持无序模式。

由于不同对象存储服务提供商的 URL 格式和 API 实现存在差异，并非所有兼容 S3 的服务都能直接开箱即用。如果你在使用上方未列出的服务时遇到问题，请联系我们的团队。

​

支持的格式

• JSON
• CSV
• TSV
• Parquet
• Avro

​

特性

​

一次性摄取

默认情况下，S3 ClickPipe 会将指定 存储桶 中所有匹配某个 模式 的文件以单个批次操作加载到 ClickHouse 目标表中。摄取任务完成后，ClickPipe 会自动停止。这种一次性摄取模式提供精确一次语义，确保每个文件都能被可靠地处理且不会重复处理。

​

持续摄取

启用持续摄取后，ClickPipes 会从指定路径持续摄取数据。默认情况下，S3 ClickPipe 依靠文件的隐式词典序来确定摄取顺序。也可以将其配置为通过连接到存储桶的 Amazon SQS 队列，按任意顺序摄取文件。

​

词典序

默认情况下，S3 ClickPipe 假定文件会按词典序添加到存储桶中，并依赖这种隐含顺序依次摄取文件。这意味着任何新文件必须在词典序上大于上一个已摄取的文件。例如，名为 file1、file2 和 file3 的文件会被依次摄取；但如果有一个新的 file 0 添加到存储桶中，它将被忽略，因为该文件名在词典序上并不大于上一个已摄取的文件。

在此模式下，S3 ClickPipe 会对指定路径中的所有文件执行初始加载，然后按可配置的时间间隔轮询新文件 (默认为 30 秒) 。无法从某个特定文件或时间点开始摄取——ClickPipes 始终会加载指定路径中的所有文件。

​

任意顺序

如需分步说明，请参阅为持续摄取配置无序模式。

可以通过设置一个连接到存储桶的 Amazon SQS 队列，并可选使用 Amazon EventBridge 作为事件路由器，来配置 S3 ClickPipe，以摄取没有隐含顺序的文件。这样一来，ClickPipes 就可以监听对象创建事件，并摄取任何新文件，而不受文件命名约定的限制。

无序模式仅支持 Amazon S3，不支持公共存储桶或兼容 S3 的服务。它要求设置一个连接到存储桶的 Amazon SQS 队列，并可选使用 Amazon EventBridge 作为事件路由器。

在此模式下，S3 ClickPipe 会先对所选路径中的所有文件执行初始加载，然后监听队列中与指定路径匹配的 ObjectCreated:* 事件。对于之前已处理过的文件、不匹配该路径的文件，或其他类型事件的消息，都会被忽略。

为事件设置前缀/后缀是可选的。如果设置了，请确保它与为 ClickPipe 配置的路径一致。S3 不允许为相同事件类型配置多个相互重叠的通知规则。

当达到 max insert bytes 或 max file count 中配置的阈值时，或者经过一个可配置的时间间隔后 (默认 30 秒) ，系统就会开始摄取文件。无法从某个特定文件或某个时间点开始摄取——ClickPipes 始终会加载所选路径中的所有文件。如果配置了 DLQ，失败的消息会被重新入队并重新处理，最多重试到 DLQ maxReceiveCount 参数中配置的次数。

我们强烈建议为 SQS 队列配置 Dead-Letter-Queue (DLQ)，这样更方便调试和重试失败的消息。

EventBridge 到 SQS

也可以通过 Amazon EventBridge 将 S3 事件通知发送到 SQS。对于大多数使用场景，推荐采用这种方法，因为 EventBridge 支持更丰富的事件过滤、将事件分发到多个目标，而且不受 S3“每个前缀下每种事件类型只能有一条通知规则”这一限制。有关分步说明，请参见为持续摄取配置 无序模式。

SNS 到 SQS

也可以通过 SNS topic 将 S3 事件通知发送到 SQS。在直接使用 S3 → SQS 集成受到某些限制时，可以采用这种方式。在这种情况下，你需要启用 raw message delivery 选项。

​

文件模式匹配

对象存储 ClickPipes 遵循 POSIX 文件模式匹配标准。所有模式均区分大小写，并会匹配 存储桶 名称之后的完整路径。为获得更佳性能，请尽可能使用最具体的模式 (例如，使用 data-2024-*.csv，而不是 *.csv) 。

​

支持的模式

模式	描述	示例	匹配项
?	精确匹配一个字符 (不含 /)	data-?.csv	data-1.csv, data-a.csv, data-x.csv
*	匹配零个或多个字符 (不含 /)	data-*.csv	data-1.csv, data-001.csv, data-report.csv, data-.csv
** 递归	匹配零个或多个字符 (包含 /) 。支持递归遍历目录。	logs/**/error.log	logs/error.log, logs/2024/error.log, logs/2024/01/error.log

示例：

• https://bucket.s3.amazonaws.com/folder/*.csv
• https://bucket.s3.amazonaws.com/logs/**/data.json
• https://bucket.s3.amazonaws.com/file-?.parquet
• https://bucket.s3.amazonaws.com/data-2024-*.csv.gz

​

不支持的模式

模式	描述	示例	替代方案
{abc,def}	大括号展开。	{logs,data}/file.csv	为每个路径分别创建单独的 ClickPipes。
{N..M}	数字范围展开	file-{1..100}.csv	使用 file-*.csv 或 file-?.csv。

示例：

• https://bucket.s3.amazonaws.com/{documents-01,documents-02}.json
• https://bucket.s3.amazonaws.com/file-{1..100}.csv
• https://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet

​

精确一次语义

在摄取大型数据集时，可能会发生各种故障，从而导致部分插入或数据重复。对象存储 ClickPipes 能够在插入失败时保持稳健，并提供精确一次语义。这是通过使用临时“暂存”表实现的。数据会先插入暂存表。如果这次插入出现问题，可以清空暂存表，并从干净状态重新尝试插入。只有当插入完整且成功完成后，暂存表中的分区才会被移动到目标表。若要进一步了解这一策略，请参阅这篇博文。

​

虚拟列

要跟踪哪些文件已被摄取，请将 _file 虚拟列添加到列映射列表中。_file 虚拟列包含源对象的文件名，可用于查询哪些文件已被处理。

​

访问控制

​

权限

S3 ClickPipe 支持公有和私有存储桶。不支持 Requester Pays 存储桶。

​

S3 存储桶

存储桶策略中必须允许以下操作：

• s3:GetObject
• s3:ListBucket

​

SQS 队列

使用无序模式时，SQS 必须在队列策略中允许以下操作：

• sqs:ReceiveMessage
• sqs:DeleteMessage
• sqs:GetQueueAttributes
• sqs:ListQueues

​

身份验证

​

IAM 凭证

要使用访问密钥进行身份验证，请在设置 ClickPipe 连接时，在 Authentication method 下选择 Credentials。然后，分别在 Access key 和 Secret key 中填写访问密钥 ID (例如 AKIAIOSFODNN7EXAMPLE) 和秘密访问密钥 (例如 wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY) 。

​

IAM role

如需使用基于角色的访问进行身份验证，请在设置 ClickPipe 连接 时，在 Authentication method 下选择 IAM role。

请按照本指南创建具有 S3 访问所需信任策略的role。然后，在 IAM role ARN 中填入 IAM role ARN。

​

网络访问

S3 ClickPipes 在元数据发现和数据摄取时分别使用两条不同的网络路径：ClickPipes 服务和 ClickHouse Cloud 服务。如果你想额外增加一层网络安全保护 (例如出于合规原因) ，则必须同时为这两条路径配置网络访问。

• 对于基于 IP 的访问控制，S3 存储桶策略必须允许 此处 列出的 ClickPipes 服务所在区域的静态 IP，以及 ClickHouse Cloud 服务的静态 IP。要获取你的 ClickHouse Cloud 区域的静态 IP，请打开终端并运行：

  # 将 <your-region> 替换为你的 ClickHouse Cloud 区域
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .egress_ips[]'
  

• 对于基于 VPC 端点的访问控制，S3 存储桶必须与 ClickHouse Cloud 服务位于同一区域，并将 GetObject 操作限制为仅允许来自 ClickHouse Cloud 服务的 VPC Endpoint ID。要获取你的 ClickHouse Cloud 区域的 VPC 端点，请打开终端并运行：

  # 将 <your-region> 替换为你的 ClickHouse Cloud 区域
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .s3_endpoints[]'
  

​

高级设置

ClickPipes 提供了合理的默认设置，能够满足大多数使用场景的需求。如果您的使用场景需要进一步微调，可以调整以下设置：

设置	默认值	说明
Max insert bytes	10GB	单个插入批次中处理的字节数。
Max file count	100	单个插入批次中处理的最大文件数。
Max threads	auto(3)	用于文件处理的最大并发线程数。
Max insert threads	1	用于文件处理的最大并发插入线程数。
Min insert block size bytes	1GB	可插入表中的块最小字节数。
Max download threads	4	最大并发下载线程数。
Object storage polling interval	30s	配置将数据插入 ClickHouse 集群前的最长等待时间。
Parallel distributed insert select	2	Parallel distributed insert select 设置。
Parallel view processing	false	是否启用以并发而非顺序的方式推送到已附加的视图。
Use cluster function	true	是否在多个节点之间并行处理文件。

​

扩缩容

对象存储 ClickPipes 的扩缩容依据 已配置的垂直自动扩缩容设置 所确定的 ClickHouse 服务最小规格。ClickPipe 的大小在创建管道时确定，之后对 ClickHouse 服务设置所做的更改不会影响 ClickPipe 的大小。

如需提高大型摄取作业的吞吐量，我们建议先对 ClickHouse 服务进行扩缩容，再创建 ClickPipe。

​

已知限制

​

文件大小

ClickPipes 只会尝试摄取大小不超过 10GB的对象。如果文件超过 10GB，系统会将一条错误记录追加到 ClickPipes 的专用错误表中。

​

兼容性

尽管兼容 S3，但某些服务使用不同的 URL 结构，导致 S3 ClickPipe 可能无法解析 (例如 Backblaze B2) ；或者它们需要与提供商专用的队列服务集成，才能实现持续的无序摄取。如果你在使用某个未列在支持的数据源中的服务时遇到问题，请联系我们的团队。

​

视图支持

目标表上的 materialized view 同样受支持。ClickPipes 不仅会为目标表创建暂存表，也会为任何依赖的 materialized view 创建暂存表。

我们不会为非物化视图创建暂存表。这意味着，如果你的目标表有一个或多个下游 materialized view，这些 materialized view 应避免通过目标表上的视图来查询数据。否则，你可能会发现 materialized view 中会缺少数据。