使用 LOAD DATA 语句导入数据

概述

本文说明如何在 OceanBase AI 数据库中通过 LOAD DATA 将外部数据写入内表，并在满足条件时启用 旁路导入（APPEND / direct(...) 等 Hint，或依赖租户级配置项 default_load_mode），以提升大批量装载吞吐。

语法

-- FROM FILES()
LOAD DATA /*+ [APPEND | DIRECT(need_sort,max_error,{'full'|'inc'|'inc_replace'})] parallel(N) */ FROM FILES(...) INTO TABLE table_name ...;

-- 客户端本地文件（不支持旁路导入）
LOAD DATA LOCAL INFILE 'file_name' INTO TABLE table_name ...;

`LOAD DATA` 按数据读取位置的分类与语法关系

路径 / 语法	数据所在位置	典型适用场景	语法关系与说明	限制 / 配置 / 补充
`LOAD DATA FROM FILES(...)`	由 `FILES` 子句描述的服务端可访问路径（本地目录、对象存储 URL、HDFS 等，以手册为准）	单条语句描述 `LOCATION / FORMAT / PATTERN`，适合 CSV / ORC / Parquet 等批量扫描与错误诊断	通过 `FROM FILES(LOCATION = ..., FORMAT = (...), [PATTERN = ...])` 声明待扫描文件集合，由服务端按格式解析后写入目标表；可与 `LOG ERRORS` 等子句配合做导入期错误诊断	旁路场景下，可在 `LOAD DATA` 关键字后添加 `/+ direct(...) parallel(N) /` 等 Hint
`LOAD DATA ... INFILE 'path'`（无 `LOCAL`）	OBServer 进程可读的服务器文件系统路径	文件已下发至数据库节点或共享存储；常配合 `secure_file_priv`	不写 `LOCAL`、且 `INFILE` 为 OBServer 上路径时，由服务端直接读取该文件（或通配符匹配的一组文件）	需将路径配置在 `secure_file_priv` 允许的范围内；修改该变量通常需经本地 Unix Socket 连接执行
`LOAD DATA ... LOCAL INFILE 'path'`	发起连接的客户端本机路径	文件仅存在于客户端；连接需启用 `--local-infile`	关键字 `LOCAL` 表明文件位于客户端本机；客户端读取后上传至服务端完成解析与写入	连接时请使用 `obclient --local-infile`（或等效选项）启用本地装载能力；`LOCAL INFILE` 不支持旁路导入

说明

全量旁路导入与增量旁路导入的适用范围、差异及更完整的旁路导入能力说明，请参见数据导入概述。

各参数的完整定义及语法细节，请参见 LOAD DATA 语法。

示例

全量旁路导入（direct(..., 'full')）通常用于空表首次装载或整体基线导入；

增量旁路导入（direct(..., 'inc') 或 'inc_replace'）通常用于目标表已有数据基础上的追加装载。

两者在 DIRECT() 第三参数、目标表状态及适用限制上不同。关于全量旁路导入与增量旁路导入的差异、适用场景及限制，参见数据导入概述。

下文示例以全量旁路导入为主；增量旁路导入的 Hint 写法相同，仅将第三参数改为 'inc' 或 'inc_replace'。

LOAD DATA FROM FILES

登录到需要连接 OBServer 节点所在的机器上，在 /home/admin 目录下准备待扫描的数据文件（LOCATION 指向 服务端可访问路径，可为该目录下的 CSV / ORC / Parquet 等，本示例以 CSV 为例）。

说明

FROM FILES 中的 LOCATION 须为 OBServer 能访问的路径；目录及文件建议置于 secure_file_priv 允许的范围内（与 LOAD DATA INFILE 相同）。
1. 进入 OBServer 节点所在的机器。
```
[xxx@xxx /home/admin]# ssh admin@10.10.10.1
```
2. 创建测试数据 tbl1.csv（与上文 LOAD DATA INFILE 示例中文件内容一致，便于对照）。
```
[admin@xxx /home/admin]# vi tbl1.csv
1,11
2,22
3,33
```
设置导入的文件路径。

