---
title: "LOAD DATA - OceanBase 数据库 V4.2.1 | OceanBase 文档中心"
description: LOAD DATA 描述 该语句用于加载外部文件的数据到数据库表中。 LOAD DATA 目前可以对 CSV 格式的文本文件进行导入，整个导入的过程可以分为以下的流程： 解析文件：OceanBase 数据库会根据用户输入的文件名，读取文件中的数据，并且根据指定的并行度来决定并行或者串行解析输入文件中的数据。 分发数据…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.2.1 LTS

# LOAD DATA

更新时间：2026-07-15 20:56:55

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.2.1/zh-CN/700.reference/500.sql-reference/100.sql-syntax/200.common-tenant-of-mysql-mode/600.sql-statement-of-mysql-mode/5900.load-data-of-mysql-mode.md)  

## 描述

该语句用于加载外部文件的数据到数据库表中。

`LOAD DATA` 目前可以对 CSV 格式的文本文件进行导入，整个导入的过程可以分为以下的流程：

1. 解析文件：OceanBase 数据库会根据用户输入的文件名，读取文件中的数据，并且根据指定的并行度来决定并行或者串行解析输入文件中的数据。
 2. 分发数据：由于 OceanBase 是分布式数据库，各个分区的数据可能分布在各个不同的 OBServer 节点，`LOAD DATA` 会对解析出来的数据进行计算，决定数据需要被发送到哪个 OBServer 节点。
 3. 插入数据：当目标 OBServer 节点收到数据后，在本地执行 `INSERT` 操作将数据插入到对应的分区当中。

## 使用限制及注意事项

### 使用限制

- 带有触发器（Trigger）的表禁止使用 `LOAD DATA` 语句。
 - 当前版本暂不支持加载本地（`LOCAL`）数据文件。

### 注意事项

为了提高数据导入速率，OceanBase 数据库在 `LOAD DATA` 操作中采用了并行设计。在该过程中，需要导入的数据被划分为多个子任务以并行方式执行，每个子任务都作为一个独立的事务进行处理，并且执行顺序是随机的。因此，需要注意以下事项：

- 无法保证整体数据导入的原子性。
 - 对于无主键表来说，数据写入的顺序可能与文件中的数据顺序不一致。

## 权限要求

执行 `LOAD DATA` 语句，需要拥有 `FILE` 权限和对应表的 `INSERT` 权限。有关 OceanBase 数据库权限的详细介绍，请参见 [MySQL 模式下的权限分类](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000220876)。

**示例如下：**

- 要为用户授予 `FILE` 权限，可以使用以下命令格式：

  ```sql
  GRANT FILE ON *.* TO user_name;

  ```

  其中，`user_name` 是需要执行 `LOAD DATA` 命令的用户。
 - 要为用户授予 `INSERT` 权限，可以使用以下命令格式：

  ```sql
  GRANT INSERT ON database_name.tbl_name TO user_name;

  ```

  其中，`database_name` 是数据库名称，`tbl_name` 是表名，`user_name` 是需要执行 `LOAD DATA` 命令的用户。

## 语法

```sql
LOAD DATA [hint_options]
    [REMOTE_OSS]
    INFILE 'file_name'
    [IGNORE | REPLACE]
    INTO TABLE table_name
    [PARTITION (partition_name [, partition_name] ...)]
    [CHARACTER SET charset_name_or_default]
    [field_opt]
    [line_opt]
    [{IGNORE | GENERATED} number {LINES | ROWS}]
    [(column_name_var [, column_name_var] ...)]
    [SET load_set_list]
    [load_data_extended_option_list];

hint_options:
    [/*+ PARALLEL(N) [load_batch_size(M)] [APPEND | direct(bool, int)] */]

charset_name_or_default:
    `string_charset_name`
    | BINARY
    | DEFAULT

field_opt:
    {COLUMNS | FIELDS}
        [TERMINATED BY 'string']
        [[OPTIONALLY] ENCLOSED BY 'char']
        [ESCAPED BY 'char']

line_opt:
    LINES
        [STARTING BY 'string']
        [TERMINATED BY 'string']

load_set_list:
    load_set_element [, load_set_element ...]

load_set_element:
    column_definition_ref = {expr | DEFAULT}

load_data_extended_option_list:
    load_data_extended_option [load_data_extended_option ...]

load_data_extended_option:
    LOGFILE [=] string_value
    | REJECT LIMIT [=] int_num
    | BADFILE [=] string_value

```

## 参数说明

