跳到主要内容

配置 ClickHouse 数据源

最近更新 2026/11/03

ClickHouse 数据源用于通过离线同步在 ClickHouse 与平台预置仓之间传输表数据。本文介绍连接配置、双向来源与去向设置、支持的字段类型,以及同步验证和任务流调度。

接入前准备与使用限制​

支持的版本​

ClickHouse 24.0 及以上版本。

准备事项​

开始配置前,请确认以下事项:

  • 支持 ClickHouse → 预置仓 和 预置仓 → ClickHouse,不支持在本方案中将 ClickHouse 与其他外部数据源直接互传。
  • 准备 ClickHouse 的 服务地址/IP、端口、数据库名、用户名 和 密码。平台运行环境需能够访问对应服务;存在网络访问限制时,请核对平台服务器的实际出口地址与允许访问范围。
  • 接入账号需有权访问数据库并查看所选表的元数据。读取来源表需有读取权限,写入目标表需有相应写入权限;使用分布式表时,还需能够获取相应的集群和分片信息。
  • 提前准备目标表,并核对字段类型、空值约束和分区定义。预置仓目标表的创建方式参见 空间表的创建与管理;ClickHouse 目标表需在对应数据库中预先创建。
  • 以表选择器中可用的表为准。Aggregating 类引擎表和物化视图不作为普通可选表使用;不要将 ClickHouse 支持的全部引擎或类型视为本方案都可同步。
环境配置方式配置要求
不区分环境开发环境与生产环境共用一套连接及凭据配置
独立环境配置分别配置开发环境与生产环境;两套配置均需能够访问方案所选的库表

数据预览使用开发环境配置,手动执行使用生产环境配置。请分别核对两套配置的服务地址、库表权限及网络访问。通过安全方式交接密码,避免将凭据写入截图、日志或公开文档。

创建 ClickHouse 数据源​

  1. 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
  2. 选择 ClickHouse,点击 下一步,填写数据源名称和备注。
  3. 选择 不区分环境 或 独立环境配置。独立环境配置需分别填写开发环境和生产环境的信息。
  4. 填写以下连接参数。在 连通性测试 中点击 测试,确认测试通过后,点击 完成。
配置 ClickHouse 服务地址、端口和访问凭据
配置项说明
数据源名称当前空间中用于识别该连接的名称;创建后不可修改
备注选填,可说明连接用途
服务地址/IPClickHouse 服务主机的地址,多个地址用英文逗号分隔;端口在下方独立填写,不在地址中重复填写
端口用于访问 ClickHouse 的服务端口,请向管理员确认
数据库名已在 ClickHouse 中创建、且接入账号有权访问的数据库
用户名具备本次读取或写入所需权限的账号
密码与用户名对应的密码
高级配置按需填写 JSON 格式的扩展配置;没有额外配置要求时可留空

连通性测试通过后,还需在同步方案中加载库表、预览来源数据并执行验证,确认实际表权限和读写结果。更换密码或调整数据库权限后,应重新验证连接和相关方案。

配置数据来源​

ClickHouse 读取到预置仓​

  1. 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
  2. 在 数据来源 中选择 ClickHouse 和已创建的数据源。
  3. 选择 取数方式,按整表读取或自定义查询配置来源。
  4. 点击 数据预览,核对来源字段、实际值和读取范围。
  5. 在 数据去向 中选择平台 预置仓,再选择目标空间表,并配置目标分区及写入模式。
取数方式配置方法
整表选择数据库和数据表;如只读取部分数据,开启 数据过滤 并填写过滤条件
自定义查询填写返回待同步字段的只读查询 SQL,将筛选条件写在查询中;此方式不单独配置整表的数据库、数据表选择项或数据过滤

整表方式的数据过滤需填写包含 WHERE 的完整条件,例如 WHERE status = 'active',不填写完整的 SELECT 查询。自定义查询需核对所访问的数据库,必要时在 SQL 中明确库名和表名,并保证返回的字段名称明确、类型可识别。