设置系统变量 secure_file_priv，配置导入或导出文件时可以访问的路径。

注意

由于安全原因，设置系统变量 secure_file_priv 时，只能通过本地 Unix Socket 连接数据库执行修改该全局变量的 SQL 语句。更多信息，请参见 secure_file_priv。
1. 登录到需要连接 OBServer 节点所在的机器上。
```
[xxx@xxx /home/admin]# ssh admin@10.10.10.1
```
2. 执行以下命令，通过本地 Unix Socket 连接方式连接租户 mysql001。
```
obclient -S /home/admin/oceanbase/run/sql.sock -uroot@mysql001 -p******
```
3. 设置导入路径为 /home/admin。
```
obclient [(none)]> SET GLOBAL secure_file_priv = "/home/admin";
Query OK, 0 rows affected
```

重新连接数据库后，使用 LOAD DATA FROM FILES 与旁路 Hint 导入数据。

创建表 tbl2（表结构与上文 LOAD DATA INFILE 全量示例一致）。

obclient [test]> CREATE TABLE tbl2 (
                    col1 INT PRIMARY KEY,
                    col2 INT
                 )
                 PARTITION BY RANGE (col1)
                    SUBPARTITION BY RANGE (col1) (
                       PARTITION p0 VALUES LESS THAN (100) (
                             SUBPARTITION p0_1 VALUES LESS THAN (50),
                             SUBPARTITION p0_2 VALUES LESS THAN (100)
                       ),
                       PARTITION p1 VALUES LESS THAN (200) (
                             SUBPARTITION p1_1 VALUES LESS THAN (150),
                             SUBPARTITION p1_2 VALUES LESS THAN (200)
                       )
                 );
Query OK, 0 rows affected

查询表 tbl2 是否有数据，此时显示表为空。
```
obclient [test]> SELECT * FROM tbl2;
Empty set
```

使用旁路导入将 tbl1.csv 扫描并导入到表 tbl2。

如果你需要使用增量旁路导入的方式导入数据，语法示例可以参考：

obclient [test]> LOAD DATA /*+ direct(true,1024,'inc') parallel(16) */ FROM FILES(
    LOCATION = '/home/admin',
    FORMAT = (TYPE = 'CSV', FIELD_DELIMITER = ','),
    PATTERN = 'tbl1.csv'
) INTO TABLE tbl2;

或：

obclient [test]> LOAD DATA /*+ direct(true,1024,'inc_replace') parallel(16) */ FROM FILES(
    LOCATION = '/home/admin',
    FORMAT = (TYPE = 'CSV', FIELD_DELIMITER = ','),
    PATTERN = 'tbl1.csv'
) INTO TABLE tbl2;

后续步骤中，将以全量旁路导入数据方式的示例接续讲解。

指定表 tbl2 的全部列导入数据。

obclient [test]> LOAD DATA /*+ direct(true,1024,'full') parallel(16) */ FROM FILES(
    LOCATION = '/home/admin',
    FORMAT = (TYPE = 'CSV', FIELD_DELIMITER = ','),
    PATTERN = 'tbl1.csv'
) INTO TABLE tbl2;
Query OK, 3 rows affected
Records: 3  Deleted: 0  Skipped: 0  Warnings: 0

指定表 tbl2 的指定列导入数据。例如指定 col1，col2 列。

obclient [test]> LOAD DATA /*+ direct(true,1024,'full') parallel(16) */ FROM FILES(
    LOCATION = '/home/admin',
    FORMAT = (TYPE = 'CSV', FIELD_DELIMITER = ','),
    PATTERN = 'tbl1.csv'
) INTO TABLE tbl2 (col1,col2);
Query OK, 3 rows affected
Records: 3  Deleted: 0  Skipped: 0  Warnings: 0

指定表 tbl2 的一级分区导入数据。