| 参数项 | 描述 |
| --- | --- |
| hint_options | 可选项，用于指定 Hint 选项。详细介绍可参见下文 [hint_options](#hint_options)。 |
| REMOTE_OSS | 可选项，表示从 OSS 文件系统中读取数据文件。若省略此选项，则默认从 OBServer 节点所在的服务器文件系统中读取数据文件。 |
| file_name | 用于指定输入文件的路径和文件名。 `file_name` 有以下格式：   - 导入文件在 OBServer 节点或客户端：`/$PATH/$FILENAME`。 - 导入文件在 OSS 上：`oss://$PATH/$FILENAME/?host=$HOST&access_id=$ACCESS_ID&access_key=$ACCESSKEY`。   参数解释如下：   - `$PATH`：指定了存储桶中的文件路径，表示文件所在的目录。 - `$FILENAME`：指定了文件的名称，表示要访问的具体文件。 - `$HOST`：指定了 OSS 服务的主机名或 CDN 加速的域名，即要访问的 OSS 服务的地址。 - `$ACCESS_ID`：指定了访问 OSS 服务所需的 Access Key ID，用于身份验证。 - `$ACCESSKEY`：指定了访问 OSS 服务所需的 Access Key Secret，用于身份验证。    #### 说明    在导入 OSS 上的文件时，需要确保以下信息：    - 确保访问 OSS 存储桶和文件的权限。你需要拥有足够的权限来读取指定的存储桶和文件。这通常需要在 OSS 控制台或通过 OSS API 设置访问权限，并将访问密钥（Access Key ID 和 Access Key Secret）配置为具有适当权限的凭据。 - 确保数据库服务器可以通过网络连接到指定的 `$HOST` 地址，以访问 OSS 服务。如果使用的是 OSS 服务的 CDN 加速域名，还需要确保 CDN 配置正确，并且网络连接正常。 |
| IGNORE \| REPLACE | 可选项，用于指定源数据与目标表数据唯一键冲突时的行为。`LOAD DATA` 通过表的主键来判断数据是否重复，如果表不存在主键，则 `REPLACE` 与 `IGNORE` 选项没有区别。若省略此选项，遇到重复数据的时候，`LOAD DATA` 会将出现错误的数据记录到日志文件中。具体选项说明如下：   - `IGNORE`：表示忽略冲突的行。 - `REPLACE`：表示替换已存在的数据，即覆盖冲突行。    #### 注意    使用 `REPLACE` 或者 `IGNORE` 子句的情况下，如果并行度大于 `1`，发生冲突的行最后插入的记录可能与串行执行的结果不同。如果需要严格保证冲突记录的插入结果，请不要指定该语句的并行度（或将并行度设置为 `1`）。 |
| table_name | 用于指定目标表的名称，即将数据导入到哪个表中。支持分区表与非分区表。 |
| PARTITION (partition_name [, partition_name ...]) | 可选项，如果目标表是分区表，可以使用 `PARTITION` 子句显式地选择将数据导入到目标表的哪些分区，多个分区使用英文逗号（`,`）分开。   #### 注意    `PARTITION` 子句仅语法支持，实际执行中不生效。 |
| CHARACTER SET charset_name_or_default | 可选项，用于指定导入文件的的字符集。详细介绍可参见下文 [charset_name_or_default](#charset_name_or_default)。 |
| field_opt | 可选项，用于指定字段选项，定义如何解释字段分隔符、文本限定符、字段转义字符等。详细介绍可参见下文 [field_opt](#field_opt)。 |
| line_opt | 可选项，用于指定如何处理行内容，包括行的起始字符和行的结束字符。详细介绍可参见下文 [line_opt](#line_opt)。 |
| {IGNORE \| GENERATED} number {LINES \| ROWS} | 可选项，用于指定数据文件内容的处理选项。`LINES` 和 `ROWS` 是同义词，它们都指代文件中的行，此选项具体意义和用法如下：   - `IGNORE number LINES`：表示跳过文件开始的指定数量（`number`）的行。 - `GENERATED number LINES` 的效果跟 `IGNORE number LINES`   相同。 |
| column_name_var | 可选项，用于指定目标表中的列名，即用于指定将数据文件中的列导入到目标表的哪些列中。若不提供此选项，则默认将输入文件中的字段依次对应至目标表的列上。如果输入文件中并没有包含目标表所有的列，那么缺少的列按照以下的规则会被默认填充：   - 字符类型：空字符串。 - 数值类型：0。 - 日期类型：`0000-00-00`。 |
| SET load_set_list | 可选项，用于在把数据导入目标表中之前设置或修改字段的值，即在导入时目标表时对数据进行转换或计算。`load_set_list` 是一个逗号分隔的列表，其中每一项 `load_set_element` 都指定了如何设置或转换一个特定的字段（列），详细介绍可参见下文 [load_set_element](#load_set_element)。 |
| load_data_extended_option_list | 可选项，用于指定列扩展选项，这些选项提供了进一步控制数据加载过程的方式。每个 `load_data_extended_option` 可以用来定义特定的行行为，详细介绍可参见下文 [load_data_extended_option](#load_data_extended_option)。 |

### hint_options

- `PARALLEL(N)`：指定加载数据的并行度，`N` 默认为 `4`。
 - `load_batch_size(M)`：指定每次插入的批量大小，`M` 默认为 `100`。推荐取值范围为 [100, 1000]。
 - `APPEND | direct(bool, int)`：使用 Hint 启用旁路导入功能。

     - `APPEND`：启用旁路导入功能，即支持直接在数据文件中分配空间并写入数据。`APPEND` Hint 默认等同于使用的 `direct(true, 0)`，同时可以实现在线收集统计信息（`GATHER_OPTIMIZER_STATISTICS` Hint）的功能。有关在线统计信息收集的信息，参见 [在线统计信息收集](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000221494)。
     - `direct(bool, int)`：启用旁路导入功能。参数解释如下：

           - `bool`：表示写入的数据是否需要排序，`true` 表示需要排序，`false` 表示不需要排序。
           - `int`：表示最大容忍的错误行数。

  更多使用 `LOAD DATA` 旁路导入的信息，参见 [使用 LOAD DATA 语句旁路导入数据/文件](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000218027)。

### charset_name_or_default

- `string_charset_name`：指定的字符集名称，通常是一个字符串值，例如 `gbk`、`latin1` 等。
 - `BINARY`：指定字符集为 `binary` 意味着不进行转换，即不进行字符集之间的转换。
 - `DEFAULT`：指定使用数据库默认的字符集来解释文件中的字符数据。OceanBase 数据库默认的字符集是 `utf8mb4`。

### field_opt

- `{COLUMNS | FIELDS}`：指定使用的关键字是 `COLUMNS` 还是 `FIELDS`，这两个关键字是同义词，表示数据文件中的列。
 - `TERMINATED BY 'string'`：指定数据文件中字段的分隔符，即设置导出列的结束符。当读取文件的每一行时，设置的结束符表示一个字段的结束和下一个字段的开始。
 - `[OPTIONALLY] ENCLOSED BY 'char'`：指定数据文件中字段的开头和结尾可以（可选地）被包围（引用）的字符，即设置导出值的修饰符。如果字段中包含了分隔符（例如逗号），那么这个字段常会被双引号包围。

     - `OPTIONALLY`：可选项，是一个修饰关键词，用于表示字段的包围字符是非强制的。在使用 `LOAD DATA` 命令时，这意味着某些字段可能有包围字符，而其他字段则没有。字段是否包围不影响命令的正常读取操作。
 - `ESCAPED BY 'char'`：指定数据文件中用于转义特殊字符的转义字符，即设置导出值忽略的字符。例如，如果字段值内部含有双引号字符，该字符就需要通过在前面加一个反斜杠来进行转义（例如 `"Hello \"world\""`）。

例如，使用 `FIELDS` 关键字配置 `LOAD DATA` 命令的字段处理方式，使用 `TERMINATED BY` 指定字段的分隔符是逗号（`,`），使用 `OPTIONALLY ENCLOSED BY` 指定字段值可以用双引号（`"`）包围，并使用 `ESCAPED BY` 指定反斜杠（`\`）作为转义字符，用于处理字段值中的特殊字符。

#### 注意

下面 SQL 语句是 `LOAD DATA` 命令中 `field_opt` 选项的一个示例，并非完整的 `LOAD DATA` 命令，所以这条 SQL 暂时还不能被运行。

```sql
...
FIELDS
    TERMINATED BY ','
    OPTIONALLY ENCLOSED BY '"'
    ESCAPED BY '\\'
...

```

### line_opt

- `LINES`: 关键字，告诉 `LOAD DATA` 命令以下的参数将应用于文件中的行。
 - `STARTING BY 'string'`：指定行起始符，即指定每一行数据的开始标识符。
 - `TERMINATED BY 'string'`：指定行结束符，即指定每一行的结束标识符。

例如，定义每一行数据的开始标记为特定的字符串 `***`，即每行中的 `***` 开头，将其作为数据行的起点。定义行的结束符为换行符（`\n`）。

#### 注意

下面 SQL 语句是 `LOAD DATA` 命令中 `line_opt` 选项的一个示例，并非完整的 `LOAD DATA` 命令，所以这条 SQL 暂时还不能被运行。

```sql
...
LINES
    STARTING BY '***'
    TERMINATED BY '\n'
...

```

### load_set_element

`column_definition_ref PARSER_SYNTAX_ERROR {expr | DEFAULT}`：表示单个的设置或转换操作。

- `column_definition_ref`: 指定目标表的列名，在导入过程中将对这一列进行设置或转换。
 - `PARSER_SYNTAX_ERROR`: 关键字，语法分析器错误。
 - `{expr | DEFAULT}`:

     - `expr`: 指定一个表达式，它定义了如何计算或转换该列的值。表达式可以用来操作数据文件中的原始值，例如，可以通过表达式将两个字段拼接在一起，或者对一个数字字段进行数学运算。
     - `DEFAULT`: 指定表中该列的值将被设置为默认值。这通常是列定义时指定的默认值。

例如，对于每条导入的数据，将现有的 `col_name1` 列的值设置为 `xxxx`，将 `col_name2` 列的值应该被设置为它的默认值。

#### 注意

下面 SQL 语句是 `LOAD DATA` 命令中 `load_set_element` 选项的一个示例，并非完整的 `LOAD DATA` 命令，所以这条 SQL 暂时还不能被运行。

```sql
...
SET col_name1 = 'xxxx', col_name2 = DEFAULT;
...

```

### load_data_extended_option

#### 注意

`load_data_extended_option` 选项仅语法支持，实际执行中不生效。

- `LOGFILE [=] string_value`：用来指定一个日志文件，其中会记录在数据加载过程中发生的特定事件或错误。`string_value` 是目标日志文件的路径和文件名。例如，`LOGFILE = 'load_data.log'` 会将日志信息记录到名为 `load_data.log` 的文件中。
 - `REJECT LIMIT [=] int_num`：用来设置在终止 `LOAD DATA` 操作之前允许的最大错误数量。`int_num` 是一个整数，代表如果在数据加载过程中遇到的错误数量超过这个限制，整个加载操作将失败。例如，`REJECT LIMIT = 10` 将在遇到超过 10 个错误后停止加载数据。
 - `BADFILE [=] string_value`：类似于 `LOGFILE` 参数，用来指定一个文件，该文件用来存放在加载数据过程中识别为无效或不能导入的数据行。`string_value` 是存放这些数据行的文件的路径和名字。例如，`BADFILE = 'bad_data.txt'` 将不良数据行放到 `bad_data.txt` 文件中。

## 示例

### 示例一：从服务器端（OBServer 节点）文件导入数据

1. 设置全局安全路径。

   #### 注意

   由于安全原因，设置系统变量 `secure_file_priv` 时，只能通过本地 Socket 连接数据库执行修改该全局变量的 SQL 语句。更多信息，请参见 [secure_file_priv](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000220800)。

   ```shell
   SET GLOBAL secure_file_priv = "/";

   ```
 2. 退出登录。

   #### 说明

   由于 `secure_file_priv` 是 `GLOBAL` 变量，所以需要执行 `\q` 退出使之生效。

   ```shell
   obclinet> \q

   ```
 3. 重连数据库后，使用 `LOAD DATA` 语句导入数据。

      - 普通导入。

       ```shell
       LOAD DATA
         INFILE '/home/admin/test.csv'
         INTO TABLE t1
         FIELDS
           TERMINATED BY ','
           ENCLOSED BY '"'
           LINES TERMINATED BY '\n';

       ```
      - 使用 `APPEND` Hint 启用旁路导入。

       ```shell
       LOAD DATA /*+ PARALLEL(4) APPEND */
         INFILE '/home/admin/test.csv'
         INTO TABLE t1
         FIELDS
           TERMINATED BY ','
           ENCLOSED BY '"'
           LINES TERMINATED BY '\n';

       ```

### 示例二：从 OSS 文件导入数据

#### 注意

使用对象存储路径时，对象存储路径的各项参数由 `&` 符号进行分隔，请确保您输入的参数值中仅包含英文字母大小写、数字、`\/-_$+=` 以及通配符。如果您输入了上述以外的其他字符，可能会导致设置失败。

使用 `direct(bool, int)` Hint 启用旁路导入功能，导入文件可在 OSS 上。

```shell
LOAD DATA /*+ direct(true,1024) parallel(16) */
  REMOTE_OSS INFILE 'oss://antsys-oceanbasebackup/backup_rd/xiaotao.ht/lineitem2.tbl?host=***.oss-cdn.***&access_id=***&access_key=***'
  INTO TABLE tbl1
  FIELDS
    TERMINATED BY ',';

```

## 相关文档

- 更多有关使用 `LOAD DATA` 语句的示例信息，请参见 [使用 LOAD DATA 语句导入数据](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000218017)。
 - 更多有关使用 `LOAD DATA` 旁路导入的示例信息，请参见 [使用 LOAD DATA 语句旁路导入数据](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000218027)。

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线