跳至主要内容
跳至主要内容
编辑此页

将 Amazon S3 与 ClickHouse Cloud 集成

S3 ClickPipe 提供了一种完全托管且具有弹性的方式，用于将 Amazon S3 和兼容 S3 的对象存储中的数据导入 ClickHouse Cloud。它支持一次性和持续导入，并具有精确一次语义。

可以使用 ClickPipes UI 手动部署和管理 S3 ClickPipes，也可以使用 OpenAPI 和 Terraform 以编程方式进行管理。

支持的数据源​

名称Logo详情
Amazon S3持续导入默认需要 词法顺序，但可以配置为 以任何顺序导入 文件。
Cloudflare R2
兼容 S3		持续导入需要 词法顺序。不支持无序模式。
DigitalOcean Spaces
兼容 S3		持续导入需要 词法顺序。不支持无序模式。
OVH 对象存储
兼容 S3
持续导入需要 词法顺序。不支持无序模式。
提示

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

支持的格式​

特性​

一次性导入​

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

持续导入​

启用持续导入后，ClickPipes 会持续从指定的路径导入数据。为了确定导入顺序，S3 ClickPipe 默认依赖于文件的隐式 词法顺序。它也可以配置为使用与存储桶连接的 Amazon SQS 队列以 任何顺序 导入文件。

词法顺序​

默认情况下，S3 ClickPipe 假定文件以词法顺序添加到存储桶中，并依赖于此隐式顺序按顺序导入文件。这意味着任何新文件必须在词法上大于最后导入的文件。例如，名为 file1、file2 和 file3 的文件将按顺序导入，但如果在存储桶中添加了一个新的 file 0，则它将被 忽略，因为文件名在词法上不大于最后导入的文件。

在这种模式下，S3 ClickPipe 会初始加载指定路径中的所有文件，然后以可配置的间隔（默认情况下为 30 秒）轮询新文件。从特定文件或时间点开始导入是不可能的——ClickPipes 将始终加载指定路径中的所有文件。

任何顺序​

注意

无序模式仅受 Amazon S3 支持，并且不支持公共存储桶。它需要设置与存储桶连接的 Amazon SQS 队列。

可以通过设置与存储桶连接的 Amazon SQS 队列来配置 S3 ClickPipe 以导入没有隐式顺序的文件。这允许 ClickPipes 侦听对象创建事件并导入任何新文件，而不管文件名约定如何。

在这种模式下，S3 ClickPipe 会初始加载所选路径中的所有文件，然后侦听队列中与指定路径匹配的 ObjectCreated:* 事件。任何先前见过文件的消息、不匹配路径的文件或不同类型的事件都将被 忽略。

注意

为事件设置前缀/后缀是可选的。如果这样做，请确保它与 Clickpipe 设置的路径匹配。S3 不允许对相同事件类型设置多个重叠的通知规则。

文件将在达到 max insert bytes 或 max file count 中配置的阈值，或在可配置的间隔（默认情况下为 30 秒）后被导入。从特定文件或时间点开始导入是不可能的——ClickPipes 将始终加载指定路径中的所有文件。如果配置了 DLQ，失败的消息将被重新排队并重新处理，次数由 DLQ maxReceiveCount 参数配置。

提示

我们强烈建议为 SQS 队列配置一个死信队列 (DLQ)，以便更容易地调试和重试失败的消息。

SNS 到 SQS​

也可以通过 SNS 主题将 S3 事件通知发送到 SQS。如果满足了直接 S3 → SQS 集成的某些限制，可以使用此方法。在这种情况下，您需要启用 原始消息传递 选项。

文件模式匹配​

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

支持的模式​

模式描述示例匹配项
?匹配 一个 字符（不包括 /）data-?.csvdata-1.csv、data-a.csv、data-x.csv
*匹配 零个或多个 字符（不包括 /）data-*.csvdata-1.csv、data-001.csv、data-report.csv、data-.csv
**
递归		匹配 零个或多个 字符（包括 /）。启用递归目录遍历。logs/**/error.loglogs/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 存储桶​

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

SQS 队列​

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

身份验证​

IAM 凭证​

要使用 访问密钥 进行身份验证，请在设置 ClickPipe 连接时在身份验证方法下选择 Credentials。然后在 Access key 和 Secret key 下提供访问密钥 ID（例如，AKIAIOSFODNN7EXAMPLE）和秘密访问密钥（例如，wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY）。

IAM 角色​

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

按照 此指南 创建 具有 S3 访问所需信任策略的角色。然后在 IAM role ARN 下提供 IAM 角色 ARN。

网络访问​

S3 ClickPipes 为元数据发现和数据导入使用两个不同的网络路径：ClickPipes 服务和 ClickHouse Cloud 服务。如果您想配置额外的网络安全层（例如，出于合规原因），则必须为这两个路径配置网络访问。

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

    # Replace <your-region> with your ClickHouse Cloud region
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 端点 ID。要获取 ClickHouse Cloud 区域的 VPC 端点，请打开终端并运行

    # Replace <your-region> with your ClickHouse Cloud region
curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .s3_endpoints[]'

高级设置​

ClickPipes 提供了合理的默认值，涵盖了大多数用例的需求。如果您的用例需要额外的微调，您可以调整以下设置

设置默认值描述
最大插入字节数10GB在单个插入批次中处理的字节数。
最大文件数100在单个插入批次中处理的最大文件数。
最大线程数auto(3)文件处理的最大并发线程数。
最大插入线程数1文件处理的最大并发插入线程数。
最小插入块大小字节数1GB可以插入到表中的块的最小字节大小。
最大下载线程数4最大并发下载线程数.
对象存储轮询间隔30s配置将数据插入 ClickHouse 集群前的最大等待时间。
并行分布式插入选择2并行分布式插入选择设置.
并行视图处理false是否启用将数据推送到附加视图并发而不是顺序地。
使用集群函数true是否在多个节点上并行处理文件。

扩展​

Object Storage ClickPipes 的扩展基于由配置的垂直自动扩展设置确定的最小 ClickHouse 服务大小。ClickPipe 的大小在创建管道时确定。ClickHouse 服务设置的后续更改不会影响 ClickPipe 的大小。

为了提高大型导入作业的吞吐量，我们建议在创建 ClickPipe 之前扩展 ClickHouse 服务。

已知限制​

文件大小​

ClickPipes 仅会尝试导入大小为 10GB 或更小 的对象。如果文件大于 10GB，则会将错误附加到 ClickPipes 专用错误表。

兼容性​

尽管与 S3 兼容，但某些服务使用 ClickPipe 可能无法解析的不同 URL 结构（例如，Backblaze B2），或者需要与提供商特定的队列服务集成才能进行连续、无序的导入。如果您在使用未列在支持的数据源下的服务时遇到问题，请联系我们的团队。

视图支持​

目标表上的物化视图也受支持。ClickPipes 不仅为目标表创建暂存表，还为任何依赖的物化视图创建暂存表。

我们不会为非物化视图创建暂存表。这意味着，如果您有一个目标表和一个或多个下游物化视图，则这些物化视图不应通过视图从目标表选择数据。否则，您可能会发现物化视图中缺少数据。

    © . This site is unofficial and not affiliated with ClickHouse, Inc.