批式导入适用于希望将已准备好的数据一次性加载到 ByteHouse 的场景，当前支持 S3 协议对象存储、Hive、ClickHouse 等数据源。本文将介绍批式导入的功能及如何将不同数据源的数据导入至 ByteHouse。

ByteHouse 支持外置计算引擎的批式导入。相比通过引擎通过 INSERT 插入数据，批式导入功能具有以下特点：

• 支持多线程并行导入，导入大文件的速度更快。
• 导入时直接写 Part 文件，不经过引擎。导入时通过调度 Spark/Flink 资源，采用外部计算资源导入，对查询性能的影响更低。对于存在分区的文件，导入任务生成 Part 后，Part 名字中将带有分区信息。
• 完成完整的 Part 文件后挂载，不会出现 INSERT 导致的 Part 过多，合并慢的情况。

创建批式导入任务后，ByteHouse 支持设置为立即执行或创建定时导入任务，支持编辑、克隆、删除任务，支持查看任务状态和详情。如果导入任务执行过程中出现冲突，ByteHouse 支持您手动解决冲突并恢复任务。

加载模式

使用 ByteHouse 批式导入功能时，最小导入单位为一个完整分区（Partition），而不是行（Row）。分区是 ByteHouse 中表内的逻辑单元，由分区键（Partition Key）作为分隔依据。当前后两次导入中若出现分区字段值重复，就会出现分区冲突。例如，第一次导入产生了 '2022-02-02' 分区，第二次导入中部分行的分区键值也是 '2022-02-02'，导入过程中生成了新的 '2022-02-02' 分区，因此将会产生冲突。
为处理导入时可能存在的冲突，ByteHouse 提供了增量合并、覆盖分区、后续处理、忽略冲突四种加载模式，您可在创建导入任务时通过冲突解决方式参数设置：

• （推荐）增量合并：新导入的分区数据合并入旧分区。
• 覆盖分区：新分区覆盖旧的同名分区。
• 后续处理：每次导入时如果出现分区冲突，当前导入任务将进入待解决冲突状态，您需要手动选择全量加载或增量加载。
• 忽略冲突：新分区如果和旧分区重名，则不导入。

支持的数据源

ByteHouse 企业版支持以下数据源：

• S3 协议对象存储（Object Storage）：支持从标准对象存储服务导入文件数据，包括火山引擎对象存储服务 TOS，阿里云对象存储服务 OSS，AWS S3 服务，自建的 MinIO 等，支持的文件类型包括：CSV，JSON，Parquet。
• Hive：支持从 Hive 表导入数据。
• ClickHouse：支持从 ClickHouse/ByteHouse 表导入数据。

添加数据源前，请确保您已经具备以下必要权限的和信息：

• 请确保数据源和 ByteHouse 集群在网络上是互通的。
• 请确保您使用的数据源的访问账号（例如对象存储的 Access Key/Secret Key）有对应路径和数据库表的访问权限。

在 ByteHouse 企业版中创建目标数据库、表，创建操作请参考新建数据库/表。不同数据源可导入的目标表引擎支持情况不同，说明如下：

创建数据源是为了建立 ByteHouse 与外部数据存储（如对象存储、Hive 等）的连接，为后续导入任务提供数据来源的访问能力。

1. 登录 ByteHouse 企业版控制台，单击顶部数据导入，在右上角切换至目标集群，单击数据源，进入新建数据源界面，单击添加一个新的数据源 >。
   

2. 在右侧新建数据源界面，配置数据源连接信息。不同数据源类型需配置的参数不同，详情请参见以下参数说明。
   

   • 对象存储

     参数项	配置说明
     源类型	选择为 S3。
     源名称	自定义源名称。
     Endpoint	配置为数据源的访问域名。 如果您使用的对象存储为 TOS，可参考 TOS 文档中 S3 **** Endpoint 列获取相关信息，详情请参见地域和访问域名（Endpoint）。
     Region	配置为数据源所在的区域。 如果您使用的对象存储为 TOS，可参考 TOS 文档中 Region ID 列获取相关信息，详情请参见地域和访问域名（Endpoint）。
     访问密钥	配置为数据源的访问密钥（Access Key，AK）。 如果您使用的对象存储为 TOS，获取方式请参见 AccessKey（密钥）管理。
     密钥	配置为数据源的密钥（Secret Key，SK）。 如果您使用的对象存储为 TOS，获取方式请参见 AccessKey（密钥）管理。
     源对象存储为 MinIO	如果您的数据源为 MinIO，请勾选该选项。

   • ClickHouse

     参数项	配置说明
     源类型	选择为 ClickHouse。
     源名称	自定义源名称。
     Clickhouse 主机	配置为您使用的 ClickHouse 服务的主机地址，如果有多个主机地址，请使用逗号（,）连接。示例：192.168.0.1:8123, 192.168.2.234:8123。
     Clickhouse 用户名	配置为您使用的 ClickHouse 服务的用户名。
     Clickhouse 密码	配置为您使用的 ClickHouse 服务的密码。

   • Hive

     参数项	配置说明
     源类型	选择为 Hive。
     源名称	自定义源名称。
     Hive Metastore Uri	配置为 Hive Metastore 服务的访问地址，用于 ByteHouse 获取 Hive 表的元数据。示例：thrift://192.168.0.1:9083。
     hdfs-site.xml 的内容	配置为 Hive 集群中实际使用的 hdfs-site.xml 文件内容，用于 ByteHouse 访问 Hive 表实际存储在 HDFS 上的数据文件。