obclient [test]> LOAD DATA /*+ direct(true,1024,'full') parallel(16) */ FROM FILES(
    LOCATION = '/home/admin',
    FORMAT = (TYPE = 'CSV', FIELD_DELIMITER = ','),
    PATTERN = 'tbl1.csv'
) INTO TABLE tbl2 partition(p0, p1);

指定表 tbl2 的二级分区导入数据。

obclient [test]> LOAD DATA /*+ direct(true,1024,'full') parallel(16) */ FROM FILES(
    LOCATION = '/home/admin',
    FORMAT = (TYPE = 'CSV', FIELD_DELIMITER = ','),
    PATTERN = 'tbl1.csv'
) INTO TABLE tbl2 partition(p0sp0_1, p1sp1_1);

（可选）结合 LOG ERRORS 做导入期错误诊断（需当前版本支持该子句时方可使用）。

obclient [test]> LOAD DATA /*+ direct(true,1024,'full') parallel(16) */ FROM FILES(
    LOCATION = '/home/admin',
    FORMAT = (TYPE = 'CSV', FIELD_DELIMITER = ','),
    PATTERN = 'tbl1.csv'
) INTO TABLE tbl2
LOG ERRORS REJECT LIMIT UNLIMITED;

使用配置项 default_load_mode 导入数据。

设置 default_load_mode 的值为 FULL_DIRECT_WRITE。

obclient [test]> ALTER SYSTEM SET default_load_mode ='FULL_DIRECT_WRITE';

不指定 LOAD DATA 语句的 Hint。

obclient [test]> LOAD DATA FROM FILES(
    LOCATION = '/home/admin',
    FORMAT = (TYPE = 'CSV', FIELD_DELIMITER = ','),
    PATTERN = 'tbl1.csv'
) INTO TABLE tbl2;

验证表 tbl2 中是否已导入数据。

obclient [test]> SELECT * FROM tbl2;

查询结果如下：

 +------+------+
 | col1 | col2 |
 +------+------+
 |    1 |   11 |
 |    2 |   22 |
 |    3 |   33 |
 +------+------+
 3 rows in set

结果显示表 tbl2 中已导入数据。

LOAD DATA INFILE

登录到需要连接 OBServer 节点所在的机器上，在 /home/admin 目录下创建测试数据。

说明

OceanBase AI 数据库中的 LOAD DATA 语句仅支持加载 OBServer 节点本地的输入文件。因此，需要在导入之前将文件拷贝到某台 OBServer 上。
1. 进入 OBServer 节点所在的机器。
```
[xxx@xxx /home/admin]# ssh admin@10.10.10.1
```
2. 创建测试数据 tbl1.csv。
```
[admin@xxx /home/admin]# vi tbl1.csv
1,11
2,22
3,33
```
设置导入的文件路径。

设置系统变量 secure_file_priv，配置导入或导出文件时可以访问的路径。

注意

由于安全原因，设置系统变量 secure_file_priv 时，只能通过本地 Unix Socket 连接数据库执行修改该全局变量的 SQL 语句。更多信息，请参见 secure_file_priv。
1. 登录到需要连接 OBServer 节点所在的机器上。
```
[xxx@xxx /home/admin]# ssh admin@10.10.10.1
```
2. 执行以下命令，通过本地 Unix Socket 连接方式连接租户 mysql001。
```
obclient -S /home/admin/oceanbase/run/sql.sock -uroot@mysql001 -p******
```
3. 设置导入路径为 /home/admin。
```
obclient [(none)]> SET GLOBAL secure_file_priv = "/home/admin";
Query OK, 0 rows affected
```

重新连接数据库后，使用 LOAD /*+ DIRECT */ DATA 语句导入数据。

创建表 tbl2。

