You need to enable JavaScript to run this app.
导航
配置 ByteHouse 云数仓版 数据源
最近更新时间:2024.06.11 19:38:58首次发布时间:2022.11.02 10:05:59

ByteHouse 是一款火山引擎云原生数据仓库,为您提供极速分析体验,能够支撑实时数据分析和海量数据离线分析等场景。
DataSail 中的 ByteHouse 云数仓版数据源配置,为您提供读取和写入 ByteHouse 的双向通道数据集成能力,实现不同数据源与 ByteHouse 之间进行数据传输。
本文为您介绍 DataSail 的 ByteHouse 数据同步的能力支持情况。

1 支持的 ByteHouse 版本

支持火山引擎 ByteHouse 云数仓版(ByteHouse_CDW)标品。开通服务详见快速开始

2 使用限制

  • 支持脚本模式(DSL)离线读写和可视化模式离线读写。

  • 因为 ByteHouse Date 类型的格式限制,如果分区字段类型是 Date,分区内容请填写为 ${DATE}。如果需要写入具体的分区,需按照 yyyy-MM-dd 格式填写。
    图片

  • 数据集成任务需要使用独享集成资源组,您需根据实际业务需求,购买相应规格的独享集成资源组。开通资源组详见资源组管理

  • 独享数据集成资源组,需要具有 ByteHouse CDW 数据库的网络访问能力,网络互通方案如下:

    网络配置方式

    操作方式

    公网

    ByteHouse CDW 数据源可通过公网的方式进行访问,因此独享数据集成资源组需要开通公网能力来访问数据库,操作步骤详见:资源组VPC开通公网

    注意

    开通公网会产生额外公网费用,具体可见公网IP计费概览NAT网关计费概览

    1. 查看资源组绑定的VPC:
      图片
    2. 进入私有网络界面,创建 NAT 网关,并绑定资源组对应的 VPC 信息:
      图片
    3. 配置公网IP:
      1. 创建完公网 NAT 网关后,在 NAT 列表页面,右侧操作栏中,单击配置公网IP
      2. 单击绑定公网IP,下拉框中,选择可绑定的公网 IP,若无可用的公网 IP,可前往 申请公网IP 页面申请。申请操作详见:https://www.volcengine.com/docs/6402/69430
    4. 配置 SNAT 规则【不要忘记这一步!!!】
      绑定完公网 IP 后,上方功能栏中,切换到SNAT规则,单击创建SNAT规则,选择资源组中对应的 VPC,完成配置。后续该VPC即可访问公网Internet。
      图片

    火山引擎内网

    ByteHouse CDW 同时也支持通过 VPC 内网形式访问连接,主账号需进入 ByteHouse CDW 租户管理界面绑定相关网络信息。操作流程如下:

    1. 主账号登录 ByteHouse CDW 控制台
    2. 在上方导航栏中,切换至租户管理界面。
    3. 网络信息 > 私网域名处,单击绑定按钮,并在右侧弹窗中完成绑定私网操作。
    4. 绑定私网时选择的 VPC、子网、安全组等信息,需和独享集成资源组中绑定的网络信息保持一致,以保障与独享集成资源组网络互通。
      图片

    更多绑定操作,详见设置网络信息

    说明

    • ByteHouse CDW 服务中,私有网络仅可绑定一次,绑定后不可修改,需谨慎选择。
    • 如果私有网络中 IPV4 CIDR 地址与 192.168.0.0/17 和 10.104.0.0/19 冲突时,子网将不会下拉显示,您创建时需避免网段冲突情况。
    • 若 ByteHouse CDW 服务绑定的私网信息与独享集成资源组网络信息存在不同的 VPC 情况时,您需额外通过云企业网VPN 连接方式,来实现不同 VPC 间的网络互通。

3 支持的字段类型

  • ByteHouse CDW Reader:

    数据类型

    是否支持

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

    支持

    Float64

    支持

    Decimal

    支持

    Date

    支持

    datetime

    支持

    String

    支持

    Array

    支持单层 Array 类型,不支持 Array 的嵌套类型

  • ByteHouse CDW Writer:

    数据字段类型

    支持情况

    Int

    支持

    Uint

    支持

    Float

    支持

    String

    支持

    Time

    支持

    Array

    支持单层 Array 类型,不支持 Array 的嵌套类型

    Map

    支持

4 数据同步任务开发

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

4.1 数据源注册

新建数据源操作详见配置数据源,下面为您介绍火山引擎 ByteHouse 云数仓版数据源不同接入方式的配置信息。
其中参数名称前带 * 的为必填参数,名称前未带 * 的为可选填参数。