预置仓去向配置项说明
目标表接收本次数据的预置仓空间表;不存在时先前往 库表 创建
分区信息目标为分区表时,按目标表要求填写分区值;可结合 空间参数 配置执行时的分区
写入模式按目标数据保留要求选择 插入新数据 或 覆盖写入,执行前再次核对目标表、目标分区及保留数据的要求

切换数据源、数据库、数据表或取数方式后,请重新核对读取范围、预览结果和字段映射。来源表结构或查询结果发生变化后,也需重新解析并检查映射。

配置数据去向​

预置仓写入 ClickHouse​

在 数据来源 中配置预置仓来源表,在 数据去向 中选择 ClickHouse 和已创建的数据源,再选择 ClickHouse 的目标数据库和数据表。

已有方案中的 ClickHouse 写入表、分片字段和批量条数
配置项说明
数据源名称当前空间已创建的 ClickHouse 数据源;尚未创建时,可前往 数据源管理 配置
数据库名本次写入的 ClickHouse 数据库
数据表名已在 ClickHouse 中准备、且接入账号有权写入的目标表
使用分片字段符合下述分片条件时可开启;开启前需在字段映射中包含对应的目标分片字段
写入模式仅支持 插入新数据,向目标表追加数据;重复执行前需评估是否产生重复记录
批量条数位于 高级配置 中,界面默认值为 20000,可设置范围为 10000–100000

ClickHouse 去向不提供覆盖写入或更新插入模式。需要按相同来源范围重试时,请先核对历史执行结果及目标数据,避免重复追加。

使用分片字段​

分片能力用于向符合条件的分布式表写入数据,需同时满足:

  • 目标表为 Distributed 引擎表,相应集群开启 internal_replication。
  • 平台能够识别目标表使用的分片字段。不能将任意分片表达式视为可直接选择的字段。
  • 字段映射中包含该目标分片字段,并已建立有效的来源对应关系。

符合条件后,开启 使用分片字段。如果开关不可用,请检查目标表、集群配置和字段映射。切换目标库表或移除分片字段映射后,应重新核对该设置。

字段映射与支持的字段类型​

完成来源和去向配置后,在 字段映射 中建立源字段与目标字段的对应关系。可以逐项选择,也可以使用 同名映射 或 同行映射 后逐项核对;一个目标字段只能对应一个来源字段。

已有 ClickHouse 方案中的字段对应关系示例

图中展示的是已有方案的字段对应关系,不能替代当前连接、字段解析和实际同步结果的验证。

读取支持的字段类型​

ClickHouse 作为数据来源时,支持以下能够正确解析的基础类型。带参数或包装的类型还需满足下方的使用限制。

类型类别支持的 ClickHouse 字段类型
布尔Bool、boolean
整数Int8、UInt8、Int16、UInt16、Int32、UInt32、Int64、UInt64、Int128、UInt128、Int256、UInt256
浮点Float32、Float64
定点数Decimal、Decimal32、Decimal64、Decimal128、Decimal256
字符串与枚举String、FixedString、Enum、Enum8、Enum16
日期时间Date、DateTime、DateTime32、DateTime64
地理类型Point、Ring、Polygon
间隔IntervalYear、IntervalQuarter、IntervalMonth、IntervalWeek、IntervalDay、IntervalHour、IntervalMinute、IntervalSecond
复杂类型Array、Map,需核对完整结构

不支持 Nested、UUID、IPv4、IPv6、Date32、MultiPolygon 等未列出的类型及其他未识别的类型。Tuple、Nullable(T) 和 LowCardinality(T) 的限制见下文,不能按名称直接判断支持。

写入支持的字段类型​

ClickHouse 作为数据去向时,支持的基础类型与上表相同,不支持的类型也相同。目标表需预先创建,字段的参数、完整结构和约束需符合实际写入要求。

MATERIALIZED、EPHEMERAL、ALIAS 等只读生成字段不能作为普通写入字段配置。这是字段种类限制,与字段本身的数据类型无关。

