配置 ByteHouse 云数仓版 数据源

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网关计费概览。 查看资源组绑定的VPC： 进入私有网络界面，创建 NAT 网关，并绑定资源组对应的 VPC 信息： 配置公网IP： 创建完公网 NAT 网关后，在 NAT 列表页面，右侧操作栏中，单击配置公网IP。 单击绑定公网IP，下拉框中，选择可绑定的公网 IP，若无可用的公网 IP，可前往 申请公网IP 页面申请。申请操作详见：https://www.volcengine.com/docs/6402/69430。 配置 SNAT 规则【不要忘记这一步！！！】 绑定完公网 IP 后，上方功能栏中，切换到SNAT规则，单击创建SNAT规则，选择资源组中对应的 VPC，完成配置。后续该VPC即可访问公网Internet。
  火山引擎内网	ByteHouse CDW 同时也支持通过 VPC 内网形式访问连接，主账号需进入 ByteHouse CDW 租户管理界面绑定相关网络信息。操作流程如下： 主账号登录 ByteHouse CDW 控制台。 在上方导航栏中，切换至租户管理界面。 在网络信息 > 私网域名处，单击绑定按钮，并在右侧弹窗中完成绑定私网操作。 绑定私网时选择的 VPC、子网、安全组等信息，需和独享集成资源组中绑定的网络信息保持一致，以保障与独享集成资源组网络互通 更多绑定操作，详见设置网络信息。 说明 ByteHouse CDW 服务中，私有网络仅可绑定一次，绑定后不可修改，需谨慎选择。 若 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 云数仓版方式接入：

  参数	说明
  基本配置
  数据源类型	ByteHouse 云数仓版
  接入方式	火山引擎 ByteHouse 云数仓版
  数据源名称	数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。
  参数配置
  *ByteHouse 库	下拉选择已在 ByteHouse 云数仓版中创建的数据库名称信息。
  *计算组	ByteHouse_CDW 中查询使用的计算组。如果在 ByteHouse 中设置了默认计算组就可以不明确指定。详见 ByteHouse CDW 计算组。
  API Token	ByteHouse_CDW 账户信息中 的 Access Key。ByteHouse 读取数据的时候需要使用，建议绑定一个长效 Token，避免 Token 过期出现任务异常。 说明 整库实时同步解决方案写入和离线读取 ByteHouse CDW 时，API Token 必须填写。

• 连接串方式接入：

  注意

  连接串方式配置数据源时，暂不支持配置数据写入 ByteHouse_CDW。

  参数	说明
  基本配置
  数据源类型	ByteHouse 云数仓版
  接入方式	连接串
  数据源名称	数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。
  参数配置
  JDBC URL	根据数据库所在地域，选择填写 ByteHouse CDW 的 JDBC URL 地址信息： 华北2（北京）：bytehouse-cn-beijing.volces.com:19000 华东2（上海）：bytehouse-cn-shanghai.volces.com:19000
  *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 过期出现任务异常。 说明 整库实时同步解决方案写入和离线读取 ByteHouse CDW 时，API Token 必须填写。

4.2 新建离线任务

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

4.3 可视化配置说明

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

4.3.1 ByteHouse_CDW 批式读

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

4.3.2 ByteHouse_CDW 批式写

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

4.3.3 字段映射

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

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

  配置节点	说明
  来源节点	配置数据来源 Source 节点信息： 节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。 数据字段：通过自动添加、手动添加等方式添加数据来源字段信息。 配置完成后，单击确认按钮，完成来源节点配置。
  数据转换	单击数据转换右侧添加按钮，选择 SQL 转换方式，配置转换信息和规则： 节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。 SQL 脚本：输入 SQL 脚本转换规则，目前仅支持添加一个单行转换的 SQL 语句，且不能包括 “;”。 配置完成后，单击确认按钮，完成数据转换节点配置。
  目标节点	配置目标节点 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 参数说明，其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数：

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": {
        ...
    }
}

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

4.5 高级参数说明

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

  

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

4.5.1 ByteHouse_CDW 批式写

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