注意

配置 ByteHouse 云数仓版数据源前,您需先进行以下操作:

  1. 开通 ByteHouse 云数据仓版服务。开通服务详见快速开始
  2. 已创建 ByteHouse 数据库,详见数据库表及视图
  • 火山引擎 ByteHouse 云数仓版方式接入:

    参数

    说明

    基本配置

    数据源类型

    ByteHouse 云数仓版

    接入方式

    火山引擎 ByteHouse 云数仓版

    数据源名称

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

    参数配置

    *ByteHouse 库

    下拉选择已在 ByteHouse 云数仓版中创建的数据库名称信息。

    *计算组

    ByteHouse_CDW 中查询使用的计算组。如果在 ByteHouse 中设置了默认计算组就可以不明确指定。详见 ByteHouse CDW 计算组

    API Token

    ByteHouse_CDW 租户管理中的 Access Key 信息。ByteHouse 读取数据的时候需要使用,建议绑定一个长效 Token,避免 Token 过期出现任务异常。

    说明

    使用数据同步解决方案写入、JDBC 连接方式写入离线读取 ByteHouse CDW 时,API Token 必须填写。

    图片

  • 连接串方式接入:

    参数

    说明

    基本配置

    数据源类型

    ByteHouse 云数仓版

    接入方式

    连接串

    数据源名称

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

    参数配置

    JDBC URL

    根据数据库所在地域,选择填写 ByteHouse CDW 的 JDBC URL 地址信息:

    *API Server

    根据数据库所在地域,选择填写 ByteHouse CDW 的 API Server 地址:

    • 华北2(北京):https://bytemart-cn-beijing.bytehouse.volcbiz.com
    • 华东2(上海):https://bytemart-cn-shanghai.bytehouse.volcbiz.com

    *数据库名

    下拉选择已在 ByteHouse 云数仓版中创建的数据库名称信息。

    *计算组

    ByteHouse_CDW 中查询使用的计算组。如果在 ByteHouse 中设置了默认计算组就可以不明确指定。详见 ByteHouse CDW 计算组

    *API Token

    ByteHouse_CDW 租户管理中的 Access Key 信息。ByteHouse 读取数据的时候需要使用,建议绑定一个长效 Token,避免 Token 过期出现任务异常。

    说明

    使用数据同步解决方案写入、JDBC 连接方式写入离线读取 ByteHouse CDW 时,API Token 必须填写。

    图片

4.2 新建离线任务

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

4.3 可视化配置说明

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

4.3.1 ByteHouse_CDW 批式读

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

参数

说明

*数据源类型

下拉选择 ByteHouse_CDW 数据源类型。

*数据源名称

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

*数据表

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

数据过滤

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

说明

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

*切分建

根据源数据表中的某一列作为切分键,建议使用主键或有索引的列作为切分键。

说明

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

4.3.2 ByteHouse_CDW 批式写

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

参数

说明

*目标类型

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

*数据源名称

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

*数据表

数据源下所属需数据写入的表名,下拉可选。

  • 快速建表:若目标表还未创建,您可单击快速建表按钮,前往 ByteHouse_CDW 控制台界面,进行目标表的创建。建表操作详见数据库表及视图
  • 修改数据表:若源端采集的字段存在更新情况时,您可单击修改数据表按钮,及时对目标表字段进行修改。

说明

子用户操作 ByteHouse CDW 库表时,需保障子用户拥有相应的 ByteHouse CDW 库表权限。权限说明详见 ByteHouse CDW 用户管理

*生命周期

展示所选目标数据表的生命周期。

*分区设置

根据所选数据表,自动获取表分区字段信息。 分区内容可设置具体时间分区粒度,可以用表达式:${date}、${hour}等参数变量表示;也支持写入动态分区类型,即根据源端字段值内容,进行动态写入,动态分区值必须存在于源端 Columns 中。

说明

  • 一级分区仅支持天级分区;
  • 小时级分区,若日期格式为:hh 如:02,则填写:${hour};
  • 小时级分区,若日期格式为:H,如:2,则填写:${HOUR};
  • 天级分区,若日期格式为:yyyyMMdd 如:20181017,则填写:${date};
  • 天级分区,若日期格式为:yyyy-MM-dd 如:2018-11-17,则填写:${DATE};
  • 月级分区,若日期格式为:MM,如:09,则填写:${month};
  • 静态分区如 App,只能输入一个分区内容的值;
  • 动态分区,分区内容不需要填写实际值,置空即可。

4.3.3 ByteHouse_CDW 流式写

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

参数

说明