obclient [test]> CREATE TABLE tbl2 (
                    col1 INT PRIMARY KEY,
                    col2 INT
                 )
                 PARTITION BY RANGE (col1)
                    SUBPARTITION BY RANGE (col1) (
                       PARTITION p0 VALUES LESS THAN (100) (
                             SUBPARTITION p0_1 VALUES LESS THAN (50),
                             SUBPARTITION p0_2 VALUES LESS THAN (100)
                       ),                           
                       PARTITION p1 VALUES LESS THAN (200) (
                             SUBPARTITION p1_1 VALUES LESS THAN (150),
                             SUBPARTITION p1_2 VALUES LESS THAN (200)
                       )
                 );
Query OK, 0 rows affected

查询表 tbl2 是否有数据，此时显示表为空。
```
obclient [test]> SELECT * FROM tbl2;
Empty set
```

使用旁路导入将 tbl1.csv 文件中的数据导入到表 tbl2。

如果你需要使用增量旁路导入的方式导入数据，语法示例可以参考：

obclient [test]> LOAD DATA /*+ direct(true,1024,'inc') parallel(16) */ INFILE '/home/admin/tbl1.csv' INTO TABLE tbl2 FIELDS TERMINATED BY ',';

或：

obclient [test]> LOAD DATA /*+ direct(true,1024,'inc_replace') parallel(16) */ INFILE '/home/admin/tbl1.csv' INTO TABLE tbl2 FIELDS TERMINATED BY ',';

后续步骤中，将以全量旁路导入数据方式的示例接续讲解。

指定表 tbl2 的所有列导入数据。

obclient [test]> LOAD DATA /*+ direct(true,1024,'full') parallel(16) */ INFILE '/home/admin/tbl1.csv' INTO TABLE tbl2 FIELDS TERMINATED BY ',';
Query OK, 3 rows affected
Records: 3  Deleted: 0  Skipped: 0  Warnings: 0

指定表 tbl2 的指定任意列导入数据。例如指定 col1，col2 列。

obclient [test]> LOAD DATA /*+ direct(true,1024,'full') parallel(16) */ INFILE '/home/admin/tbl1.csv' INTO TABLE tbl2 FIELDS TERMINATED BY ','(col1,col2);
Query OK, 3 rows affected
Records: 3  Deleted: 0  Skipped: 0  Warnings: 0

指定表 tbl2 的一级分区导入数据。

obclient [test]> LOAD DATA /*+ direct(true,1024,'full') parallel(16) */ INFILE '/home/admin/tbl1.csv' INTO TABLE tbl2 partition(p0, p1)  FIELDS TERMINATED BY ',';

指定表 tbl2 的二级分区导入数据。

obclient [test]> LOAD DATA /*+ direct(true,1024,'full') parallel(16) */ INFILE '/home/admin/tbl1.csv' INTO TABLE tbl2 partition(p0sp0_1, p1sp1_1)  FIELDS TERMINATED BY ',';

使用配置项 default_load_mode 导入数据。

设置 default_load_mode 的值为 FULL_DIRECT_WRITE。

obclient [test]> ALTER SYSTEM SET default_load_mode ='FULL_DIRECT_WRITE';

不指定 LOAD DATA 语句的 Hint。

obclient [test]> LOAD DATA INFILE '/home/admin/tbl1.csv' INTO TABLE tbl2 FIELDS TERMINATED BY ',';

验证表 tbl2 中是否已导入数据。

obclient [test]>  SELECT * FROM tbl2;

查询结果如下：

 +------+------+
 | col1 | col2 |
 +------+------+
 |    1 |   11 |
 |    2 |   22 |
 |    3 |   33 |
 +------+------+
 3 rows in set

结果显示表 tbl2 中已导入数据。

LOAD DATA LOCAL INFILE

在 运行 obclient 的客户端本机 准备数据文件（路径为 客户端本地路径，勿与 OBServer 上路径混淆）。文件内容与上文示例一致，仍命名为 tbl1.csv。

说明