字段类型使用限制​

类型或场景支持条件与限制
整数、定点数、固定字符串及枚举核对完整取值范围、精度、小数位数、长度及枚举允许值;列入基础类型范围不表示所有字段定义和实际值均适用
带参数类型整表与自定义查询的字段解析结果可能不同。数字长度或精度参数需核对完整定义;包含时区文本的时间类型和带允许值的枚举类型,需确认当前取数方式下能够正确解析
Nullable(T)仅外层包装可按内部类型识别;内部类型仍需受支持,并核对目标字段的空值约束。不能推广到所有嵌套包装形式
LowCardinality(T)不保证自动识别内部类型;需检查当前字段解析和可用状态,不能仅凭内部类型受支持就判断该包装类型可用
Tuple(...)不保证带参数的 Tuple 能够正确识别;以当前完整字段定义和解析结果为准,不作为无条件支持类型列出
Array、Map 及嵌套结构核对完整的元素、键值定义及空值约束;顶层类型受支持不表示任意内部结构均受支持

ClickHouse 类型定义可参见 ClickHouse 官方数据类型说明。数据库支持的类型不等于本方案均支持。来源或目标表结构变化后,请重新解析字段并核对字段对应关系;数据预览可见也不能替代同步验证。

保存、验证与调度​

基本信息与同步验证​

  1. 核对来源表或查询、过滤范围、目标表及分区、写入模式和字段映射。先使用来源 数据预览 检查字段与样例值。
  2. 填写方案名称、负责人、同步速率及备注,点击 保存。方案名称保存后不可修改。
  3. 点击 手动执行,按弹窗要求选择执行模式,并核对本次参数值后开始执行。手动执行使用生产环境配置;执行模式不用于切换开发环境与生产环境。
  4. 在 手动执行记录 中查看状态和日志。任务成功后,到目标表核对数据量、字段对应关系,以及数值、时间、复杂类型和空值等样例。

独立环境配置下,开发环境能够加载或预览数据,不代表生产环境凭据和读写权限也已具备。首次执行前,请分别核对两套配置的库表、分区和参数。向预置仓覆盖写入时确认目标范围,向 ClickHouse 追加写入时评估重试和重复执行的影响。

挂载任务流​

手动验证通过后,可将方案挂载到任务流,按调度周期执行。

  1. 打开已保存的方案,点击 挂载到任务流,选择目标任务流。没有对应任务流时,可从选择器新建,或参见 创建任务流;列表未显示目标任务流时,可刷新后再选择。
  2. 填写节点名、执行模式、负责人等信息,点击 创建节点并挂载,创建关联当前方案的 离线同步方案 节点。
  3. 点击 前往任务流,检查节点及上下游依赖,核对调度所用的库表、分区和空间参数。
  4. 完成 任务流调度设置,保存并 发布任务流。挂载成功不等于节点已经发布上线。

方案挂载到任务流后,不再通过方案详情页手动执行,请从任务流中执行和验证该节点。

解除任务流挂载​

  • 任务流尚未发布时,在任务流的 开发模式 中删除对应的 离线同步方案 节点即可。
  • 任务流已经发布时,先在 开发模式 中删除对应节点,再重新发布任务流,才能解除该节点在生产环境中的挂载。

常见问题​

现象检查项
连通性测试失败核对服务地址、独立端口、数据库、账号密码及平台服务器网络访问范围
连接通过,但找不到表或无法预览核对库表名、元数据及读取权限、表引擎是否可选;自定义查询还需核对 SQL 的数据库与字段类型
分片开关不可用核对 Distributed 表、集群 internal_replication、可识别分片字段,以及映射中是否包含该目标字段
预览正常,但执行失败核对生产环境凭据、目标写入权限、库表及分区、参数和实际执行日志
重复执行后出现重复记录核对追加写入范围及历史执行结果,确认是否重复读取和写入同一批数据
这篇文档对你有帮助吗?