将对象存储与 ClickHouse Cloud 集成
对象存储 ClickPipes 提供了一种简单且弹性的方式，将来自 Amazon S3、Google Cloud Storage、Azure Blob Storage 和 DigitalOcean Spaces 的数据导入到 ClickHouse Cloud。支持一次性和持续性数据输入，并具有精确一次的语义。
先决条件
您已熟悉 ClickPipes 简介。
创建您的第一个 ClickPipe
- 在云控制台中，选择左侧菜单上的
Data Sources按钮，并点击“设置 ClickPipe”
- 选择您的数据源。
- 填写表单，为您的 ClickPipe 提供名称、描述（可选）、您的 IAM 角色或凭据以及存储桶 URL。您可以使用类 bash 的通配符指定多个文件。有关更多信息，请 查看有关路径中使用通配符的文档。
- UI 将显示指定存储桶中的文件列表。选择您的数据格式（我们目前支持 ClickHouse 格式的子集），并选择是否要启用持续输入 更多细节如下。
- 在下一步中，您可以选择将数据输入到新的 ClickHouse 表中，或重用现有表。按照屏幕中的说明修改您的表名称、模式和设置。您可以在顶部的示例表中看到更改的实时预览。
您还可以使用提供的控件自定义高级设置
- 或者，您可以决定将数据输入到现有的 ClickHouse 表中。在这种情况下，UI 将允许您将字段从源映射到所选目标表中的 ClickHouse 字段。
您还可以将 虚拟列（如 _path 或 _size）映射到字段。
- 最后，您可以为内部 ClickPipes 用户配置权限。
权限： ClickPipes 将为写入目标表创建一个专用用户。您可以使用自定义角色或预定义角色之一选择该内部用户的角色：
全访问：具有对集群的完全访问权限。如果使用目标表的物化视图或字典，则需要此权限。仅目标表：仅对目标表具有INSERT权限。
- 通过点击“完成设置”，系统将注册您的 ClickPipe，您将能够在摘要表中看到它。
摘要表提供了在 ClickHouse 中显示源或目标表的示例数据的控件
以及用于删除 ClickPipe 和显示数据输入作业摘要的控件。
- 恭喜！ 您已成功设置第一个 ClickPipe。 如果这是一个流式 ClickPipe，它将持续运行，从您的远程数据源实时输入数据。否则，它将输入批处理并完成。
支持的数据源
| 名称 | Logo | 类型 | 状态 | 描述 |
|---|---|---|---|---|
| Amazon S3 | 对象存储 | 稳定 | 配置 ClickPipes 从对象存储中输入大量数据。 | |
| Google Cloud Storage | 对象存储 | 稳定 | 配置 ClickPipes 从对象存储中输入大量数据。 | |
| DigitalOcean Spaces | 对象存储 | 稳定 | 配置 ClickPipes 从对象存储中输入大量数据。 | |
| Azure Blob Storage | 对象存储 | 私有测试版 | 配置 ClickPipes 从对象存储中输入大量数据。 |
更多连接程序将添加到 ClickPipes，您可以通过 联系我们 了解更多信息。
支持的数据格式
支持的格式有：
精确一次语义
在输入大型数据集时可能会出现各种类型的故障，这可能导致部分插入或重复数据。对象存储 ClickPipes 具有抗插入失败的弹性，并提供精确一次的语义。这是通过使用临时“暂存”表来实现的。数据首先插入暂存表中。如果插入过程中出现问题，可以截断暂存表并从干净的状态重试插入。只有在插入完成并成功后，暂存表中的分区才会移动到目标表中。要了解有关该策略的更多信息，请查看 这篇博客文章。
视图支持
目标表上的物化视图也受到支持。ClickPipes 将为目标表创建暂存表，以及任何依赖的物化视图。
我们不会为非物化视图创建暂存表。这意味着如果您有一个目标表和一个或多个下游物化视图，那么这些物化视图应避免通过目标表的视图选择数据。否则，您可能会发现物化视图中缺少数据。
扩展性
对象存储 ClickPipes 的规模基于由 配置的垂直自动扩展设置 确定的最小 ClickHouse 服务大小。ClickPipe 的大小在创建管道时确定。对 ClickHouse 服务设置的后续更改不会影响 ClickPipe 的大小。
为了提高大型输入作业的吞吐量，我们建议在创建 ClickPipe 之前扩展 ClickHouse 服务。
限制
- 对目标表、其物化视图（包括级联物化视图）或物化视图的目标表的任何更改都可能导致临时错误，这将被重试。为了获得最佳结果，我们建议停止管道，进行必要的修改，然后重新启动管道，以便变更被采纳并避免错误。
- 支持的视图类型存在限制。有关更多信息，请阅读 精确一次语义 和 视图支持 部分。
- 对于在 GCP 或 Azure 部署的 ClickHouse Cloud 实例，不支持 S3 ClickPipes 的角色身份验证。仅支持 AWS ClickHouse Cloud 实例。
- ClickPipes 仅会尝试输入大小为 10GB 或更小的对象。如果文件大于 10GB，则会将错误追加到 ClickPipes 专用错误表中。
- 在包含超过 10 万个文件的容器上，Azure Blob Storage 管道的持续输入将有约 10-15 秒的延迟来检测新文件。延迟会随着文件数量的增加而增加。
- S3 / GCS ClickPipes 不 与 S3 表函数 共享列表语法，也不与 AzureBlobStorage 表函数 共享。
?— 替代任何单个字符*— 替代任何数量的任何字符，包括空字符串**— 替代任何数量的任何字符，包括空字符串
这是有效路径（对于 S3）：
https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz
这不是有效路径。{N..M} 在 ClickPipes 中不受支持。
https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/{documents-01,documents-02}.ndjson.gz
持续输入
ClickPipes 支持来自 S3、GCS、Azure Blob Storage 和 DigitalOcean Spaces 的持续输入。当启用时，ClickPipes 会连续从指定路径输入数据，并以每 30 秒一次的速度轮询新文件。然而，新文件必须在字典上大于上一个输入的文件。这意味着它们的命名方式必须定义输入顺序。例如，文件命名为 file1、file2、file3 等，将按顺序输入。如果添加了一个名为 file0 的新文件，ClickPipes 将不会输入它，因为它在字典上并不大于上一个输入的文件。
存档表
ClickPipes 将创建一个与目标表并列的表，后缀为 s3_clickpipe_<clickpipe_id>_archive。该表将包含 ClickPipe 已输入的所有文件的列表。该表用于在输入过程中跟踪文件，并可以用来验证文件是否已输入。存档表具有 7 天的 TTL。
这些表不会通过 ClickHouse Cloud SQL 控制台可见，您需要通过外部客户端连接，可以使用 HTTPS 或原生连接来读取它们。
身份验证
S3
您可以在没有配置的情况下访问公共存储桶，对于受保护的存储桶，您可以使用 IAM 凭据 或 IAM 角色。要使用 IAM 角色，您需要按照 本指南 中的说明创建 IAM 角色。在创建后复制新 IAM 角色的 Arn 并将其粘贴到 ClickPipe 配置中作为“IAM ARN 角色”。
GCS
与 S3 类似，您可以在没有配置的情况下访问公共存储桶，对于受保护的存储桶，您可以使用 HMAC 密钥 替代 AWS IAM 凭据。您可以阅读 Google Cloud 关于 如何设置此类密钥 的指南。
GCS 的服务账户不直接受支持。必须在对非公共存储桶进行身份验证时使用 HMAC（IAM）凭据。
附加到 HMAC 凭据的服务账户权限应为 storage.objects.list 和 storage.objects.get。
DigitalOcean Spaces
目前仅支持受保护的 DigitalOcean 空间存储桶。您需要“访问密钥”和“秘密密钥”来访问存储桶及其文件。您可以阅读 本指南 了解如何创建访问密钥。
Azure Blob Storage
目前仅支持受保护的 Azure Blob Storage 存储桶。身份验证通过连接字符串完成，该字符串支持访问密钥和共享密钥。有关更多信息，请阅读 本指南。
常见问题解答
- ClickPipes 支持以
gs://为前缀的 GCS 存储桶吗？
不支持。出于互操作性原因，我们要求您用 https://storage.googleapis.com/替换您的 gs:// 存储桶前缀。
- GCS 公共存储桶需要什么权限？
allUsers 需要适当的角色分配。在存储桶级别必须授予 roles/storage.objectViewer 角色。该角色提供 storage.objects.list 权限，允许 ClickPipes 列出存储桶中的所有对象，这是注册和输入所必需的。该角色还包括 storage.objects.get 权限，这对于读取或下载存储桶中的单个对象是必需的。有关更多信息，请参阅 Google Cloud 访问控制。
