ByteHouse 是一款火山引擎云原生数据仓库，为您提供极速分析体验，能够支撑实时数据分析和海量数据离线分析等场景。
ByteHouse（企业版）是基于开源 ClickHouse 的企业级分析型数据库，支持用户交互式分析 PB 级别数据，通过多种自研表引擎，灵活支持各类数据分析和应用。
DataSail 中的 ByteHouse 企业版数据源配置，为您提供读取和写入 ByteHouse 的双向通道数据集成能力，实现不同数据源与 ByteHouse 之间进行数据传输。
本文为您介绍 DataSail 的 ByteHouse 数据同步的能力支持情况。

1 支持的 ByteHouse 版本

支持火山引擎 ByteHouse 企业版（ByteHouse_CE）标品。开通服务详见快速开始。

2 使用限制

• 支持脚本模式（DSL）离线写和可视化模式离线读写、流式写，后续更多支持方式，敬请期待。
• 因为 ByteHouse Date 类型的格式限制，如果分区字段类型是 Date，分区内容请填写为 ${DATE}。如果需要写入具体的分区，需按照 yyyy-MM-dd 格式填写。
  
• 数据集成任务需要使用独享集成资源组，您需根据实际业务需求，购买相应规格的独享集成资源组。开通资源组详见资源组管理。
• ByteHouse CE 默认使用内网连通，独享数据集成资源组，需要具有 ByteHouse CE 数据库的网络访问能力。您需保障独享数据集成资源组和 ByteHouse CE 集群处于同一个 VPC 网络下，且您需要通过提工单的方式，将 VPC ID 信息，提供给 ByteHouse CE 支持同学，来打通 VPC 与集群间的网络。
  
• DataSail 解决方案中，目标端为 ByteHouse CE 数据源，在源表和目标表映射中使用已有的 ByteHouse CE 表时，需保证表引擎必须选择为 HaUniqueMergeTree。
  

3 支持的字段类型

| | | \

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

4 数据同步任务开发

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

4.1 数据源注册

新建数据源操作详见配置数据源，下面为您介绍火山引擎 ByteHouse 企业版数据源不同接入方式的配置信息。
其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。
:::warning
配置 ByteHouse 企业版数据源前，您需先进行以下操作：

1. 开通 ByteHouse 企业版服务。开通服务详见快速开始。
2. 已创建 ByteHouse 数据库，详见新建数据库表。
3. 如果 ByteHouse 企业版的首个集群由子用户创建，在配置首个 ByteHouse 数据源之前，主账号需要先进入 ByteHouse 企业版控制台一次，进行集群激活、重置集群连接密码等操作。主账号激活 ByteHouse 企业版服务后，子用户才能进行后续的数据源配置。开启服务操作详见快速开始。
   :::

• 火山引擎 ByteHouse 企业版方式接入：

  | | | \

  参数	说明
  基本配置
  *数据源类型	ByteHouse 企业版
  *接入方式	火山引擎 ByteHouse 企业版
  *数据源名称	数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。
  参数配置
  *集群	下拉选择已创建的 ByteHouse 企业版集群名称。
  *数据库名	下拉选择已在 ByteHouse 企业版中创建的数据库名称信息。
  *用户名	有权限访问数据库的用户名信息。
  *密码	输入用户名对应的密码信息。

• 连接串方式接入
  :::warning

  • 连接串方式配置数据源时，暂不支持配置数据写入 ByteHouse_CE。
  • 在跨账号场景下连接访问 ByteHouse 数据源时，确保数据源网络与独享集成资源组网络互通之后，可将数据源类型切换为 ClickHouse 进行配置。配置详见4.1 数据源注册。
    :::

  | | | \

  参数	说明
  基本配置
  *数据源类型	ByteHouse 企业版
  *接入方式	连接串
  *数据源名称	数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。
  参数配置
  JDBC URL	您可前往 ByteHouse CE 控制台 集群管理 > 集群列表 > 集群名称 > 连接集群 页签中查看 JDBC 连接地址。
  	
  	在数据源配置时输入连接 ByteHouse CE 集群的私网或公网 JDBC URL 地址信息.
  	:::tip
  	* 若该数据源用于数据同步解决方案写入 ByteHouse CE 时，JDBC URL为必填项。
  	* "jdbc:clickhouse://" 这一前缀和端口号信息无需在此填写，测试连通性时，平台将自动补全。
  	:::
  *API Server	根据集群所在地域，选择填写 ByteHouse CE 集群的 API Server 地址：
  	* 华北2（北京）：http://ceprod.offline.bytehouse.cn
  	* 华东2（上海）：http://ceprod-sh.offline.bytehouse.cn
  	:::tip
  	连接串接入方式下，数据集成任务支持您跨 Region 读取 ByteHouse CE 集群数据，您需保障网络互通即可。
  	暂不支持跨 Region 写入 ByteHouse CE 集群。
  	:::
  *集群	输入已创建的 ByteHouse 企业版集群名称。
  *数据库名	下拉选择已在 ByteHouse 企业版中创建的数据库名称信息。
  *用户名	有权限访问数据库的用户名信息。
  *密码	输入用户名对应的密码信息。

