跳至主要内容

ClickHouse

可用性
可用 核心可用 标准可用 Plus可用 Pro可用 Enterprise Flex可用 自托管 Enterprise可用 PyAirbyte
支持级别
Airbyte
连接器版本
2.1.20 (上次更新 8 天前)
同步成功率
使用率
定义 ID
ce0d828e-1dc4-496c-b122-2da42e637e48

ClickHouse 目标连接器将数据从 Airbyte 源同步到 ClickHouse，这是一种专为在线分析处理 (OLAP) 设计的高性能列式数据库。此连接器直接将数据写入 ClickHouse 表，并进行适当的类型化，从而实现对复制数据的快速分析查询。

这是一个基于 Airbyte 的 Bulk CDK 框架完全重写的 ClickHouse 目标连接器，取代了旧版 v1 连接器。

版本 2 如何改进版本 1​

版本 2.0.0 代表 ClickHouse 目标连接器的完全架构重新设计，具有显著的改进

  • 支持所有同步模式：完全刷新（覆盖和追加）和增量（追加和追加 + 去重）同步模式现在完全支持。
  • 直接加载与类型化列：Airbyte 将数据直接写入与源模式匹配的类型化列，而不是将所有内容作为原始表中的 JSON 存储。这提高了查询性能并减少了存储需求。
  • 改进的性能：新的架构使用 ClickHouse 的本机二进制协议和批量插入，以实现更快的数据加载。
  • 积极维护：基于 Airbyte 的现代 CDK 框架构建，并由 Airbyte 团队提供持续的开发和支持。

支持的同步模式​

连接器支持所有同步模式。

功能支持？(是/否)备注
完全刷新同步是
增量 - 追加同步是
增量 - 追加 + 去重是利用 ReplacingMergeTree
命名空间是

去重​

为了在增量 - 追加 + 去重同步模式中实现最佳去重，请使用带有以下类型之一的游标列

  • 整数类型 (Int64 等)
  • 日期
  • 时间戳 (DateTime64)

如果使用不同的游标列类型，例如 string，则连接器将回退到使用 _airbyte_extracted_at 时间戳进行去重排序。此回退可能无法准确反映源数据的自然顺序，并且您会在同步日志中看到警告。

警告

Airbyte 的 ClickHouse 连接器利用 ReplacingMergeTree 表引擎来处理去重。为了保证查询时的去重结果，您可以将 FINAL 操作符添加到您的查询字符串中。例如

SELECT * FROM your_table FINAL

如果没有此操作符，在查询数据时可能会看到重复或已删除的结果。

或者，您也可以 调整您的合并设置，以更好地匹配您的查询模式。

要求​

要使用 ClickHouse 目标连接器，您需要

  • 一个 ClickHouse 实例（ClickHouse Cloud 或自托管）
  • ClickHouse 服务器版本 21.8.10.19 或更高版本
  • 从 Airbyte 到您的 ClickHouse 实例的网络访问权限
  • 具有适当权限的 ClickHouse 用户（如下所示）

设置指南​

1. 配置网络访问​

确保您的 ClickHouse 数据库可以从 Airbyte 访问。

Airbyte 部署Clickhouse 部署执行此操作
云云在您的 ClickHouse Cloud 设置中白名单 Airbyte Cloud 的 IP 地址。
云自托管配置您的防火墙以允许从 Airbyte Cloud 的 IP 地址传入的连接，端口为 8443（HTTPS）或 8123（HTTP）。
自托管云将您的 Airbyte 服务器的公共 IP 地址列入 ClickHouse Cloud 设置的白名单。
自托管自托管确保端口 8443（HTTPS）或 8123（HTTP）可从您的 Airbyte 主机访问。如果两者位于同一私有网络中，请配置安全组或防火墙规则以允许它们之间的流量。

如果您无法公开 ClickHouse，请使用可以通过到达 ClickHouse 的堡垒主机通过 SSH 隧道进行连接。

2. 创建具有权限的专用用户​

提示

最好为 Airbyte 创建一个专用的 ClickHouse 用户，而不是使用现有用户。这可以提高安全性并简化 Airbyte 数据库操作的审计。

为 Airbyte 创建一个 ClickHouse 用户，并具有以下权限

  • 创建和管理数据库
  • 创建、更改、删除和截断表
  • 插入和选择数据