*目标类型

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

*数据源名称

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

*数据表

数据源下所属需数据写入的表名,下拉可选。

  • 快速建表:若目标表还未创建,您可单击快速建表按钮,前往 ByteHouse_CDW 控制台界面,进行目标表的创建。建表操作详见数据库表及视图
  • 修改数据表:若源端采集的字段存在更新情况时,您可单击修改数据表按钮,及时对目标表字段进行修改。

*生命周期

展示所选目标数据表的生命周期。

*分区设置

根据所选数据表,自动获取表分区字段信息。 分区内容可设置具体时间分区粒度,可以用表达式:${date}、${hour}等参数变量表示;也支持写入动态分区类型,即根据源端字段值内容,进行动态写入,动态分区值必须存在于源端 Columns 中。

说明

  • 一级分区仅支持天级分区;
  • 小时级分区,若日期格式为:hh 如:02,则填写:${hour};
  • 小时级分区,若日期格式为:H,如:2,则填写:${HOUR};
  • 天级分区,若日期格式为:yyyyMMdd 如:20181017,则填写:${date};
  • 天级分区,若日期格式为:yyyy-MM-dd 如:2018-11-17,则填写:${DATE};
  • 月级分区,若日期格式为:MM,如:09,则填写:${month};
  • 静态分区如 App,只能输入一个分区内容的值;
  • 动态分区,分区内容不需要填写实际值,置空即可。

4.3.3 字段映射

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

说明

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

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

    配置节点

    说明

    来源节点

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

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

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

    数据转换

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

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

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

    目标节点

    配置目标节点 Sink 信息:

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

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

  • 基础模式:

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

    • 自动添加:单击自动添加按钮,根据两端数据表信息,可以自动填充来源和目标的字段信息。
    • 手动添加:单击手动添加按钮,可以手动编辑来源和目标的字段信息,可以逐个添加。
    • 移动\删除字段:您也可以根据需要移动字段映射顺序或删除字段。

4.4 DSL 配置说明

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

4.4.1 进入 DSL 模式

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

4.4.2 ByteHouse_CDW 批式读

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

// 变量使用规则如下:
// 1.自定义参数变量: {{}}, 比如{{number}}
// 2.系统时间变量${}, 比如 ${date}、${hour}
// **************************************
{
    "version": "0.2",
    "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": {
            "clickhouse_type":"bytehouse_cdw",
            "sql_filter":"date = '20230921' ",
            "split_field":"id",
            "password":"*******",
            "db_name":"db_test",
            "vw_name":"dts_test",
            //"user_name":"default",
            "class":"com.bytedance.bitsail.connector.clickhouse.source.ClickhouseSource",
            "jdbc_url":"bytehouse-cn-beijing.volces.com:19000",
            "table_name":"table_name_test",
            "columns": [
                {
                    "upperCaseName":"ID",
                    "name":"id",
                    "type":"Int64"
                },
                {
                    "upperCaseName":"NAME",
                    "name":"name",
                    "type":"String"
                }
            ]
        }
    },
    // writer config
    "writer": {
        ...
    },
    // common config
    "common": {
        ...
    }
}

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

参数名

参数说明

示例

*type

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

clickhouse

*datasource_id

目前 DSL 模式暂不支持以数据源 ID 的方式填写,此处默认为 null。

*clickhouse_type

clickhouse数据源类型下,读取 ByteHouse 云数仓版数据源需设置为:bytehouse_cdw

bytehouse_cdw

sql_filter

同步数据的过滤条件,同步数据时只会同步符合过滤条件的数据,可选。

*jdbc_url

ByteHouse_CDW 数据源连接的 jdbc 地址。
默认公网地址,独享数据集成资源组需要打开公网访问,详见“资源组 VPC 开通公网”。
公网地址:bytehouse-cn-beijing.volces.com:19000

说明

因为 ByteHouse_CDW 侧网络限制,若实际场景中需要通过私网域名访问时,您可通过提工单的方式,联系 ByteHouse_CDW 支持同学操作,并将独享集成资源组中 VPC 中的 IPv4 CIDR 地址添加到 ByteHouse_CDW 数据库的白名单中。
私网地址:bytehouse-cn-beijing.ivolces.com:19000

*vw_name

ByteHouse_CDW 中查询使用的计算组。如果在 ByteHouse 中设置了默认计算组就可以不明确指定。

*password

填写 Bytehouse CDW 账号下的 Access Key 信息:

  1. 登录 Bytehouse CDW 控制台
  2. 右上角单击齿轮按钮,进入我的账号界面;
  3. 在账号详细信息界面中,获取 Access Key。

