首批通过分布式安全可靠测评，为关键业务系统打造
数据导入概述
更新时间：2026-06-30 19:47:42
编辑
分享
数据导入是指将外部数据写入 OceanBase 内表的过程。数据可能位于本地路径、对象存储、HDFS 等外部存储，也可能来自其他数据库。
选择导入方案时，建议优先按导入方式判断（由谁读文件、以何种 SQL/工具写入），再确认数据所在位置与网络是否可达。
OceanBase 数据库导数方案架构如下所示：
导入方式
将文件或可读外部路径上的数据写入内表时，多数场景可先在以下三类方式中取舍；它们对应不同的执行入口，而非按“数据源类型”分类。
| 导入方式 | 数据位置 | 适用场景 | 更多阅读 |
|---|---|---|---|
| LOAD DATA FROM FILES | 服务端可读的对象存储 URL、外部文件路径等 | 适合大规模文件导入、多文件并行装载，以及无需先将文件复制到 OBServer 本地盘的场景。 | LOAD DATA FROM FILES |
| LOAD DATA INFILE | OBServer 进程可访问的服务器侧路径 | 适合文件已在节点本地或共享挂载中的场景。 | LOAD DATA INFILE |
| LOAD DATA LOCAL INFILE | 客户端本地文件 | 适合中小批量、测试验证，或文件仅保存在客户端本机的场景。 | LOAD DATA LOCAL INFILE |
| INSERT INTO ... SELECT FROM FILES | 查询侧可读取的外部文件 | 适合需要在 SQL 中完成列映射、过滤、表达式计算等转换的场景。 | INSERT INTO SELECT FROM FILES |
| INSERT INTO ... SELECT（内表 / 外表） | 内表、外表或其他查询结果 | 适合分析结果回灌、内外表数据倒换等场景。 | 通过外表 INSERT INTO SELECT 导入 |
| CREATE TABLE AS SELECT（CTAS） | 由 SELECT 定义新表并装载数据 |
适合建表与装载同时完成的场景。 | 使用 CREATE TABLE AS SELECT 导入 |
| 工具辅助导入 | 客户端、中转机或隔离网络侧持有文件 | 适合网络受限、导入链路需要独立工具协议或批量导入任务编排的场景。 | 使用 obloader 导入数据 |
什么是旁路导入
OceanBase 支持在部分导入语句上启用旁路导入，以缩短常规写入链路，降低 SQL 层和 MemTable 的热写压力，从而提升大规模装载吞吐。
OceanBase 数据库通过旁路导入技术，跳过中间步骤，直接将数据写入 SSTable，同时减少资源消耗（CPU、内存），并且支持高效全量或增量数据导入。
注意
不建议在执行旁路导入任务过程中执行升级，可能导致旁路导入任务失败。
技术架构
传统导入路径（蓝色路径）：
客户端 -> SQL 解析 -> 事务处理 -> 内存表（MemTable） -> 转储 -> Minor/Major 合并 -> SSTable
缺点：路径长，资源消耗高，写入速度受限。
旁路导入路径（绿色路径）：
客户端 -> 类型转换 -> 主键排序（可选） -> 直接写入 Major SSTable（全量）或 Mini SSTable（增量）
优势：
- 跳过 SQL、事务、MemTable 等中间模块，减少资源消耗。
- 数据直接写入底层存储，避免多次合并开销。
旁路导入的核心机制
跳过中间层：绕过 SQL 解析、事务、MemTable，直接写入 SSTable。
类型转换与排序：
- 数据类型转换（如 CSV 到 OceanBase 表结构）。
- 按主键排序（全量导入时必需，保证 Major SSTable 的有序性）。
从概念上看，旁路导入是一种导入执行模式，而不是一种独立的数据来源或单独的语法类别。
也就是说，用户通常不是先选择“旁路导入”，再去选择语法；而是先根据业务需求选择 LOAD DATA、INSERT INTO SELECT、CREATE TABLE AS SELECT 或 obloader 等导入方式，再判断这些路径在当前条件下是否适合走旁路执行。
在启用 APPEND、DIRECT(...) 等 Hint，或依赖租户级配置项 default_load_mode 时，优化器和执行引擎会根据语句类型、执行计划、并行能力以及对象约束等条件，判断是否可以采用旁路导入模式。
适用场景
数据迁移与同步。对于数据迁移和同步，通常需要将大量的各种格式的数据从不同的数据源向 OceanBase 数据库进行迁移，传统的 SQL 接口性能可能在时效性上无法得到满足。
传统 ETL。当数据在源端进行了抽取和转化之后，在装载到目标端时，通常需要在短时间内加载大量的数据，使用旁路导入技术，会提升数据导入的性能。而对于 ETL 技术，在装载数据的过程中，也可以通过旁路导入技术提高效率。
从文本文件或者其他数据源向 OceanBase 数据库加载数据，利用旁路导入技术，也能够提升加载数据效率。
旁路导入与导入语法的关系
理解旁路导入时，最容易混淆的一点是：它与 LOAD DATA、INSERT INTO SELECT、CTAS 等语法不是并列关系，而是执行模式与承载语法之间的关系。
可以将其理解为：
LOAD DATA、INSERT INTO SELECT、CREATE TABLE AS SELECT等语句定义了“如何读取数据并写入目标表”；- 旁路导入定义的是“这些语句在满足条件时，是否采用更高效的写入方式”。
因此，同一条导入语句在不同条件下，可能有不同的执行方式：
- 语句在不同 OceanBase 版本中，可能会根据版本行为差异采用常规插入方式执行。
- 在满足 Hint、配置项、并行能力和对象限制等前提下，语句也可能走旁路导入路径。
例如：
LOAD DATA更适合文件导入场景，是否走旁路取决于具体 Hint、模式和执行条件。INSERT INTO ... SELECT ...能否走旁路，往往还依赖并行 DML（PDML）等前提，详见 并行 DML；CREATE TABLE AS SELECT在建表同时装载数据时，也可以在满足条件的情况下配合旁路执行。
支持旁路导入的典型语句
下表展示了常见导入语句与旁路导入之间的关系。
| 语句类型 | 与旁路导入的关系 |
|---|---|
LOAD DATA |
在 FROM FILES 形态下，可结合 APPEND、DIRECT(...)、parallel(N) 等方式使用。 |
INSERT INTO ... SELECT ... |
可在满足并行 DML 等条件时走旁路导入路径，通常需要结合 enable_parallel_dml、parallel(N)、DIRECT(...) 等使用。 |
CREATE TABLE AS SELECT |
在建表同时装载数据的场景下，可结合 APPEND、DIRECT(...)、parallel(N) 等方式评估旁路能力。 |
| 工具导入（如 obloader） | 是否采用等价于旁路导入的装载路径，取决于工具版本、参数配置及工具内部实现。 |
全量旁路导入与增量旁路导入
旁路导入通常可分为全量旁路导入和增量旁路导入两类。
全量旁路导入
- 全量旁路导入用于将完整的数据集一次性直接写入到数据库的数据文件中。该方法能够绕过 SQL 层的接口，在数据文件中直接分配空间并插入数据，从而提高数据导入的效率。
- 全量旁路导入通常用于初始化数据库、数据迁移或在需要快速载入大量数据时使用。
增量旁路导入
- 增量旁路导入用于在已有大量数据的情况下，直接将新增的数据写入数据库的数据文件，无需通过 SQL 接口。该方法能够绕过 SQL 层的数据处理过程，直接将新增数据写入数据文件，从而提高数据的写入效率。
- 增量旁路导入通常用于高吞吐量的数据写入场景，例如大规模的实时数据采集、日志写入等场景。
为了理解两者差异，可以结合 OceanBase LSM-Tree 存储层来观察写入路径。OceanBase 的存储层主要包括：
- MemTable：内存中的写入结构，支持高并发更新。
- Mini SSTable：由 MemTable 转储形成的磁盘结构。
- Major SSTable：经合并后形成的稳定数据文件，适合高效查询。
在常规导入中，数据通常需要经过更完整的事务写入和转储链路；而在旁路导入中，执行引擎会尽量缩短这条路径，以提升大规模装载效率。全量旁路和增量旁路的区别，主要体现在写入目标形态、冲突处理方式以及适用场景上。
全量导入示意图：
增量导入示意图（只展示不冲突的数据）：
| 维度 | 全量旁路导入 | 增量旁路导入 |
|---|---|---|
| 触发场景 | 初始化装载、全量覆盖或构建基线。 | 批量追加、部分更新或在已有数据上继续装载。 |
| 导入过程 | 数据完成必要转换后写入基线方向，适合完整批次装载。 | 数据完成必要转换后，需结合已有数据与冲突情况处理写入路径。 |
| 写入位置 | 侧重写入 Major SSTable 方向。 | 无冲突数据与冲突数据的写入路径可能不同。 |
| 性能特征 | 吞吐高，适合大批量整体装载。 | 更依赖数据分布和冲突比例；冲突较多时性能会下降。 |
| 锁机制 | 对指定表或分区加锁。 | 对指定表或分区加锁。 |
| 查询性能 | 装载后查询性能较优。 | 无冲突数据查询性能较优；存在冲突时需结合后续写入路径评估。 |
注意事项
全量旁路导入注意事项
在使用全量旁路导入时，须注意以下旁路导入能力层面的限制与说明：
OceanBase 数据库从 V4.3.0 版本开始支持 LOB 数据类型的旁路导入。
旁路导入期间会加表锁，表无法被写入其他数据，整个过程中表是只读的。
全量旁路导入适用于大表首次导入、10 GB~TB 级别的数据迁移以及 CPU 和内存都不是特别充裕的场景，因为旁路导入的执行路径短，可以省 CPU 开销。
在导入过程中无法同时执行两个写操作语句（即不能同时写一个表），因为导入过程中会先加表锁，并且整个导入过程中只能进行读操作。
不支持在触发器（Trigger）使用。
不支持含有生成列的表（某些索引会产生隐藏生成列，例如 KEY idx_c2 (c2(16)) GLOBAL）。
不支持 Liboblog 和闪回查询（Flashback Query）。
在
LOAD DATA语句和INSERT INTO SELECT语句中使用指定分区旁路导入时需要注意，目标表不能是复制表，且不能含有自增列、标识列、Global Index。对于 V4.3.5 版本，从 V4.3.5 BP1 版本开始全量旁路导入有以下变更：
- 如果目标表最后一级分区为 Hash/Key 分区，支持分区级旁路导入。
- 当 Session 级变量 foreign_key_checks 取值为 False 时，旁路导入操作不会进行外键约束校验。
各导入语句自身的使用限制（与上表所述旁路能力限制不同），请分别参见：
- 使用
LOAD DATA执行旁路导入时，语法及语句级使用限制请参见 LOAD DATA 语法（MySQL 模式）。 - 使用
INSERT INTO SELECT执行旁路导入时，语法及语句级使用限制请参见 INSERT 语法（MySQL 模式）。
增量旁路导入注意事项
OceanBase 数据库在 V4.6.0 版本对增量旁路导入进行了优化。新的增量旁路导入策略把数据分成两部分，和已有数据主键冲突的部分写入 Mini SSTable（增量 SSTable），不冲突的部分写到另外一份 Major SSTable（基线 SSTable）中。这样对于冲突数据少的情况，新的增量旁路导入策略可以做到多次导入，查询性能也不会差。
在使用增量旁路导入时，除上文全量旁路导入中的通用限制外，还须注意以下增量旁路导入能力层面的限制：
- 有外键的表不支持增量旁路导入。
- 有
GLOBAL索引的表不支持增量旁路导入。 - 有约束的表不支持增量旁路导入。
- 多于一个
LOCAL唯一索引的无主键表不支持增量旁路导入。 - 有唯一索引的有主键表不支持增量旁路导入。
使用 LOAD DATA 或 INSERT INTO SELECT 执行增量旁路导入时，语句级使用限制请分别参见 LOAD DATA 语法（MySQL 模式） 与 INSERT 语法（MySQL 模式）。
注意事项
在使用旁路导入时，有以下通用注意事项（适用于全量与增量）：
增量旁路导入的数据会触发转储，对于数据量较小且能在分钟内完成导入的情况，不建议使用增量旁路导入。
增量旁路导入支持目标表有非唯一局部索引。
对于 V4.3.5 版本，从 V4.3.5 BP1 版本开始增量旁路导入有以下变更：
- 如果目标表最后一级分区为 Hash/Key 分区，支持分区级旁路导入。
- 仅支持堆表加一个局部唯一索引的场景，如果目标表存在多个局部唯一索引或全局唯一索引，导入操作将失败。
LOAD DATA/INSERT INTO SELECT语句中，存在多个导入任务有重合分区时，不支持分区并行导入；无重合分区时，支持分区并行导入。- 当 Session 级变量 foreign_key_checks 取值为 False 时，旁路导入操作不会进行外键约束校验。
说明
本节描述的是旁路导入能力的通用注意事项。若需了解某条具体 SQL 的使用限制，请参见对应语法文档：LOAD DATA 语法、INSERT 语法。
相关文档
- 数据传输概述
- 数据迁移概述
- LOAD DATA FROM FILES
- LOAD DATA INFILE
- LOAD DATA LOCAL INFILE
- INSERT INTO SELECT FROM FILES
- 通过外表 INSERT INTO SELECT 导入
- 使用 CREATE TABLE AS SELECT 导入
- 使用 obloader 导入数据
完整 SQL 语句参考文档：