要在您的 ClickHouse 实例中创建具有所需权限的用户，请运行以下 SQL 命令

-- Create the user (replace 'your_password' with a secure password)
CREATE USER airbyte_user IDENTIFIED BY 'your_password';

-- If async_insert is enabled in ClickHouse, disable it for the Airbyte user to ensure connection checks and data syncs work correctly. This fixes the "Error: Failed to insert expected rows into check table. Actual written: 0" error.
ALTER USER airbyte_user SETTINGS async_insert = 0;

-- Grant permissions on the default database
GRANT CREATE ON * TO airbyte_user;
GRANT CREATE ON {database}.* TO airbyte_user;
GRANT ALTER ON {database}.* TO airbyte_user;
GRANT TRUNCATE ON {database}.* TO airbyte_user;
GRANT INSERT ON {database}.* TO airbyte_user;
GRANT SELECT ON {database}.* TO airbyte_user;
GRANT CREATE DATABASE ON {database}.* TO airbyte_user;
GRANT CREATE TABLE ON {database}.* TO airbyte_user;
GRANT DROP TABLE ON {database}.* TO airbyte_user;

将 {database} 替换为您在连接器设置中配置的数据库名称。通常为 default。

如果您配置了自定义命名空间，请为每个命名空间授予权限

GRANT CREATE ON {namespace}.* TO airbyte_user;
GRANT ALTER ON {namespace}.* TO airbyte_user;
GRANT TRUNCATE ON {namespace}.* TO airbyte_user;
GRANT INSERT ON {namespace}.* TO airbyte_user;
GRANT SELECT ON {namespace}.* TO airbyte_user;
GRANT CREATE DATABASE ON {namespace}.* TO airbyte_user;
GRANT CREATE TABLE ON {namespace}.* TO airbyte_user;
GRANT DROP TABLE ON {namespace}.* TO airbyte_user;

将 {namespace} 替换为您计划使用的每个自定义命名空间。

3. 配置连接器​

  1. 在 Airbyte 中，单击 目标 > ClickHouse。

  2. 使用以下信息配置目标。

    • 主机名：您的 ClickHouse 服务器主机名（没有协议前缀，例如 http:// 或 https://）
    • 端口：ClickHouse 的 HTTP 端口（HTTP 的默认值为 8123，HTTPS 的默认值为 8443）
    • 协议（仅限自托管）：选择 HTTP 或 HTTPS。在 Airbyte Cloud 中，此选项被隐藏并由平台管理。
    • 数据库：目标数据库名称（默认：default）
    • 用户名：您创建的 ClickHouse 用户（例如，airbyte_user）
    • 密码：ClickHouse 用户的密码
    • 启用 JSON：是否在 ClickHouse 中使用 JSON 类型来表示对象字段（如果您的 ClickHouse 版本支持，则推荐）

4. SSH 隧道（可选）​

警告

SSH 隧道支持目前处于 Beta 阶段。

如果您的 ClickHouse 实例无法直接从 Airbyte 访问，您可以使用 SSH 隧道建立安全连接。使用 SSH 主机、端口、用户名和身份验证方法（密码或私钥）在连接器配置中配置 SSH 隧道设置。

输出 schema​

Airbyte 将每个流写入 ClickHouse 中的一个表。它在您配置的默认数据库中创建表，通常为 default，或者在您在设置连接时为流指定的命名空间中创建数据库。

连接器将 Airbyte 数据类型转换为 ClickHouse 类型，如下所示

  • Decimal 类型 → Decimal(38, 9)（38 位精度，9 位小数）
  • Timestamp 类型 → DateTime64(3)（毫秒精度）
  • Object 类型 → 如果您在连接器配置中启用了 JSON，则为 JSON，否则为 String
  • Integer 类型 → Int64
  • Boolean 类型 → Bool
  • String 类型 → String
  • Union 类型 → String
  • Array 类型 → String
注意

连接器将数组和联合转换为字符串以实现兼容性。如果您需要将它们作为结构化数据进行查询，请使用 ClickHouse 的 JSON 函数来解析字符串值。

参考​

配置字段参考

字段
类型
属性名称
字符串
database
字符串
host
字符串
password
字符串
port
字符串
protocol
字符串
username
布尔值
enable_json
整数
record_window_size
对象
tunnel_method

变更日志​