LOCAL INFILE 表示由客户端读取本地文件并上传至服务端；连接命令需携带 --local-infile（或等效选项）。LOAD DATA LOCAL INFILE 不支持旁路导入，因此请勿添加 APPEND / DIRECT(...) Hint。
1. 在客户端创建数据文件（示例路径 /home/admin/client_csv/tbl1.csv，请按实际客户端环境调整目录）。
```
mkdir -p /home/admin/client_csv
vi /home/admin/client_csv/tbl1.csv
```
  文件内容如下：
```
1,11
2,22
3,33
```
使用本地 infile 能力连接数据库并进入目标库（示例为租户 mysql001 下 test 库）。
```
obclient --local-infile -h10.10.10.1 -P2881 -uroot@mysql001 -p****** -Dtest
```

使用 LOAD DATA LOCAL INFILE 导入数据（非旁路）。

创建表 tbl2（表结构与上文 LOAD DATA INFILE 全量示例一致）。

obclient [test]> CREATE TABLE tbl2 (
                    col1 INT PRIMARY KEY,
                    col2 INT
                 )
                 PARTITION BY RANGE (col1)
                    SUBPARTITION BY RANGE (col1) (
                       PARTITION p0 VALUES LESS THAN (100) (
                             SUBPARTITION p0_1 VALUES LESS THAN (50),
                             SUBPARTITION p0_2 VALUES LESS THAN (100)
                       ),
                       PARTITION p1 VALUES LESS THAN (200) (
                             SUBPARTITION p1_1 VALUES LESS THAN (150),
                             SUBPARTITION p1_2 VALUES LESS THAN (200)
                       )
                 );
Query OK, 0 rows affected

查询表 tbl2 是否有数据，此时显示表为空。
```
obclient [test]> SELECT * FROM tbl2;
Empty set
```

使用 LOAD DATA LOCAL INFILE 将客户端 tbl1.csv 导入到表 tbl2。

指定表 tbl2 的全部列导入数据。

obclient [test]> LOAD DATA LOCAL INFILE '/home/admin/client_csv/tbl1.csv' INTO TABLE tbl2 FIELDS TERMINATED BY ',';
Query OK, 3 rows affected
Records: 3  Deleted: 0  Skipped: 0  Warnings: 0

指定表 tbl2 的指定列导入数据。例如指定 col1，col2 列。

obclient [test]> LOAD DATA LOCAL INFILE '/home/admin/client_csv/tbl1.csv' INTO TABLE tbl2 FIELDS TERMINATED BY ','(col1,col2);
Query OK, 3 rows affected
Records: 3  Deleted: 0  Skipped: 0  Warnings: 0

指定表 tbl2 的一级分区导入数据。

obclient [test]> LOAD DATA LOCAL INFILE '/home/admin/client_csv/tbl1.csv' INTO TABLE tbl2 partition(p0, p1)  FIELDS TERMINATED BY ',';

指定表 tbl2 的二级分区导入数据。

obclient [test]> LOAD DATA LOCAL INFILE '/home/admin/client_csv/tbl1.csv' INTO TABLE tbl2 partition(p0sp0_1, p1sp1_1)  FIELDS TERMINATED BY ',';

LOCAL INFILE 形态不适用 default_load_mode 的旁路导入模式；可直接执行如下语句：

obclient [test]> LOAD DATA LOCAL INFILE '/home/admin/client_csv/tbl1.csv' INTO TABLE tbl2 FIELDS TERMINATED BY ',';

验证表 tbl2 中是否已导入数据。

obclient [test]> SELECT * FROM tbl2;

查询结果如下：

 +------+------+
 | col1 | col2 |
 +------+------+
 |    1 |   11 |
 |    2 |   22 |
 |    3 |   33 |
 +------+------+
 3 rows in set

结果显示表 tbl2 中已导入数据。

概述

语法

LOAD DATA 按数据读取位置的分类与语法关系

说明

示例

LOAD DATA FROM FILES

说明

注意

LOAD DATA INFILE

说明

注意

LOAD DATA LOCAL INFILE

说明

`LOAD DATA` 按数据读取位置的分类与语法关系