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

将 Google Cloud Storage 与 ClickHouse Cloud 集成

GCS ClickPipe 提供了一种完全托管且具备高可靠性的方式，用于从 Google Cloud Storage (GCS) 摄取数据。它同时支持具有 exactly-once 语义的 一次性摄取 和 持续摄取。

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

支持的格式​

功能​

一次性摄取​

默认情况下，GCS ClickPipe 会在一次批处理操作中，从指定 bucket 中按模式匹配将所有文件加载到 ClickHouse 目标表中。摄取任务完成后，ClickPipe 会自动停止。此一次性摄取模式提供精确一次（exactly-once）语义，确保每个文件都能被可靠处理且不会产生重复。

持续摄取​

启用持续摄取后，ClickPipes 会从指定路径持续摄取数据。为确定摄取顺序，GCS ClickPipe 依赖文件的隐式字典序。

Lexicographical order​

GCS ClickPipe 假定文件是按词典序添加到存储桶中的，并依赖这种隐式顺序按顺序摄取文件。也就是说，任何新文件必须在词典序上大于上一次已摄取的文件。例如，名为 file1、file2 和 file3 的文件会被依次摄取，但如果在存储桶中新增一个 file 0 文件，它将会被忽略，因为该文件名在词典序上并不大于最后一个已摄取的文件。

在此模式下，GCS ClickPipe 会对指定路径中的所有文件进行一次初始加载，然后按可配置的时间间隔轮询以发现新文件（默认 30 秒）。无法从某个特定文件或时间点开始摄取——ClickPipes 将始终加载指定路径中的所有文件。

文件模式匹配​

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

支持的模式​

Pattern描述示例匹配结果
?精确匹配 一个 字符（不包含 /）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

不支持的模式​

PatternDescriptionExampleAlternatives
{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

Exactly-once 语义​

在摄取大型数据集时，可能会发生各种类型的故障，从而导致部分插入或产生重复数据。Object Storage ClickPipes 能够抵御插入失败，并提供 Exactly-once 语义。其实现方式是使用临时的“暂存”（staging）表。数据首先被插入到暂存表中。如果此次插入出现问题，可以截断暂存表，并在干净状态下重试插入。只有当一次插入完成且成功后，暂存表中的分区才会被移动到目标表。要进一步了解这一策略，请参阅这篇博客文章。

虚拟列​

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

访问控制​

权限​

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

必须在存储桶级别授予 roles/storage.objectViewer 角色。该角色包含 storage.objects.list 和 storage.objects.get 这两个 IAM 权限，使 ClickPipes 可以在指定的存储桶中列出并获取对象。

身份验证​

注意

当前不支持使用服务账户进行身份验证。

HMAC 凭证​

要使用 HMAC keys 进行身份验证，在设置 ClickPipe 连接时，在 Authentication method 中选择 Credentials。然后分别在 Access key 和 Secret key 中提供访问密钥（例如 GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA）和秘密密钥（例如 bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ）。

用于 GCS ClickPipes 的 HMAC 凭证

请参阅本指南来创建带有 HMAC 密钥的服务账号。

高级设置​

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

SettingDefault valueDescription
Max insert bytes10GB单个插入批次中要处理的字节数。
Max file count100单个插入批次中要处理的最大文件数量。
Max threadsauto(3)用于文件处理的最大并发线程数。
Max insert threads1用于文件处理的最大并发插入线程数。
Min insert block size bytes1GB可插入到表中的数据块的最小字节数。
Max download threads4最大并发下载线程数。
Object storage polling interval30s配置在向 ClickHouse 集群插入数据前的最大等待时间。
Parallel distributed insert select2并行分布式 INSERT SELECT 设置。
Parallel view processingfalse是否并发而非串行向附加的 VIEW 推送数据。
Use cluster functiontrue是否在多个节点上并行处理文件。
ClickPipes 的高级设置

扩展​

Object Storage ClickPipes 的规模取决于由已配置的垂直自动扩缩设置确定的 ClickHouse 服务最小规格。ClickPipe 的规格会在创建时确定。之后对 ClickHouse 服务设置所做的更改不会影响 ClickPipe 的规格。

要提升大规模摄取任务的吞吐量，我们建议在创建 ClickPipe 之前先扩容 ClickHouse 服务。

已知限制​

文件大小​

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

兼容性​

为实现互操作性，GCS ClickPipe 使用了 Cloud Storage 的 XML API，这要求使用 https://storage.googleapis.com/ 作为 bucket 前缀（而不是 gs://），并使用 HMAC keys 进行身份验证。

视图支持​

目标表上的 materialized view 也受支持。ClickPipes 不仅会为目标表创建 staging 表，还会为所有依赖它的 materialized view 创建 staging 表。

我们不会为非 materialized view 创建 staging 表。这意味着，如果你的目标表存在一个或多个下游的 materialized view，这些 materialized view 应避免通过中间的视图从目标表中选择数据。否则，你可能会发现在这些 materialized view 中出现数据缺失的情况。