3. 配置完成后，单击确定，完成数据源的创建。

1. 在数据源模块中，单击目标数据源，在右侧单击新建导入任务，进入新建任务界面。
   
2. 填写导入任务通用信息，自定义任务名称和任务描述，请注意任务名称不可与其他任务名重名。
   确认集群时区是否与导入数据的时区一致。
   
   集群时区需要和导入数据的时区保持一致，否则会引起时间相关列的数据错误。如需调整时区，可单击修改时区，系统将跳转至集群时区配置页面，您可按需选择所在时区。
   
3. 选择并配置数据源。不同数据源需配置的参数不同，您可参考对应数据源的参数说明配置。

   • 对象存储
     源类型选择为 s3，数据源选择为您创建的目标数据源，配置数据源的详细信息，包括存储桶（Bucket）名称、源文件所在的路径、格式等。
     
     如果您的数据源文件格式为 CSV 或 JSON，需为源文件配置对应的格式参数。

     格式	配置项	配置说明
     CSV	字段分隔符	设置数据源文件中不同字段的分隔方式。
     	编码	设置数据源文件的编码格式。
     	引用字符	设置数据源文件使用的包裹特殊字符时使用的符号。
     	转义字符	设置数据源文件中取消“引用字符”原本含义使用的符号。
     	跳过第一行	设置是否忽略数据源文件的第一行内容。
     	第一行包含列标题	设置数据源文件是否包含表头。 无表头：ByteHouse 将使用 "_c0，_c1" 作为源列名来映射模式与目标表。 有表头：ByteHouse 将分离表头来映射模式到目标表上。
     	1 条记录跨多行	设置是否允许一条记录可以包含多行。
     	忽略首尾空格	设置是否忽略源文件每个字段值首尾的空格。
     JSON	1 条记录跨多行	设置是否允许一条记录可以包含多行。
     	允许评论	设置是否允许在文件中添加注释，用于兼容 JSON 文件中存在注释的情况。

   • ClickHouse
     选择数据源类型为 clickhouse，数据源选择为您创建的目标数据源，ClickHouse 数据库选择为待导入的数据库。
     

   • Hive
     选择数据源类型为 Hive，数据源选择为您创建的目标数据源。
     

4. 选择导入的目标数据库和表。
   
5. 定义 Schema 映射。设置数据源和目标表后，系统会自动填充 Schema 映射表，生成数据源与目标表的映射关系。如果生成的 Schema 不符合实际情况，您也可以使用以下方式调整映射关系。
   
   • 数据映射

     说明

     仅对象存储支持通过数据映射调整映射关系。

     1. 单击数据映射，从下拉列表中选择 Schema 描述文件。ByteHouse 会自动读取您设置的对象存储路径中的文件，您可按需选择文件作为 Schema 样例文件。
     2. 选择字段新增方式，支持覆盖添加和增量添加。
     3. 设置完成后，单击确定，ByteHouse 将自动生成新的数据映射。
   • 解析 JSON
     1. 单击 JSON，输入 Schema 映射关系。
     2. 选择字段新增方式，支持覆盖添加和增量添加。
     3. 设置完成后，单击解析，ByteHouse 将自动生成新的数据映射。
   • 解析 SQL
     1. 单击 SQL，输入 Schema 映射关系。
     2. 选择字段新增方式，支持覆盖添加和增量添加。
     3. 设置完成后，单击解析，ByteHouse 将自动生成新的数据映射。
   • 手动调整
     您可在映射表格中手动调整源列与目标列名的映射关系、自定义表达式。

   注意

   注意，目前批式导入不支持表达式（expression）进行简单的数据转换，需要确保源数据和目标数据的数据格式是一致的。