4.2 新建离线任务

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

4.3 可视化配置说明

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

4.3.1 ByteHouse_CE 批式读

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

| | | \

参数	说明
*数据源类型	下拉选择 ByteHouse_CE 数据源类型。
*数据源名称	已在数据源管理中注册成功的 ByteHouse_CE 数据源，下拉可选。
	若还未建立相应数据源，可单击数据源管理按钮，前往创建 ByteHouse_CE 数据源。
*数据表	选择需要采集的数据表名称信息，目前单个任务只支持将单表的数据采集到一个目标表中。
数据过滤	可自定义配置全量或增量读取数据源：
	* 如果不配置数据过滤，默认会同步全量数据。
	* 增量读取时您将需要同步的数据进行筛选条件设置，只同步符合过滤条件的数据，可直接填写关键词 where 后的过滤 SQL 语句且无需填写结束符号（;），例如：create_time > '${date}'，表示只同步 create_time 大于等于 ${date} 的数据，不需要填写 where 关键字。
	:::tip
	该过滤语句通常用作增量同步，暂时不支持 limit 关键字过滤，其 SQL 语法需要和选择的数据源类型对应。
	:::
切分键	根据配置的字段进行数据分片，建议使用主键或有索引的列作为切分键：
	* 如果表没有主键或者索引列，可以不配置该字段，同步任务不会进行分片，并以单并发的方式同步所有的数据；
	* 建议使用主键或有索引的列作为切分键，切分键配置没有索引的列同步任务会比较慢；
	:::tip
	目前仅支持类型为整型或字符串的字段作为切分键。切分键设置推荐详见4.6 切分键应用推荐。
	:::

4.3.2 ByteHouse_CE 批式写

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

| | | \

参数	说明
*目标类型	数据去向目标类型选择 ByteHouse_CE。
*数据源名称	已在数据源管理界面注册的 ByteHouse_CE 数据源，下拉可选。
	若还未建立相应数据源，可单击数据源管理按钮，前往创建 ByteHouse_CE 数据源。
*数据表	数据源下所属需数据写入的表名，下拉可选。
	* 一键建表：若目标表还未创建，您可单击一键建表按钮，在弹窗中进行可视化建表操作。建表逻辑详见新建数据库表。
	:::tip
	* 若是定义为排序键、分表键、分区键、唯一键等字段，均不允许为空；
	* 对于 HaUniqueMergeTree（源表有主键的表），必须定义唯一键（uniqueKeys）；如果还定义了分片键（shardKey），则 shardKey 必须在唯一键中选取。
	* 对于 HaMergeTree（源表无主键的表），不允许定义唯一键（uniqueKeys）。如果还定义了分片键（shardKey），则必须在非空字段中选择，且字段类型必须为 String、Int 类型（包括但不限于 Int8、Int16、Int64 等）、UInt 类型、Date 类型（包括但不限于 Date、DateTime、DateTime64）、Time 类型，或者为 rand() 字符串。
	:::
*生命周期	展示所选目标数据表的生命周期。
*写入方式	支持选择 CFS、JDBC 方式写入。
	:::warning
	* CFS 方式逐步下线中，新用户已不支持。
	* JDBC 写入方式，必须在数据源配置时，配置数据源的 JDBC URL 信息。详见4.1 数据源注册。
	:::
