旁路导入介绍 | OceanBase 文档中心

旁路导入介绍

更新时间：2026-04-14 15:36:17

OceanBase 迁移服务（OceanBase Migrate Service，OMS）社区版进行数据迁移时，支持通过旁路导入的方式写入数据。本文为您介绍旁路导入的使用限制、相关参数，以及如何查询旁路导入任务状态等。

背景介绍

OceanBase 数据库支持以旁路导入的方式向数据库中插入数据。该功能可以绕过传统的 SQL 层接口，直接向数据库的文件写入数据，从而提高数据导入的效率。更多详情请参见旁路导入概述。

旁路导入不支持断点续传，因此迁移中断并恢复后，源端数据将重新读取，但上一次已经完成的表不会再次读取。

OMS 社区版中，下述类型的数据迁移任务在创建时支持选择通过旁路导入方式写入数据。

direct-load-zh

OMS 社区版为 V4.2.2-CE 及之后版本，且数据迁移的目标端为 OceanBase 社区版 V4.2.1-CE 及之后版本时，全量迁移才支持该方式。
通过旁路导入的方式写入数据时，目标端用户的 host 字段必须为 %。
单行数据不能超过 2MB。
源端为 OceanBase 社区版 V4.3.3-CE 时，暂不支持增量同步向量类型的增量数据。
暂不支持通过旁路导入的方式写入向量类型的数据。
暂不支持处理除主键（PK）外，其他唯一键（UK）约束导致的数据重复问题。
暂不支持生成列、Trigger 和 UDT（用户自定义类型）。
旁路导入空表比较合适，并且需要确保中途不中断，即不支持断点续传。因此，当全量迁移使用旁路导入方式中断后，即使任务运行恢复，源端的数据会重新开始读取。
如果导入表存在 LOB 字段，请关闭 OceanBase 社区版的 enable_rebalance 参数。关闭命令如下：
```
SHOW PARAMETERS LIKE 'enable_rebalance';
ALTER SYSTEM SET enable_rebalance = false;
```
旁路导入目前不支持并发，请确保目标库同一时间只有一张表在使用旁路导入方式写入数据。
源端表字段和目标端字段数一致，并且顺序一致。
包含前缀索引的表，不支持通过旁路导入方式写入。

下表为您介绍旁路导入相关参数，这些参数均在组件参数的 Sink 模块下。

参数	描述
dbVersion	数据库的版本。仅 OceanBase 社区版的版本大于 V4.2.1 时，才支持旁路导入。未设置该参数的情况下，自动从数据库中查询：`SHOW VARIABLES LIKE 'version_comment'`。
host	RPC 地址。默认自动从数据库中查询：`SHOW PARAMETERS LIKE 'rpc_port'`，获取第一个 `svr_ip`。
port	RPC 端口。默认自动从数据库中查询：`SHOW PARAMETERS LIKE 'rpc_port'`，获取第一个 `svr_port`。
username	复用原 sink 中的 username 配置，格式为 `用户@租户#集群名`。旁路导入从此处解析用户和租户，用于 `tableApi`。
password	复用原 sink 中的 password 配置。
serverParallel	旁路导入 Server 端的并发，默认值为 8。
maxErrors	最大允许错误记录数，默认值为 0。
replaceData	PK 重复时，是否使用 `replace` 方式覆盖。默认值为 `true`，`flase` 表示忽略（ignore）。
serverTimeout	服务端旁路导入任务超时。单位为 us，默认值为 `1209600L * 1000 * 1000`（14 天）。
rpcExecuteTimeout	RPC 执行超时。单位为 ms，默认值为 600000（10 分钟）。

在 SYS 租户中查询旁路导入系统表

SELECT * FROM oceanbase.__all_virtual_load_data_stat;