本文将介绍如何将小文件通过本地文件、对象存储、HDFS 等数据源导入至 ByteHouse。

当您需要测试文件导入，或导入的文件体积较小时（如几 KB 至几十 MB 的小批量数据）时，推荐通过 INSERT INTO 语句完成导入，效率更优。 从导入效率来看，使用批式导入处理对象存储数据源，该过程需要调度 Spark 资源，即使是几 KB 的文件，也需分钟级导入。而 INSERT INTO 方式直接从对象存储读取数据写入 ByteHouse，无需依赖 Spark 资源调度，能快速完成导入。
ByteHouse 从小文件导入功能支持本地文件、对象存储、HDFS 数据源：

• 从本地文件导入至 ByteHouse 时，需确保您使用的工具和文件均在本地，推荐通过 ClickHouse Client 连接 ByteHouse 并结合 INSERT INTO 语句完成导入，导入方式更简单便捷。
• 从对象存储导入和从 HDFS 导入可使用能执行 SQL 语句的连接工具，您可使用 ByteHouse 企业版控制台的查询窗口或使用其他连接工具连接 ByteHouse，并使用 INSERT INTO 语句完成导入。连接 ByteHouse 操作详情请参考查询窗口和连接集群。

• 每次执行 INSERT INTO 时，会占用 ByteHouse 集群的 CPU 资源，可能与正在运行的查询任务争抢资源，导致查询响应延迟或性能下降。批式导入功能则采用旁路写入，使用 Spark 集群的 CPU 资源，因此不会发生抢占。
• 如果直接向 Distributed 分布式表执行 INSERT INTO（如下文示例场景），当集群分片数大于 1 时，数据需在分片间进行路由分发，会产生额外的网络传输和数据处理开销，导致导入性能较差。建议您将源数据按分片规则拆分后，分别向各节点的本地表（即示例中的 Local 表）执行导入，可减少资源消耗，提升导入效率。
• 基于上述资源占用特性与性能局限，从小文件导入方式仅适合于导入测试，不适合于实际生产。如果您需要导入大批量数据可参考批式导入或流式导入。

从本地文件导入

clickhouse client \
  --host <host> \
  --user <user> \
  --password <password> \
  --query "INSERT INTO <database_name>.<table_name> FORMAT format SETTINGS key1=value1, key2=value2" \
  < File_Name.csv \

您也可以使用 Cat 命令：

cat File_Name.csv | clickhouse-client \
    --host <host> \
    --user <user> \
    --password <password> \
    --query="INSERT INTO <database_name>.<table_name> FORMAT format SETTINGS key1=value1, key2=value2";

参数说明

从对象存储导入

INSERT INTO <database_name>.<table_name>
SELECT * FROM s3(
    path, 
    access_key_id,
    secret_access_key,
    format,
    structure,
    [compression]
)
[SETTINGS key1=value1, key2=value2];

参数说明

https://{bucket_name}.endpoint/file_path/file

https://{bucket_name}.tos-s3-{region}.ivolces.com/file_path/file

从 HDFS 导入

INSERT INTO <database_name>.<table_name>
SELECT * 
FROM hdfs(
    'path', 
    'format',                    
    'structure'
)
[SETTINGS key1=value1, key2=value2];

参数说明

Settings 配置

在执行 SQL 语句时，您可根据 CSV 数据的实际格式，按需添加以下 Settings 配置项，灵活适配数据读写需求。

创建 ByteHouse 目标数据库、表

在 ByteHouse 中创建目标数据库、表，请确保目标表与源表结构一致，操作详情请参见新建数据库/表。
本文示例以 HaMergeTree 表为例，建表语句如下：

-- 创建数据库
CREATE DATABASE IF NOT EXISTS test_db

-- 创建 Local 本地表
CREATE TABLE IF NOT EXISTS test_db.test_table_local ON CLUSTER default_cluster
(
    `id` String,
    `name` String,
    `date` Date
)
ENGINE = HaMergeTree('/clickhouse/tables/test_db/test_table_local/{shard}', '{replica}')
ORDER BY id;