*分区设置	根据所选数据表，自动获取表分区字段信息。 分区内容可设置具体时间分区粒度，可以用表达式：${date}、${hour}等参数变量表示；也支持写入动态分区类型，即根据源端字段值内容，进行动态写入，动态分区值必须存在于源端 Columns 中。
	:::tip
	* 小时级分区，若日期格式为：hh 如:02，则填写：${hour}；
	* 小时级分区，若日期格式为：H，如：2，则填写：${HOUR}；
	* 天级分区，若日期格式为：yyyyMMdd 如:20181017，则填写：${date}；
	* 天级分区，若日期格式为：yyyy-MM-dd 如:2018-11-17，则填写：${DATE}；
	* 月级分区，若日期格式为：MM，如：09，则填写：${month}；
	* 静态分区如 App，只能输入一个分区内容的值；
	* 动态分区，分区内容不需要填写实际值，置空即可;
	* 数据写入时，分区字段暂不支持写入 datetime 数据类型。
	:::
写入前准备语句	写入方式为 JDBC 时，可在执行该数据集成任务前，输入率先执行的 SQL 语句，通常是为了使任务重跑时支持幂等。
	例如您可以通过填写语句，清空表中的某些旧数据，清空完成后，再执行集成任务写入新的数据。如清空表中已有的数据：TRUNCATE TABLE dts.unified_table_jdbc
	语句填写完成后，您可单击右侧的校验按钮，进行语句校验是否符合逻辑。
	:::tip
	* 若前置语句中操作的是本地表（Local Table，即包含 “_local” 后缀的表）时，写入语句中必须带上 ON CLUSTER <cluster_name> ，否则在 ByteHouse CE 侧执行时会异常，如清空表语句示例为 TRUNCATE TABLE db_name.unified_table_jdbc_local ON CLUSTER dts_db。
	* 若前置语句中操作的是通用表（Unified Table）时，则无需加上 ON CLUSTER <cluster_name>，输入 TRUNCATE TABLE dts.unified_table_jdbc 即可。
	ByteHouse CE 建表模式差异说明详见 建表模式。
	* 不支持配置多条写入前准备语句。
	:::
写入后准备语句	写入方式为 JDBC 时，可在执行数据同步任务之后再执行输入的 SQL 语句。例如写入完成后插入某条特殊的数据，标志导入任务执行结束。
	语句填写完成后，您可单击右侧的校验按钮，进行语句校验是否符合逻辑。
	:::tip
	* 若后置语句中操作的是本地表（Local Table，即包含 “_local” 后缀的表）时，写入语句中必须带上 ON CLUSTER <cluster_name> ，否则在 ByteHouse CE 侧执行时会异常，如插入表数据语句示例为 INSERT INTO db_name.unified_table_jdbc_local (id, name) VALUES (3, 'MEOW') ON CLUSTER dts_db。
	* 若后置语句中操作的是通用表（Unified Table）时，则无需加上 ON CLUSTER <cluster_name>，输入 INSERT INTO db_name.unified_table_jdbc (id, name) VALUES (3, 'MEOW') 即可。
	ByteHouse CE 建表模式差异说明详见 建表模式。
	* 不支持配置多条写入后准备语句。
	:::

4.3.3 ByteHouse_CE 流式写

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

| | | \

参数	说明
*目标类型	数据去向目标类型选择 ByteHouse_CE。
*数据源名称	已在数据源管理界面注册的 ByteHouse_CE 数据源，下拉可选。
	若还未建立相应数据源，可单击数据源管理按钮，前往创建 ByteHouse_CE 数据源。
*数据表	数据源下所属需数据写入的表名，下拉可选。
写入前准备语句	在首次执行该流式数据集成任务或重启任务前，需要率先执行的 SQL 语句。
	例如您可以通过填写语句，清空表中的某些旧数据，清空完成后，再执行集成任务写入新的数据。如删除 date='${date}' 的数据：ALTER TABLE database.table [ON CLUSTER cluster] DELETE WHERE date='${date}'
	:::tip
	可视化通道任务配置中，只允许执行一条写入前准备语句。
	:::
*生命周期	展示所选目标数据表的生命周期。
*写入方式	支持选择 CFS、JDBC 方式写入，
	:::warning
	JDBC 写入方式，必须在数据源配置时，配置数据源的 JDBC URL 信息。详见4.1 数据源注册。
	:::
