You need to enable JavaScript to run this app.
导航
配置 ClickHouse 数据源
最近更新时间:2024.10.18 11:53:47首次发布时间:2023.11.01 17:27:16

DataSail 中的 ClickHouse 数据源,为您提供读取和写入 ClickHouse 的双向通道数据集成能力,实现不同数据源与 ClickHouse 之间进行数据传输。
本文为您介绍 DataSail 的 ClickHouse 数据同步的能力支持情况。

1 支持的 ClickHouse 版本

支持 ClickHouse 20.X 以上自建开源版本。

2 使用限制

  1. 子账号新建数据源时,需要有项目的管理员角色,方可以进行新建数据源操作。各角色对应权限说明,详见:管理成员
  2. 目前支持离线读取和离线写入 ClickHouse 场景。

3 支持的字段类型

数据类型

是否支持

  • Int8
  • Int16
  • Int32
  • Int64
  • UInt8
  • UInt16
  • UInt32
  • UInt64

支持

Float64

支持

Decimal

支持

Date

支持

datetime

支持

String

支持

Array

支持

4 数据同步任务开发

下文将为您介绍数据集成任务配置的详细流程。

4.1 数据源注册

新建数据源操作详见配置数据源,下面为您介绍通过连接串形式配置 ClickHouse 数据源:

参数

说明

基本配置

数据源类型

ClickHouse

接入方式

连接串

数据源名称

数据源的名称,可自行设置,仅支持中文,英文,数字,“_”,100个字符以内。

参数配置

主机名或 IP 地址

ClickHouse 数据库的主机名称或者 IP 地址。

端口

输入 ClickHouse 主机的端口号。

数据库名

下拉选择已在 ClickHouse 中创建的数据库名称信息。

用户名

有权限访问数据库的用户名信息。

密码

输入用户名对应的密码信息。

4.2 新建离线任务

ClickHouse 数据源测试连通性成功后,进入到数据开发界面,开始新建 ClickHouse 相关通道任务。
新建任务方式详见离线数据同步

4.3 可视化配置说明

任务创建成功后,您可根据实际场景,配置 ClickHouse 离线读ClickHouse 离线写等通道任务。

4.3.1 ClickHouse 离线读

Image
数据来源选择 ClickHouse,并完成以下相关参数配置:
其中参数名称前带 * 的为必填参数,名称前未带 * 的为可选填参数。

参数

说明

*数据源类型

下拉选择 ClickHouse 数据源类型。

*数据源名称

已在数据源管理中注册成功的 ClickHouse 数据源,下拉可选。
若还未建立相应数据源,可单击数据源管理按钮,前往创建 ClickHouse 数据源。

*数据表

选择需要采集的数据表名称信息,目前单个任务只支持将单表的数据采集到一个目标表中。

数据过滤

可自定义配置全量或增量读取数据源:

  • 如果不配置数据过滤,默认会同步全量数据。
  • 增量读取时您将需要同步的数据进行筛选条件设置,只同步符合过滤条件的数据,可直接填写关键词 where 后的过滤 SQL 语句且无需填写结束符号(;),例如:create_time > '${date}',表示只同步 create_time 大于等于 ${date} 的数据,不需要填写 where 关键字。
    语句填写完成后,您可单击右侧的校验按钮,进行过滤语句校验。

    说明

    该过滤语句通常用作增量同步,暂时不支持 limit 关键字过滤,其 SQL 语法需要和选择的数据源类型对应。

切分建

根据配置的字段进行数据分片,建议使用主键或有索引的列作为切分键:

  • 如果表没有主键或者索引列,可以不配置该字段,同步任务不会进行分片,并以单并发的方式同步所有的数据;
  • 建议使用主键或有索引的列作为切分键,切分键配置没有索引的列同步任务会比较慢;

说明

目前仅支持类型为整型或字符串的字段作为切分建。

4.3.2 ClickHouse 离线写

Image
数据来源选择 ClickHouse,并完成以下相关参数配置:
其中参数名称前带 * 的为必填参数,名称前未带 * 的为可选填参数。

参数

说明

*目标类型

数据去向目标类型选择 ClickHouse。

*数据源名称

已在数据源管理界面注册的 ClickHouse 数据源,下拉可选。
若还未建立相应数据源,可单击数据源管理按钮,前往创建 ClickHouse 数据源。

*数据表

在数据源名称下,选择需数据写入的数据表名信息,下拉可选。

