# 批量导入本地数据文件至ClickHouse集群
#### 操作场景
当本地存在较多数据文件需要导入ClickHouse时，用户可以使用多线程导入工具批量导入ClickHouse。
多线程导入工具通过并行处理多个任务，显著提高数据导入的速度和效率。
- 提高处理速度：多线程可以充分利用多核CPU的计算能力，同时处理多个数据文件，从而显著减少数据导入的总时间。
- 资源高效利用：通过并行处理，可以更高效地利用系统资源，提高整体性能。
- 提高导入效率：多线程导入工具可以有效地管理并发任务，确保数据导入过程更加顺畅和高效。
**典型应用场景：**
- 日志文件批量导入：将服务器或应用产生的日志文件（如CSV、TSV格式）批量导入ClickHouse进行分析。
- 历史数据迁移归档：将其他大数据系统（如HDFS、Hive）中的历史数据导出后批量导入ClickHouse。
 
#### 约束与限制
- 本章节仅适用于MRS 3.3.0-LTS及之后版本。
- 导入过程中会对ClickHouse集群产生写入压力，建议在业务低峰期执行大规模数据导入。
 
#### 前提条件
- 已安装ClickHouse客户端，例如客户端安装目录为"/opt/client"。
- 如果集群为安全模式需要创建一个具有ClickHouse相关权限的用户，例如创建用户"clickhouseuser"，具体请参考[创建具有ClickHouse权限的用户](https://support.huaweicloud.com/cmpntguide-lts-mrs/mrs_01_24057.html)。
- 准备待导入的数据文件，并将数据文件上传到客户端节点目录，例如上传到目录"/opt/data"。 ClickHouse支持的所有数据类型请参考：<https://clickhouse.com/docs/en/interfaces/formats>
  
 
#### 操作步骤
1. 以客户端安装用户，登录客户端所在节点。
2. 进入多线程写入工具"clickhouse_insert_tool"所在目录： 
   ```
   cd /opt/client/ClickHouse/clickhouse_insert_tool
   ```
   
   
3. 使用文本编辑器打开clickhouse_insert_tool.sh，按照注释填写所需信息： 
   
   | 参数                  | 参数描述                                                                                                                                                                                                                                     | 示例                            |
   |:---|:---|:---|
   | datapath            | 待导入数据所在目录。                                                                                                                                                                                                                               | /opt/data                     |
   | balancer_ip_list    | ClickHouse服务Balancer实例IP地址列表，整体使用括号括起，单个IP使用双引号引起，IP之间使用空格分隔。 Balancer IP地址可通过登录FusionInsight Manager，选择"集群 \> 服务 \> ClickHouse \> 实例"查看Balancer实例获取。                                                  | ("192.168.1.1" "192.168.1.2") |
   | balancer_tcp_port   | ClickHouse服务Balancer实例TCP端口。                                                                                                                                                                                                             | 21428                         |
   | local_table_name    | 待导入的本地库名.本地表名。                                                                                                                                                                                                                           | testdb1.testtb1               |
   | thread_num          | 并发导入线程数。                                                                                                                                                                                                                                 | 10                            |
   | data_format         | 待导入数据的格式。支持格式包括CSV、TSV、JSONEachRow、Parquet、ORC等。                                                                                                                                                                                         | CSV                           |
   | is_security_cluster | 集群是否为安全模式。 - true：表示安全模式  - false：表示普通模式   | true                          |
      
   
   
4. 保存修改后的 "clickhouse_insert_tool.sh"，并执行如下命： 
   进入客户端目录：
   ```
   cd /opt/client
   ```
   配置环境变量：
   ```
   source bigdata_env
   ```
   安全模式（开启Kerberos认证）执行kinit命令，普通模式（关闭Kerberos认证）无需执行：
   ```
   kinit clickhouseuser
   ```
   
   
5. 运行脚本，导入数据。 
   ```
   ./ClickHouse/clickhouse_insert_tool/clickhouse_insert_tool.sh
   ```
   
   
6. 登录ClickHouse客户端节点，连接服务端，具体请参考[ClickHouse客户端使用实践](https://support.huaweicloud.com/cmpntguide-lts-mrs/mrs_01_2345.html)。
7. 执行如下命令，查询插入数据的本地表对应的分布式表，查看结果是否符合预期： 
   ```
   select count(1) from testdb1.testtb1_all;
   ```
   
   
 
#### 相关文档
- 了解如何安装和使用ClickHouse客户端连接ClickHouse服务，具体请参考[ClickHouse客户端使用实践](https://support.huaweicloud.com/cmpntguide-lts-mrs/mrs_01_2345.html)。
- 了解更多ClickHouse用户权限管理（如修改、删除租户等），具体请参考[ClickHouse用户权限管理](https://support.huaweicloud.com/cmpntguide-lts-mrs/mrs_01_24251.html)。
- 如需配置ClickHouse冷热分离策略，将冷数据迁移至OBS以降低存储成本，请参考[配置ClickHouse冷热分离](https://support.huaweicloud.com/cmpntguide-lts-mrs/mrs_01_2493081.html)。

- **常见问题：**
  - **导入失败提示Connection refused**：请检查balancer_ip_list和balancer_tcp_port配置是否正确，确认Balancer实例状态正常，可通过FusionInsight Manager查看Balancer实例状态。
  
  - **导入失败提示Authentication failed**：安全模式下请确认已执行kinit命令完成Kerberos认证，且认证用户具有目标表的写入权限。
  
  - **数据格式不匹配导致导入失败**：请确认data_format参数与实际数据文件格式一致，数据文件的列顺序和数据类型与目标本地表结构匹配。
  
  - **线程数设置过大导致内存溢出**：请降低thread_num参数值，建议设置为客户端节点CPU核数的1\~2倍，同时确认客户端节点可用内存充足。
  
  - **导入完成后数据量不匹配**：请查看导入日志中成功和失败的行数，检查失败行数对应的数据文件是否有格式异常或数据缺失。通过查询分布式表count与源文件行数对比确认数据完整性。