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

1 支持的 ByteHouse 版本

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

2 使用限制

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

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

• ByteHouse CDW 数据源接入方式为连接串模式，配置 ByteHouse CDW 批式写时，暂不支持目标表一键建表功能；配置解决方案中 ByteHouse CDW 写入时，暂不支持自动建表操作。您需手动在目标库表中创建相应的数据表。

• DataSail 解决方案中，目标端为 ByteHouse CDW 数据源，在源表和目标表映射中使用已有的 ByteHouse CDW 表时，需保证表结构中必须包含唯一键字段。
  

• ByteHouse CDW 数据源用于配置实时整库同步解决方案，用实时 CDC 方式读取 ByteHouse CDW 数据表时，需满足以下条件：

  • ByteHouse CDW 数据源注册配置时，需要使用“火山引擎 ByteHouse 云数仓版”方式接入，连接串模式暂不支持获取源端 Binlog 信息。
  • ByteHouse CDW 集群的引擎版本需为 2.3.1 及以上，方可支持 Binlog 消费能力。引擎版本，您可在 ByteHouse 控制台 → 租户管理 → 基础信息中查看。若版本不符合要求时，您可通过提工单的方式，咨询 ByteHouse 同学进行操作。
    
  • 在使用实时整库同步解决方案自动创建 ByteHouse CDW 表时，若要使该表后续具备 Binlog 读取能力，则需要在映射配置 → 高级参数配置处，手动添加高级参数 solution.writer.common.ddl.bytehouse.enable.binlog=true，如此创建的表方可后续支持 Binlog 读取。
    
  • 若是手动创建的 ByteHouse CDW 表，则表的 SETTINGS 参数中必须包含 enable_binlog = 1 这一属性参数；存量的表可以通过 ALTER TABLE 语句加上这个参数，如 alter table database.name modify setting enable_binlog = 1;

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

  网络配置方式	操作方式
  公网	ByteHouse CDW 数据源可通过公网的方式进行访问，因此独享数据集成资源组需要开通公网能力来访问数据库，操作步骤详见：资源组VPC开通公网。 注意 开通公网会产生额外公网费用，具体可见公网IP计费概览、NAT网关计费概览。 通过公网访问时，数据源接入需选择连接串方式，并配置 ByteHouse CDW 数据库的公网 JDBC URL 和 API Server 地址。地址获取方式详见调用方式。 查看资源组绑定的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 服务中，私有网络仅可绑定一次，绑定后不可修改，需谨慎选择。 如果私有网络中 IPV4 CIDR 地址与 192.168.0.0/17 和 10.104.0.0/19 冲突时，子网将不会下拉显示，您创建时需避免网段冲突情况。 若 ByteHouse CDW 服务绑定的私网信息与独享集成资源组网络信息存在不同的 VPC 情况时，您需额外通过云企业网或 VPN 连接方式，来实现不同 VPC 间的网络互通。

3 使用前提

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

• 开通 ByteHouse 云数据仓版服务。开通服务详见快速开始。
• 已创建 ByteHouse 数据库，详见数据库表及视图。
• 已创建合适资源规格的独享数据集成资源组，并将其绑定至创建成功的 DataLeap 项目下。购买操作详见资源组管理，项目绑定操作详见数据集成资源组。

4 支持的字段类型

• ByteHouse CDW Reader：

  数据类型	是否支持
  Int8 Int16 Int32 Int64 UInt8 UInt16 UInt32 UInt64	支持
  Float64	支持
  Decimal	支持
  Date	支持
  datetime	支持
  String	支持
  Enum8	支持
  Array	支持单层 Array 类型，不支持 Array 的嵌套类型

• ByteHouse CDW Writer：

  数据字段类型	支持情况
  Int	支持
  Uint	支持
  Float	支持
  String	支持
  Time	支持
  Array	支持单层 Array 类型，不支持 Array 的嵌套类型
  Map	支持
  BitMap64	支持
  JSONB	支持

5 数据同步任务开发

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

5.1 数据源注册

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