写入前准备语句

在执行该数据集成任务前,需要率先执行的 SQL 语句,通常是为了使任务重跑时支持幂等。
例如您可以通过填写语句,清空表中的某些旧数据,清空完成后,再执行集成任务写入新的数据。如删除 date='${date}' 的数据:delete from table_name where date='${date}'
语句填写完成后,您可单击右侧的校验按钮,进行语句校验是否符合逻辑。

说明

可视化通道任务配置中只允许执行一条写入前准备语句。

写入后准备语句

执行数据同步任务之后执行的 SQL 语句。例如写入完成后插入某条特殊的数据,标志导入任务执行结束。
语句填写完成后,您可单击右侧的校验按钮,进行语句校验是否符合逻辑。

说明

可视化通道任务配置中只允许执行一条写入后准备语句。

*数据写入方式

下拉选择数据写入 ClickHouse 的方式:

  • insert into: 当主键/唯一性索引冲突时会无法写入冲突的行,任务会运行失败。

4.3.3 字段映射

数据来源和目标端配置完成后,需要指定来源和目标端的字段映射关系,根据字段映射关系,数据集成任务将源端字段中的数据,写入到目标端对应字段中。
字段映射支持选择基础模式转换模式配置映射:

注意

基础模式和转换模式不支持互相切换,模式切换后,将清空现有字段映射中所有配置信息,一旦切换无法撤销,需谨慎操作。

  • 转换模式:
    字段映射支持数据转换,您可根据实际业务需求进行配置,将源端采集的数据,事先通过数据转换后,以指定格式输入到目标端数据库中。
    转换模式详细操作说明详见4.1 转换模式
    在转换模式中,你可依次配置:来源节点、数据转换、目标节点信息:

    配置节点

    说明

    来源节点

    配置数据来源 Source 节点信息:

    • 节点名称:自定义输入来源节点名称信息,只允许由数字、字母、下划线、-和.组成;且长度不能超过10。
    • 数据字段:通过自动添加、手动添加等方式添加数据来源字段信息。

    配置完成后,单击确认按钮,完成来源节点配置。

    数据转换

    单击数据转换右侧添加按钮,选择 SQL 转换方式,配置转换信息和规则:

    • 节点名称:自定义输入来源节点名称信息,只允许由数字、字母、下划线、-和.组成;且长度不能超过10。
    • SQL 脚本:输入 SQL 脚本转换规则,目前仅支持添加一个转换的 SQL 语句,且不能包括 “;”。

    配置完成后,单击确认按钮,完成数据转换节点配置。SQL 脚本示例详见4.1.2 添加转换节点

    目标节点

    配置目标节点 Sink 信息:

    • 节点名称:自定义输入来源节点名称信息,只允许由数字、字母、下划线、-和.组成;且长度不能超过10。
    • 数据字段:通过自动添加、手动添加等方式添加数据目标字段信息。

    配置完成后,单击确认按钮,完成目标节点配置。

  • 基础模式:

    您可通过以下三种方式操作字段映射关系:

    • 自动添加:单击自动添加按钮,根据两端数据表信息,可以自动填充来源和目标的字段信息。

      说明

      自动添加字段映射时,默认不会映射来源表中的分区键字段。若有需要,您可通过手动添加的方式,将分区键字段的映射配置上。

    • 手动添加:单击手动添加按钮,可以手动编辑来源和目标的字段信息,可以逐个添加。

      说明

      来源端字段信息支持输入数据库函数和常量配置,单击手动添加按钮,在源表字段中输入需添加的值,并选择函数或常量类型,例如:

      • 函数:支持您输入 now()、current_timestamp() 等 ClickHouse 数据库支持的函数。
      • 常量:您可自定义输入常量值,'123'、'${DATE}'、'${hour}' 等,输入值两侧需要加上英文单引号,支持结合时间变量参数使用。
    • 移动\删除字段:您也可以根据需要移动字段映射顺序或删除字段。

4.4 DSL 配置说明

ClickHouse 数据源支持使用脚本模式(DSL)的方式进行配置。
在某些复杂场景下,或当数据源类型暂不支持可视化配置时,您可通过任务脚本的方式,按照统一的 Json 格式,编写 ClickHouse Reader 和 ClickHouse Writer 参数脚本代码,来运行数据集成任务。

4.4.1 进入 DSL 模式

进入 DSL 模式操作流程,可详见 MySQL 数据源-4.4.1 进入DSL 模式

