配置 ClickHouse 数据源
ClickHouse 数据源用于通过离线同步在 ClickHouse 与平台预置仓之间传输表数据。本文介绍连接配置、双向来源与去向设置、支持的字段类型,以及同步验证和任务流调度。
接入前准备与使用限制
支持的版本
ClickHouse 24.0 及以上版本。
准备事项
开始配置前,请确认以下事项:
- 支持 ClickHouse → 预置仓 和 预置仓 → ClickHouse,不支持在本方案中将 ClickHouse 与其他外部数据源直接互传。
- 准备 ClickHouse 的 服务地址/IP、端口、数据库名、用户名 和 密码。平台运行环境需能够访问对应服务;存在网络访问限制时,请核对平台服务器的实际出口地址与允许访问范围。
- 接入账号需有权访问数据库并查看所选表的元数据。读取来源表需有读取权限,写入目标表需有相应写入权限;使用分布式表时,还需能够获取相应的集群和分片信息。
- 提前准备目标表,并核对字段类型、空值约束和分区定义。预置仓目标表的创建方式参见 空间表的创建与管理;ClickHouse 目标表需在对应数据库中预先创建。
- 以表选择器中可用的表为准。Aggregating 类引擎表和物化视图不作为普通可选表使用;不要将 ClickHouse 支持的全部引擎或类型视为本方案都可同步。
| 环境配置方式 | 配置要求 |
|---|---|
| 不区分环境 | 开发环境与生产环境共用一套连接及凭据配置 |
| 独立环境配置 | 分别配置开发环境与生产环境;两套配置均需能够访问方案所选的库表 |
数据预览使用开发环境配置,手动执行使用生产环境配置。请分别核对两套配置的服务地址、库表权限及网络访问。通过安全方式交接密码,避免将凭据写入截图、日志或公开文档。
创建 ClickHouse 数据源
- 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
- 选择 ClickHouse,点击 下一步,填写数据源名称和备注。
- 选择 不区分环境 或 独立环境配置。独立环境配置需分别填写开发环境和生产环境的信息。
- 填写以下连接参数。在 连通性测试 中点击 测试,确认测试通过后,点击 完成。
| 配置项 | 说明 |
|---|---|
| 数据源名称 | 当前空间中用于识别该连接的名称;创建后不可修改 |
| 备注 | 选填,可说明连接用途 |
| 服务地址/IP | ClickHouse 服务主机的地址,多个地址用英文逗号分隔;端口在下方独立填写,不在地址中重复填写 |
| 端口 | 用于访问 ClickHouse 的服务端口,请向管理员确认 |
| 数据库名 | 已在 ClickHouse 中创建、且接入账号有权访问的数据库 |
| 用户名 | 具备本次读取或写入所需权限的账号 |
| 密码 | 与用户名对应的密码 |
| 高级配置 | 按需填写 JSON 格式的扩展配置;没有额外配置要求时可留空 |
连通性测试通过后,还需在同步方案中加载库表、预览来源数据并执行验证,确认实际表权限和读写结果。更换密码或调整数据库权限后,应重新验证连接和相关方案。
配置数据来源
ClickHouse 读取到预置仓
- 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
- 在 数据来源 中选择 ClickHouse 和已创建的数据源。
- 选择 取数方式,按整表读取或自定义查询配置来源。
- 点击 数据预览,核对来源字段、实际值和读取范围。
- 在 数据去向 中选择平台 预置仓,再选择目标空间表,并配置目标分区及写入模式。
| 取数方式 | 配置方法 |
|---|---|
| 整表 | 选择数据库和数据表;如只读取部分数据,开启 数据过滤 并填写过滤条件 |
| 自定义查询 | 填写返回待同步字段的只读查询 SQL,将筛选条件写在查询中;此方式不单独配置整表的数据库、数据表选择项或数据过滤 |
整表方式的数据过滤需填写包含 WHERE 的完整条件,例如 WHERE status = 'active',不填写完整的 SELECT 查询。自定义查询需核对所访问的数据库,必要时在 SQL 中明确库名和表名,并保证返回的字段名称明确、类型可识别。
| 预置仓去向配置项 | 说明 |
|---|---|
| 目标表 | 接收本次数据的预置仓空间表;不存在时先前往 库表 创建 |
| 分区信息 | 目标为分区表时,按目标表要求填写分区值;可结合 空间参数 配置执行时的分区 |
| 写入模式 | 按目标数据保留要求选择 插入新数据 或 覆盖写入,执行前再次核对目标表、目标分区及保留数据的要求 |
切换数据源、数据库、数据表或取数方式后,请重新核对读取范围、预览结果和字段映射。来源表结构或查询结果发生变化后,也需重新解析并检查映射。
配置数据去向
预置仓写入 ClickHouse
在 数据来源 中配置预置仓来源表,在 数据去向 中选择 ClickHouse 和已创建的数据源,再选择 ClickHouse 的目标数据库和数据表。
| 配置项 | 说明 |
|---|---|
| 数据源名称 | 当前空间已创建的 ClickHouse 数据源;尚未创建时,可前往 数据源管理 配置 |
| 数据库名 | 本次写入的 ClickHouse 数据库 |
| 数据表名 | 已在 ClickHouse 中准备、且接入账号有权写入的目标表 |
| 使用分片字段 | 符合下述分片条件时可开启;开启前需在字段映射中包含对应的目标分片字段 |
| 写入模式 | 仅支持 插入新数据,向目标表追加数据;重复执行前需评估是否产生重复记录 |
| 批量条数 | 位于 高级配置 中,界面默认值为 20000,可设置范围为 10000–100000 |
ClickHouse 去向不提供覆盖写入或更新插入模式。需要按相同来源范围重试时,请先核对历史执行结果及目标数据,避免重复追加。
使用分片字段
分片能力用于向符合条件的分布式表写入数据,需同时满足:
- 目标表为 Distributed 引擎表,相应集群开启
internal_replication。 - 平台能够识别目标表使用的分片字段。不能将任意分片表达式视为可直接选择的字段。
- 字段映射中包含该目标分片字段,并已建立有效的来源对应关系。
符合条件后,开启 使用分片字段。如果开关不可用,请检查目标表、集群配置和字段映射。切换目标库表或移除分片字段映射后,应重新核对该设置。
字段映射与支持的字段类型
完成来源和去向配置后,在 字段映射 中建立源字段与目标字段的对应关系。可以逐项选择,也可以使用 同名映射 或 同行映射 后逐项核对;一个目标字段只能对应一个来源字段。
图中展示的是已有方案的字段对应关系,不能替代当前连接、字段解析和实际同步结果的验证。
读取支持的字段类型
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 官方数据类型说明。数据库支持的类型不等于本方案均支持。来源或目标表结构变化后,请重新解析字段并核对字段对应关系;数据预览可见也不能替代同步验证。
保存、验证与调度
基本信息与同步验证
- 核对来源表或查询、过滤范围、目标表及分区、写入模式和字段映射。先使用来源 数据预览 检查字段与样例值。
- 填写方案名称、负责人、同步速率及备注,点击 保存。方案名称保存后不可修改。
- 点击 手动执行,按弹窗要求选择执行模式,并核对本次参数值后开始执行。手动执行使用生产环境配置;执行模式不用于切换开发环境与生产环境。
- 在 手动执行记录 中查看状态和日志。任务成功后,到目标表核对数据量、字段对应关系,以及数值、时间、复杂类型和空值等样例。
独立环境配置下,开发环境能够加载或预览数据,不代表生产环境凭据和读写权限也已具备。首次执行前,请分别核对两套配置的库表、分区和参数。向预置仓覆盖写入时确认目标范围,向 ClickHouse 追加写入时评估重试和重复执行的影响。
挂载任务流
手动验证通过后,可将方案挂载到任务流,按调度周期执行。
- 打开已保存的方案,点击 挂载到任务流,选择目标任务流。没有对应任务流时,可从选择器新建,或参见 创建任务流;列表未显示目标任务流时,可刷新后再选择。
- 填写节点名、执行模式、负责人等信息,点击 创建节点并挂载,创建关联当前方案的 离线同步方案 节点。
- 点击 前往任务流,检查节点及上下游依赖,核对调度所用的库表、分区和空间参数。
- 完成 任务流调度设置,保存并 发布任务流。挂载成功不等于节点已经发布上线。
方案挂载到任务流后,不再通过方案详情页手动执行,请从任务流中执行和验证该节点。
解除任务流挂载
- 任务流尚未发布时,在任务流的 开发模式 中删除对应的 离线同步方案 节点即可。
- 任务流已经发布时,先在 开发模式 中删除对应节点,再重新发布任务流,才能解除该节点在生产环境中的挂载。
常见问题
| 现象 | 检查项 |
|---|---|
| 连通性测试失败 | 核对服务地址、独立端口、数据库、账号密码及平台服务器网络访问范围 |
| 连接通过,但找不到表或无法预览 | 核对库表名、元数据及读取权限、表引擎是否可选;自定义查询还需核对 SQL 的数据库与字段类型 |
| 分片开关不可用 | 核对 Distributed 表、集群 internal_replication、可识别分片字段,以及映射中是否包含该目标字段 |
| 预览正常,但执行失败 | 核对生产环境凭据、目标写入权限、库表及分区、参数和实际执行日志 |
| 重复执行后出现重复记录 | 核对追加写入范围及历史执行结果,确认是否重复读取和写入同一批数据 |