• 火山引擎 ByteHouse 云数仓版方式接入：

  参数	说明
  基本配置
  数据源类型	ByteHouse 云数仓版
  接入方式	火山引擎 ByteHouse 云数仓版
  数据源名称	数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。
  参数配置
  环境	ByteHouse 云数仓版支持选择多环境实例管理，下拉选择 ByteHouse 云数仓版中具体的环境名称信息。默认为 ByteHouse 云数仓中 default 环境。ByteHouse 云数仓版多环境操作，详见环境管理。 若当前 DataLeap 项目是多环境模式项目，则您可根据实际情况在开发、生产环境中配置不同的 ByteHouse 云数仓版多环境实例，满足生产开发数据源隔离配置场景。生产开发数据源隔离开启方式详见新建多环境项目。
  *ByteHouse 库	下拉选择已在 ByteHouse 云数仓版对应环境中创建的数据库名称信息。
  *计算组	ByteHouse_CDW 对应环境中查询使用的计算组。详见 ByteHouse CDW 计算组。 注意 选择计算组时，需确保计算组使用率在 80% 以下，若超过 80% 会导致任务执行时写入异常，需进行扩容。扩容操作详见计算组规格变更。
  API Token	ByteHouse_CDW 租户管理中的 Access Key 信息。ByteHouse 读取数据的时候需要使用，建议绑定一个长效 Token，避免 Token 过期出现任务异常。 说明 使用数据同步解决方案写入、JDBC 连接方式写入和离线读取 ByteHouse CDW 时，API Token 必须填写。

• 连接串方式接入：

  参数	说明
  基本配置
  数据源类型	ByteHouse 云数仓版
  接入方式	连接串
  数据源名称	数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。
  参数配置
  环境	ByteHouse 云数仓版支持选择多环境实例管理，下拉选择 ByteHouse 云数仓版中具体的环境名称信息。默认为 ByteHouse 云数仓中 default 环境。ByteHouse 云数仓版多环境操作，详见环境管理。 若当前 DataLeap 项目是多环境模式项目，则您可根据实际情况在开发、生产环境中配置不同的 ByteHouse 云数仓版多环境实例，满足生产开发数据源隔离配置场景。生产开发数据源隔离开启方式详见新建多环境项目。
  JDBC URL	根据数据库所在地域，选择填写 ByteHouse CDW 的 JDBC URL 地址信息，格式如下： 私网：tenant-210xxxxxx7-cn-beijing.bytehouse.ivolces.com:19000 公网：tenant-210xxxxxx7-cn-beijing-public.bytehouse.volces.com:19000 说明 地址信息中的租户 ID 和地域信息需根据实际情况进行替换。地址获取方式详见调用方式。
  *API Server	根据数据库所在地域，选择填写 ByteHouse CDW 的 API Server 地址，格式如下： 私网：https://tenant-210xxxxxx7-cn-beijing.bytehouse.ivolces.com 公网：https://tenant-210xxxxxx7-cn-beijing-public.bytehouse.volces.com 说明 地址信息中的租户 ID 和地域信息需根据实际情况进行替换。地址获取方式详见调用方式。
  *数据库名	输入已在 ByteHouse 云数仓版中创建的数据库名称信息。
  *计算组	ByteHouse_CDW 中查询使用的计算组。详见 ByteHouse CDW 计算组。
  *API Token	ByteHouse_CDW 租户管理中的 Access Key 信息。ByteHouse 读取数据的时候需要使用，建议绑定一个长效 Token，避免 Token 过期出现任务异常。 说明 使用数据同步解决方案写入、JDBC 写入方式和离线读取 ByteHouse CDW 时，API Token 必须填写。

5.2 新建离线任务

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

5.3 可视化配置说明

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

5.3.1 ByteHouse_CDW 批式读

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

5.3.2 ByteHouse_CDW 批式写

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

5.3.3 ByteHouse_CDW 流式写

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

5.3.3 字段映射

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

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

  配置节点	说明
  来源节点	配置数据来源 Source 节点信息： 节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。 数据字段：通过自动添加、手动添加等方式添加数据来源字段信息。 配置完成后，单击确认按钮，完成来源节点配置。
  数据转换	单击数据转换右侧添加按钮，选择 SQL 转换方式，配置转换信息和规则： 节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。 SQL 脚本：输入 SQL 脚本转换规则，目前仅支持添加一个转换的 SQL 语句，且不能包括 “;”。 配置完成后，单击确认按钮，完成数据转换节点配置。SQL 脚本示例详见4.1.2 添加转换节点。
  目标节点	配置目标节点 Sink 信息： 节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。 数据字段：通过自动添加、手动添加等方式添加数据目标字段信息。 配置完成后，单击确认按钮，完成目标节点配置。

• 基础模式：

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

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

    说明

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

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

    说明

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

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

5.4 DSL 配置说明

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

5.4.1 进入 DSL 模式

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

5.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 参数说明，其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数：

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

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

5.5 高级参数说明

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

  

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

5.5.1 ByteHouse_CDW 批式读

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

5.5.2 ByteHouse_CDW 批式写

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