展开以查看
版本日期拉取请求主题
2.1.202026-01-1571120添加模式和表标识回归测试；升级 CDK 到 0.1.105
2.1.192026-01-0870996升级到 CDK 0.1.97
2.1.182025-12-1770963内部重构：删除名称生成器类，简化命名实用程序
2.1.172025-12-1070835修复：跳过 CDC 游标以考虑去重的版本列。
2.1.162025-12-1270897推广发布候选版本 2.1.16-rc.3 到主版本。
2.1.16-rc.32025-12-0970835获取 CDK 修复，用于命名空间 / 前缀处理
2.1.16-rc.22025-12-0970358内部重构：继续使用 TableSchemaMapper 进行模式操作
2.1.16-rc.12025-12-0470279内部重构：使用 TableSchemaMapper 进行模式操作
2.1.152025-12-1669829将 ClickHouse 客户端升级到 0.9.4
2.1.142025-11-1369245升级到 CDK 0.1.78
2.1.132025-11-1169116升级到 CDK 0.1.74（内部重构，用于模式演进）
2.1.122025-11-0669226改进了附加统计信息处理
2.1.112025-11-0569200添加了可观测性指标的支持
2.1.102025-11-0469154修复了十进制验证
2.1.92025-11-0369100升级到 CDK 0.1.61 以修复状态索引错误
2.1.82025-10-2968186升级到 CDK 0.1.59
2.1.72025-10-2167153实现新的 proto 模式实现
2.1.62025-10-1668144实现了 TableOperationsSuite 组件测试。
2.1.52025-10-1067598改进了对高度交错流的处理。
2.1.42025-09-2966743激活加速模式。
2.1.32025-09-2966743将发布候选版本 2.1.3-rc.1 提升为主要版本。
2.1.3-rc.12025-09-2566699为加速模式做准备。修复了交错流状态处理。
2.1.22025-09-0966143改进了模式传播。
2.1.12025-09-0966134将我们为数字类型设置的类型更新为 Decimal(38, 9)。
2.1.02025-09-0365929将发布候选版本 2.1.0-rc.2 提升为主要版本。
2.1.0-rc.22025-08-29#65626采纳 CDK 修复了罕见的数组越界异常。
2.1.0-rc.12025-08-21#65144迁移到数据流模型。
2.0.132025-08-20#65125更新文档权限建议。
2.0.122025-08-20#65120检查应该正确显示与协议相关的配置错误。
2.0.112025-07-23#65117修复了与列重复名称相关的错误。
2.0.102025-07-23#64104添加了一个选项来配置批处理大小（字节数和记录数）。
2.0.92025-07-23#63738将 ClickHouse 设置为 Airbyte 连接器。
2.0.82025-07-23#63760如果在第一次同步之前存在无效的目标表，则抛出错误。
2.0.72025-07-23#63751仅在存在去重更改时复制交叉列。
2.0.62025-07-22#63724为列应用 ClickHouse 列名转换。
2.0.52025-07-22#63721修复了带有主键的模式更改。
2.0.42025-07-21#62948SSH 支持 BETA。
2.0.32025-07-11#62946发布元数据更改。
2.0.22025-07-10#62928为了解决 UI 问题，使 spec 中的 json 可选。
2.0.12025-07-10#62906为包含协议的旧版主机名添加了定制的验证。
2.0.02025-07-10#62887发布 2.0.0 版本。替换现有连接器。
0.1.112025-07-09#62883仅在启用时才在客户端上设置 JSON 属性，以支持旧的 CH 部署。
0.1.102025-07-08#62861设置内部 CH 遥测的用户代理标头。
0.1.92025-07-03#62509简化了联合字符串化的行为。
0.1.82025-06-30#62100添加了 JSON 支持。
0.1.72025-06-24#62047删除了内部命名空间的使用。
0.1.62025-06-24#62047在云端运行时隐藏协议选项。
0.1.52025-06-24#62043公开数据库协议配置选项。
0.1.42025-06-24#62040检查器插入到配置的数据库中。
0.1.32025-06-24#62038允许客户端连接到解析后的数据库。
0.1.22025-06-23#62028在 OSS 和云端启用注册表。
0.1.12025-06-23#62022发布第一个 beta 版本并固定 CDK 版本。
0.1.02025-06-23#62024发布第一个 beta 版本。
此页面是否有帮助？