*分区设置	根据所选数据表，自动获取表分区字段信息。 分区内容可设置具体时间分区粒度，可以用表达式：${date}、${hour}等参数变量表示；也支持写入动态分区类型，即根据源端字段值内容，进行动态写入，动态分区值必须存在于源端 Columns 中。
	:::tip
	* 一级分区仅支持天级分区；
	* 小时级分区，若日期格式为：hh 如:02，则填写：${hour}；
	* 小时级分区，若日期格式为：H，如：2，则填写：${HOUR}；
	* 天级分区，若日期格式为：yyyyMMdd 如:20181017，则填写：${date}；
	* 天级分区，若日期格式为：yyyy-MM-dd 如:2018-11-17，则填写：${DATE}；
	* 月级分区，若日期格式为：MM，如：09，则填写：${month}；
	* 静态分区如 App，只能输入一个分区内容的值；
	* 动态分区，分区内容不需要填写实际值，置空即可;
	* 流式集成写入 ByteHouse CE 选择 JDBC 写入方式时，分区类型默认为动态分区类型，且不可更改。
	* 数据写入时，分区字段暂不支持写入 datetime 数据类型。
	:::

4.3.4 字段映射

数据来源和目标端配置完成后，需要指定来源和目标端的字段映射关系，根据字段映射关系，数据集成任务将源端字段中的数据，写入到目标端对应字段中。
字段映射支持选择基础模式和转换模式配置映射：
:::warning
基础模式和转换模式不支持互相切换，模式切换后，将清空现有字段映射中所有配置信息，一旦切换无法撤销，需谨慎操作。
:::

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

  | | | \

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

• 基础模式：

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

  • 自动添加：单击自动添加按钮，根据两端数据表信息，可以自动填充来源和目标的字段信息。
    :::tip
    自动添加字段映射时，默认不会映射来源表中的分区键字段。若有需要，您可通过手动添加的方式，将分区键字段的映射配置上。
    :::

  • 手动添加：单击手动添加按钮，可以手动编辑来源和目标的字段信息，可以逐个添加。
    :::tip
    来源端字段信息支持输入数据库函数和常量配置，单击手动添加按钮，在源表字段中输入需添加的值，并选择函数或常量类型，例如：

    • 函数：支持您输入 now()、FROM_UNIXTIME()等 ByteHouse CE 数据库支持的函数。
    • 常量：您可自定义输入常量值，'123'、'${DATE}'、'${hour}' 等，输入值两侧需要加上英文单引号，支持结合时间参数与项目参数使用。
      :::

  • 移动\删除字段：您也可以根据需要移动字段映射顺序或删除字段。
    :::tip
    数据写入 ByteHouse CE 时，当 ByteHouse CE 表引擎设置为 HaUniqueMergeTree，且已在 ByteHouse CE 数据查询控制台中完成了以下表配置变更：
    
    变更完成后，您可以根据实际业务需求，灵活选择只更新数据表中的部分列。您只需要配置需要更新的列映射，对于未设定的列，它们将保持原有的值，或是默认值。这种灵活的数据更新方式，可以帮助您更高效地管理和维护数据，减少不必要的操作，提升工作效率。
    :::

4.4 DSL 配置说明

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

4.4.1 进入 DSL 模式

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

4.4.2 ByteHouse_CE 批式读

根据实际情况替换 ByteHouse_CE 批式读相应参数，ByteHouse_CE 批式读脚本示例如下：

{
    "version": "0.2",
    "type": "batch",
    "reader": {
        "type": "bytehouse_ce",
        "datasource_id": {datasource_id},
        "parameter": {
            "columns": [
                {
                    "name": "name_sample",
                    "type": "type_sample"
                }
            ],
            "splitKeys": [
                "id"
            ],
            "sql_filter": "",
            "table_name": "table_sample"
        }
    },
    // writer config
    "writer": {
        ...
    },
    // common config
    "common": {
        ...
    }
}

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

| | | \

参数名称	参数含义
*type	数据源类型，对于 ByteHouse_CE 类型，填写： bytehouse_ce
*datasource_id	注册的 ByteHouse_CE 数据源 ID。可以在项目控制台 > 数据源管理界面中查找。
*table_name	填写需要读取数据的 Bytehouse_CE 表名称。
splitKeys	根据配置的字段进行数据分片，建议使用主键或有索引的列作为切分键，同步任务会启动并发任务进行数据同步，提高同步速率：
	* 如果表没有主键或者索引列，可以不配置该字段，同步任务不会进行分片，并以单并发的方式同步所有的数据；
	* 建议使用主键或有索引的列作为切分键，切分键配置没有索引的列同步任务会比较慢；
	:::tip
	目前仅支持类型为整型或字符串的字段作为切分键。
	:::