4.4.2 ClickHouse 批式读

进入 DSL 模式编辑界面后,您可根据实际情况替换相应参数,ClickHouse 批示读脚本示例如下:

{
    // [required] dsl version, suggest to use latest version
    "version": "0.2",
    // [required] exection mode, supoort streaming / batch now
    "type": "batch",
    // reader config
    "reader": {
        // [required] datasource type
        "type": "clickhouse" ,
        // [optional] datasource id, set it if you have registered datasource
        "datasource_id": null,
        // [required] user parameter
        "parameter": {
            "split_field":"split_field_sample",   
            "password":"password_sample",  
            "db_name":"db_name_sample",   
            "user_name":"user_name_sample",
            "class":"com.bytedance.bitsail.connector.clickhouse.source.ClickhouseSource",
            "jdbc_url":"jdbc:clickhouse://{host}:{port}",
            "table_name":"table_name_sample",
            "columns": [
                {
                    "name": "name_sample",
                    "type": "type_sample"
                }
            ]
        }
    },
    // writer config
    "writer": {
        ...
    },
    // common config
    "common": {
        ...
    }
}

Reader 参数说明,其中参数名称前带 * 的为必填参数,名称前未带 * 的为可选填参数:

参数名称

参数含义

*type

数据源类型,对于 ClickHouse 类型,填写:clickhouse

*datasource_id

对应 ClickHouse 的数据源ID,暂时不支持,这里需填写 null

*class

ClickHouse reader connector type, 默认固定值com.bytedance.bitsail.connector.clickhouse.source.ClickhouseSource

*jdbc_url

ClickHouse JDBC url 主机名地址,示例:jdbc:clickhouse://{host}:{port}

*db_name

填写需读取的 ClickHouse 数据库名称。

*table_name

填写需读取的数据表信息。

*columns

填写所配置的表中,需要同步的列名集合,使用 JSON 的数组描述字段信息。

  • 支持列裁剪:列可以挑选部分列进行导出。
  • 支持列换序:列可以不按照表 Schema 信息顺序进行导出。
  • 支持函数、常量形式添加列:
    • 函数:ClickHouse Reader 支持您输入 now()、current_timestamp() 等 ClickHouse 数据库支持的函数。
    • 常量:ClickHouse Reader 支持您自定义输入常量值,如 '123'、'${DATE}'、'${hour}' 等,输入值两侧需要加上英文单引号,支持结合时间变量参数使用。

user_name

访问 ClickHouse 数据库的用户名。

password

ClickHouse 用户名对应的密码信息。

*split_field

批量查询字段,仅支持 Int8-Int64 和 UInt8-UInt32 整数类型。

split_config

根据 split_field 字段进行批量查询的配置,包括初始值、最大值和查询次数,
例如 {"lower_bound": 0, "upper_bound": 10000, "split_num": 3}

sql_filter

查询同步数据的过滤条件,例如:id%2==0,将被拼接到查询的 WHERE 子句的 SQL 中,同步时只采集符合过滤条件的数据。

说明

过滤条件可以有效地进行业务增量同步。如果不配置,默认会同步全量数据。

4.4.3 ClickHouse 批式写

根据实际情况替换 ClickHouse Writer 相应参数,ClickHouse 批式写脚本示例如下:

{
    // [required] dsl version, suggest to use latest version
    "version": "0.2",
    // [required] exection mode, supoort streaming / batch now
    "type": "batch",
    // reader config
    "reader": {
        ...
    },
    // writer config
    "writer": {
        // [required] datasource type
        "type": "clickhouse",
        // [optional] datasource id, set it if you have registered datasource
        "datasource_id": null,
        // [required] user parameter
        "parameter": {
            "user_name":"user_name_sample",
            "columns":[
                {
                    "name": "name_sample",
                    "type": "type_sample"
                }
            ],
            "table_name":"table_name_sample",
            "write_mode":"directlyInsert",
            "password":"password_sample",
            "db_name":"db_name_sample",
            "pre_sql_list":[    
                "pre_sql_sample"
            ],
            "post_sql_list":[    
                "post_sql_list"
            ],
            "class":"com.bytedance.dts.batch.jdbc.JDBCClickhouseOutputFormat",
            "connections":[
                {
                    "port":"port_sample",
                    "db_url":"jdbc:clickhouse://{host}:{port}/{db_name}?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull",
                    "host":"host_sample"
                }
            ]
        }
    },
    // common config
    "common": {
        ...
    }
}