6. 选择分区冲突解决方式，处理导入过程中由于分区字段值重复导致的数据冲突问题。
   • （推荐）增量合并：新导入的分区数据合并入旧分区。
   • 覆盖分区：新分区覆盖旧的同名分区。
   • 忽略冲突：新分区如果和旧分区重名，则不导入。
   • 后续处理：导入时如果出现分区冲突，当前任务状态变为 “有冲突”，进入待解决冲突状态，您可根据新老分区的行数大小，手动选择保留新分区还是旧分区。处理完成后，系统将继续执行导入任务。当前任务暂停时，其他任务不受影响。
7. 选择提交，完成创建。

创建完成后，ByteHouse 将跳转至开始任务界面，您可配置任务并开始导入，支持配置为立即执行任务和定时任务。定时任务支持设置为周期性或一次性任务，您可按需设置任务执行时间。

您也可在数据导入数据导入页签下，单击目标数据源名称，单击导入任务名称，进入任务详情页面，单击开始，进入开始任务界面。

立即执行

1. 在开始任务界面，单击立即执行，选择需导入的文件。不同数据源需配置的参数不同：

   • S3 协议对象存储：选择待导入的文件，支持通过选择文件和输入表达式方式。

     选择方式	配置说明
     文件	从下拉列表中选择文件。该方式支持最多选择 10 个文件，单个文件的上限容量为 2 GB。
     表达式	使用表达式选择文件，适用于需批量选择文件的场景。可使用如下通配符： ? 表示占位符 表示全部 中可输入 0-9, a-z 等 填写示例： data?.json：筛选前缀为 data、后缀为 .json，且中间仅 1 位字符不同的文件。 data[0-100].json：导入文件名称为 data0.json 到 data100.json 的文件。

   • ClickHouse：需要输入待导入数据的 SELECT 语句。

   • Hive：需要设置数据源并行度，并输入待导入的 Hive 数据表名称。并行度默认为 1，并行度的值越高，导入速度越快。

2. 单击运行，ByteHouse 将自动开始执行导入任务。

新建定时任务

1. 在开始任务界面，单击新建定时任务。
2. 选择文件。使用表达式匹配需导入的文件，可使用如下通配符：
   • ? 表示占位符；
   • • 表示全部；
   • 中可输入 0-9, a-z 等。
     填写示例：
   • data?.json：筛选前缀为 data、后缀为 .json，且中间仅 1 位字符不同的文件。
   • data[0-100].json：导入文件名称为 data0.json 到 data100.json 的文件。
     
3. 定义定时任务。输入任务名称，选择执行类型，支持设置为周期性或一次性，并设置执行时间。
   建议在周期任务的设定执行时间，关注任务执行状态，如果出现冲突或任务执行失败，请及时处理异常，避免数据丢失，影响业务。任务失败或冲突处理方式请参见任务跟踪。
   
4. 单击创建，ByteHouse 将在您设置的时间执行导入任务。

开启任务后，您可在任务详情页面，查看当前执行的导入任务，查看任务状态、执行时间、数据源信息、目标数据表、导入信息等。

• 若执行状态是“已停止”（灰色图标），表明当前任务已经成功。
• 若执行状态是“失败”（红色叉号），您可单击执行 ID，将鼠标悬浮在“失败图标”上方，单击查看更多，查看报错信息，并对应调整配置。
• 若执行状态是“有冲突”（红色感叹号），您可按照冲突处理步骤解决冲突，操作详情请参见处理冲突。

处理冲突

1. 在任务详情页单击恢复任务，查看分区冲突详情，解决冲突。
   
2. 按需选择冲突处理方式，并单击替换分区并恢复任务。
   • 勾选分区：表示保留新分区，老分区的数据完全丢弃。
   • 不勾选分区：表示保留老分区，丢弃新导入的分区。
     

冲突处理完成后，导入任务即会完成，任务进入“已停止”状态，即代表导入成功。

编辑任务

任务创建完成后，您可通过编辑任务调整任务配置信息，当前支持编辑任务名称、描述、目标表 Schema 配置、冲突解决方式。

1. 在数据源界面，单击目标数据源，单击任务名称，进入任务详情页。
2. 单击右上角 ... 按钮，单击编辑任务。
   
3. 在任务编辑界面，您可按需调整任务配置。
   
4. 修改完成后，单击提交，修改的内容将即时生效。

克隆任务

您可基于已有任务克隆任务，并按需调整。克隆任务时，数据源类型不可修改。

1. 在数据源界面，单击目标数据源，单击任务名称，进入任务详情页。
2. 单击右上角 ... 按钮，单击克隆。
   
3. 在克隆导入任务界面，配置任务，操作步骤可参考创建导入任务。
   
4. 配置完成后，单击提交，修改的内容将即时生效。

删除任务

如果您不再需要某任务，可删除该任务。

1. 在数据源界面，单击目标数据源，单击任务名称，进入任务详情页。
2. 单击右上角 ... 按钮，单击删除。
   
3. 单击确定，即可删除任务。