图片

user_name

ByteHouse_CDW 中默认用户名default,可以不设置。

*split_field

根据源数据表中的某一列作为切分键,建议使用主键或有索引的列作为切分键:

说明

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

*class

bytehouse_cdw reader connector type,默认填写固定值:com.bytedance.bitsail.connector.clickhouse.source.ClickhouseSource

com.bytedance.bitsail.connector.clickhouse.source.ClickhouseSource

*db_name

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

*table_name

输入需读取的数据表名字信息。

*columns

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

4.4.3 ByteHouse_CDW 批式写

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

// **************************************
// 变量使用规则如下:
// 1.自定义参数变量: {{}}, 比如{{number}}
// 2.系统时间变量${}, 比如 ${date}、${hour}
// **************************************
{
    // [required] dsl version, suggest to use latest version
    "version": "0.2",
    // [required] execution mode, supoort streaming / batch now
    "type": "batch",
    // reader config
    "reader": {
        ...
    },
    // writer config
    "writer": {
        // [required] datasource type
        "type": "bytehouse_cdw",
        // [optional] datasource id, set it if you have registered datasource
        "datasource_id": {datasource_id},
        // [required] user parameter
        "parameter": {
            "columns": [
                {
                    "name": "id",
                    "type": "String"
                }
            ],
            "ch_partition_type":"String",   
            "shard_num":2,    
            "shard_column":"id",     
            "partition":"date=20240101", 
            "ch_table":"table_test1"
        }
    },
    // common config
    "common": {
        ...
    }
}

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

参数名

参数说明

*type

数据源类型,对于 ByteHouse 类型,填写 bytehouse_cdw

*datasource_id

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

*ch_table

填写需要数据写入的 ByteHouse_CDW 表名称信息。

*columns

需要同步的列名集合,使用 JSON 的数组描述字段信息。

ch_partition_type

ByteHouse_CDW 表分区字段类型,多级分区需要英文逗号按顺序分割,非分区表可不填写。

partition

ByteHouse_CDW 分区,key=value 格式,多级分区需要英文逗号按顺序分割,非分区表可不填写。

*shard_num

分片数量,用于任务分片处理,建议和任务并发设置一致。

*shard_column

分片字段,建议使用 ByteHouse_CDW 表主键字段信息。

4.5 高级参数说明

  • 对于通道任务,读参数需要加上 job.reader. 前缀,写参数需要加上 job.writer. 前缀,如下图所示:

  • 对于 DSL 任务,读参数请配置到 reader.parameter 下,写参数请配置到 writer.parameter 下,直接输入参数名称和参数值,如:"job.writer.loading_mode":"FULL_REFRESH"

4.5.1 ByteHouse_CDW 批式读

读取 ByteHouse_CDW 时,支持以下高级参数,您可根据实际情况进行配置:

参数名

描述

默认值

job.reader.split_config

设置任务分片数量配置参数。
配置示例: job.reader.split_config = {"split_num": 10}
适用范围: 整数类型切分键,如切分键是 int 类型,默认分片数是和并发数相同 ,可以通过此参数修改分片数量:job.reader.split_config = {"split_num": 100}

分片数是和并发数相同

job.read.string_split_size

设置分片大小。
适用范围:字符串类型切分键,您可根据该值计算分片数量。
该值不宜过大或过小:

  • 过小,分片数量较多,计算分片耗时较长
  • 过大,单分片数量过大,触发读数据超时

1000000

job.reader.customized_connection_properties

读取 ByteHouse 超时设置参数。
配置示例: 超时设置 : job.reader.customized_connection_properties = {"max_execution_time":3000}

4.5.2 ByteHouse_CDW 批式写

批式写入 ByteHouse_CDW 时,支持以下高级参数,您可根据实际情况进行配置:

参数名

描述

默认值

job.writer.flush_interval

写入 buffer 的刷新时间,默认 60000 毫秒

60000

job.writer.buffer_count

写入 buffer 记录条数,默认 8192

8192

job.writer.bh_ce_partition_type

显示的指定 ByteHouse 的分区字段为 string 类型,当分区字段使用函数时,需要使用此高级参数函数。

string

job.writer.loading_mode

高级参数 job.writer.loading_mode 可设置为 FULL_REFRESH 或 INCREMENTAL,默认为 INCREMENTAL:

  • FULL_REFRESH:可支持非分区表清除原先表中数据后再导入新数据,避免数据重复。
  • INCREMENTAL:支持分区表导入数据时,事先清除对应分区中的数据后再导入新数据,对非分区表无效。

INCREMENTAL