Writer 参数说明,其中参数名称前带 * 的为必填参数,名称前未带 * 的为可选填参数:

参数名称

参数含义

*type

数据源 writer type,对于 ClickHouse 类型,默认固定值:clickhouse

*datasource_id

对应 ClickHouse 的数据源 ID,暂时不支持,这里请填写null

*class

ClickHouse writer connector type, 默认固定值com.bytedance.dts.batch.jdbc.JDBCClickhouseOutputFormat

*connections

ClickHouse JDBC 链接地址,包括 port,host 和 db_url 信息:

  • port:对应连接 ClickHouse 的端口号;
  • db_url:需要访问的 ClickHouse 数据库地址信息,填写示例如下:jdbc:clickhouse://{host}:{port}/{db_name}?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull
  • host:连接 ClickHouse 数据库的 IP 地址信息。

*db_name

填写需写入的 ClickHouse 数据库名称。

*table_name

填写需写入的数据表信息。

*columns

填写需写入数据的字段名称和类型信息。

*write_mode

写入模式,暂时只支持directlyInsert模式,即数据直接写入 ClickHouse。

user_name

访问 ClickHouse 数据库的用户名。

password

ClickHouse 用户名对应的密码信息。

pre_sql_list

写入前执行语句,在数据写入 ClickHouse 前会执行。可以根据需求执行清表等操作。详见“可视化离线写”说明。

post_sql_list

写入后执行语句,在同步任务写入 ClickHouse 数据完成后再执行的语句。详见“可视化离线写”说明。

4.4.4 ClickHouse 流式写

根据实际情况替换 ClickHouse 相应参数,ClickHouse 流式写脚本示例如下:

{
    // [required] dsl version, suggest to use latest version
    "version": "0.2",
    // [required] exection mode, supoort streaming / batch now
    "type": "streaming",
    // reader config
    "reader": {
        ...
    },
    // writer config
    "writer": {
        // [required] datasource type
        "type": "clickhouse",
        // [optional] datasource id, set it if you have registered datasource
        "datasource_id": 9823,
        // [required] user parameter
        "parameter": {
            "user_name":"user_name_sample",
            "columns":[
                {
                    "name": "name_sample",
                    "type": "type_sample"
                }
            ],
            "table_name":"table_name_sample",
            "write_mode":"directlyInsert",
            "password":"password_sample",
            "db_name":"db_name_sample",
            "pre_sql_list":[    
                "pre_sql_sample"
            ]
            "format.type": "json",
            "class":"com.bytedance.dts.batch.jdbc.JDBCClickhouseOutputFormat",
            "connections":[
                {
                    "port":"port_sample",
                    "db_url":"jdbc:clickhouse://{host}:{port}/{db_name}?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull",
                    "host":"host_sample"
                }
            ]
        }
    },
    // common config
    "common": {
        ...
    }
}

Writer 参数说明,其中参数名称前带 * 的为必填参数,名称前未带 * 的为可选填参数:

参数名称

参数含义

*type

数据源 writer type,对于 ClickHouse 类型,默认固定值:clickhouse

*datasource_id

注册的 ClickHouse 数据源 ID。可以在项目控制台 > 数据源管理界面中查找。

*class

ClickHouse writer connector type, 默认固定值 com.bytedance.dts.batch.jdbc.JDBCClickhouseOutputFormat

*connections

ClickHouse JDBC 链接地址,包括 port,host 和 db_url 信息:

  • port:对应连接 ClickHouse 的端口号;
  • db_url:需要访问的 ClickHouse 数据库地址信息,填写示例如下:jdbc:clickhouse://{host}:{port}/{db_name}?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull
  • host:连接 ClickHouse 数据库的 IP 地址信息。

*db_name

填写需写入的 ClickHouse 数据库名称。

*table_name

填写需写入的 ClickHouse 数据表信息。

*columns

填写需写入数据的字段名称和类型信息。

*write_mode

写入模式,目前仅支持 directlyInsert 模式,即数据直接写入 ClickHouse。

user_name

访问 ClickHouse 数据库的用户名。

password

ClickHouse 用户名对应的密码信息。

pre_sql_list

写入前执行语句,在数据写入 ClickHouse 前会执行。可以根据需求执行清表等操作。详见“4.3.2 ClickHouse 离线写”说明。

format.type

支持配置来源数据格式,支持 json、db、debezium_json 格式类型。