-- 创建 Distributed 分布式表
CREATE TABLE IF NOT EXISTS test_db.test_table ON CLUSTER default_cluster
AS test_db.test_table_local
ENGINE = Distributed('default_cluster', 'test_db', 'test_table_local', rand());

从本地文件导入

准备工作

安装 ClickHouse Client 工具，点此下载。

操作步骤

1. 准备本地文件 test.csv，并写入数据如下。确保本地 CSV 文件的字段顺序与目标表的字段顺序一致。

   $ cat /test.csv
       A001,Amy,2023-01-01
       A002,Bob,2023-01-02
       A003,Charles,2023-01-03
   

2. 使用 ClickHouse Client 向目标表写入数据。

   cat test.csv | clickhouse-client \
       --host 2xxxxxxxxxxxxxxxxx.bytehouse-ce.ivolces.com \
       --user demo_user \
       --password Mt**************  \
       --query="INSERT INTO test_db.test_table_local FORMAT CSV";
   

3. 查询是否写入成功。

   SELECT * FROM test_db.test_table;
   

从对象存储导入

本示例将演示如何使用 ClickHouse s3() 函数，将本地文件中的数据写入到准备工作章节创建的 ByteHouse 表中。

准备工作

在开始操作前，请确保您已经具备您使用的对象存储桶的访问权限：

• 获取 Access Key ID（AK） 与 Secret Access Key（SK）。如果您使用的是火山引擎对象存储服务（TOS），获取详情请参考 Access Key（密钥）管理。
• 如果您使用 TOS 时出现 “Access Denied” 报错，请排查权限问题，详情请参考对象存储 Access Denied 排查建议。

操作步骤

1. 构建 Schema 映射。此步骤用于获取目标表的字段名和字段类型，确保源数据与目标表结构匹配，避免导入时因结构不匹配导致失败。

   SELECT arrayStringConcat(groupArray(concat(name, ' ', type)), ', ')  
   FROM system.columns 
   WHERE DATABASE = '<database_name>' AND TABLE = '<table_name>'
   

2. 从对象存储中导入数据至 ByteHouse。

   INSERT INTO test_db.test_table_local
   SELECT *
   FROM s3(
       'https://bucket.endpoint/file_path/test_outfile.csv', 
       'AK***************',                                 
       'aBc********************',                
       'CSV',                                          
       '(id String, name String, date Date)',  
       'none',                                           
   );
   

3. 查询是否写入成功。

   SELECT * FROM test_db.test_table;
   

从 HDFS 导入

本示例将演示如何使用 ClickHouse hdfs() 函数，将本地文件中的数据写入到准备工作章节创建的 ByteHouse 表中。

准备工作

在开始操作前，请确保您已经获取 HDFS 文件的访问路径，且具备该路径的访问权限。

操作步骤

1. 从 HDFS 中导入数据至 ByteHouse。

   INSERT INTO test_db.test_table_local 
   SELECT * 
   FROM hdfs(
       'hdfs://192.168.x.xxx:8020/user/data/202509_user.csv',
       'CSV',
       '(id String, name String, date Date)'
   );
   

2. 查询是否写入成功。

   SELECT * FROM test_db.test_table;
   

Code: 27

如果您在使用中遇到以下报错：

Code: 27, e.displayText() = DB::ParsingException:Cannot parse input: expected '\\N' before: ... (version 21.8.7.1) 

• 问题原因：
  出现这一报错的原因，一般是由于 CSV 文件中的字符串存在不被单引号或双引号包围，且内容中存在反斜杠 \，如 aaa,bbb,cc\c，这种情况会被 ByteHouse 视作特殊字符。
• 解决方法：
  • 在数据源中，将字符串都置于双引号或单引号中，这样 ByteHouse 会认为反斜杠是字符串的一部分。
  • 在插入时设置 input_format_null_as_default = 0，即 ByteHouse 不再识别 \N 为 Null。但此种方案将导致无法导入 Null 值。