sql_filter	输入同步数据的筛选条件，同步数据时只会同步符合过滤条件的数据，直接填写关键词 where 后的过滤 SQL 语句即可。
	* 如将过滤条件指定为：date>=${date} ，表示只同步 date 大于等于 ${date}。
	* 过滤条件可以有效地进行业务增量同步。如果不配置，默认会同步全量数据。
*columns	配置表中需要同步的列名集合，使用 JSON 的数组描述字段信息。
	* 支持列裁剪：列可以挑选部分列进行导出。
	* 支持列换序：列可以不按照表 Schema 信息顺序进行导出。
	:::warning
	* column 必须显示指定同步的列集合，不允许为空。
	* column 必须与导入的源端列集合对齐，不允许多列或少列。
	:::

4.4.2 ByteHouse_CE 批式写

根据实际情况替换 ByteHouse_CE 批式写相应参数，ByteHouse_CE 批式写脚本示例如下：

// **************************************
// 变量使用规则如下:
// 1.自定义参数变量: {{}}, 比如{{number}}
// 2.系统时间变量${}, 比如 ${date}、${hour}
// **************************************
{
    "version": "0.2",
    "type": "batch",
    "reader": {
        ...
    },
    "writer": {
        "type": "bytehouse_ce",
        "datasource_id": {datasource_id},
        "parameter": {
            "ch_table": "ch_table_sample",
            "partition": "partition1=value1,partition2=value2",
            "bh_ce_partition_type": "partition_type1,partition_type2",
            "columns": [
                {
                    "name": "name_sample",
                    "type": "type_sample"
                }
            ]
        }
    },
    "common": {
        ...
    }
}

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

| | | \

参数名称	参数含义
*type	数据源类型，对于 ByteHouse_CE 类型，填写： bytehouse_ce
*datasource_id	注册的 ByteHouse_CE 数据源 ID。可以在项目控制台 > 数据源管理界面中查找。
*ch_table	填写需要写入数据的 Bytehouse_CE 表名称。
*partition	写入的分区，key=value 的格式，多级分区按顺序，并用英文逗号分隔。
*bh_ce_partition_type	写入的分区字段类型，多级分区按照顺序英文逗号分隔。
*columns	配置表中需要同步的列名集合，使用 JSON 的数组描述字段信息。
	* 支持列裁剪：列可以挑选部分列进行导出。
	* 支持列换序：列可以不按照表 Schema 信息顺序进行导出。
	:::warning
	* column 必须显示指定同步的列集合，不允许为空。
	* column 必须与导入的源端列集合对齐，不允许多列或少列。
	:::

4.5 高级参数说明

ByteHouse CE 高级参数配置与 ByteHouse CDW 高级参数配置一致，详见6 高级参数说明 。
:::warning
其中写入 ByteHouse CDW 的高级参数：job.writer.loading_mode，在写入 ByteHouse CE 时不适用。
:::

4.6 切分键应用推荐

集成任务读取 ByteHouse CE 表时，若表中的数据量比较大，您可以通过设置合理的切分键、并发数等参数，来提高数据读取效率。
目前切分键支持整数和字符串字段类型，以下为您推荐切分键设置方案：

• 整数类型：优先推荐整数类型的字段作为切分键，能够更高效的快速划分数据量，进行分批读取。
• 字符串类型：若字段类型中没有整数类型的字段，您也可通过数据分布均匀的字符串类型字段作为切分键，能够有效避免数据倾斜的场景，进而提高数据读取效率。
• ByteHouse CE 表中默认缺省值列：若 ByteHouse CE 表的业务字段中，没有合适的字段作为切分键时，推荐在 ByteHouse CE 表中，定义一个列用缺省值，作为数据表某一列的默认值，您可以用整数或分布均匀的数据来填充，如 HASH 取模或者随机值，然后将该列作为切分键字段，实现并发读取。操作详见 ByteHouse CE 列缺省值实践。