使用 obloader 导入数据

更新时间：2026-06-30 19:47:42

编辑

数据文件所在环境无法被 OBServer 直接访问，即与 Observer 网络不通、或不便把文件拷贝到 OBServer 本地路径时，可以使用 obloader 将数据写入 OceanBase。

与在 OBServer 侧通过 SQL 执行 LOAD DATA、LOAD DATA FROM FILES 等不同，obloader 在客户端进程内读文件，经 RPC 与存储层交互，适合离线包、跨网段交付等场景。

注意

obloader 旁路导入支持连接 OBServer 或 ODP。版本要求：

连接 OBServer：OBServer 为 V4.2.0 及以上。
连接 ODP：ODP 为 V4.3.0 及以上，且 OBServer 为 V4.2.1 及以上。

具体以当前使用的导数工具发行说明为准。

适用场景

文件与 OBServer 不通：导出文件在业务机、跳板机或隔离网段，OBServer 与数据文件地址网络不通，不便使用由 OBServer 直接读取文件的导入方式。

若文件已放在 OBServer 可访问路径或对象存储，可优先评估 LOAD DATA FROM FILES、LOAD DATA INFILE 及数据导入概述中的路径选型。

命令行选项

以导数工具文档与实际环境配置为准。

命令行选项	说明	OceanBase 数据库 & OBServer
--direct	标识使用旁路导入。	必选
--parallel	服务端并发度。默认值 1，建议与租户 CPU 规格一致。建议指定该选项以保证性能稳定。	非必选
--rpc-port	服务端 inner rpc port。获取方式：连接 OBServer 服务端时，sys 租户下查询系统视图 DBA_OB_SERVERS 即可获取 OBServer 的 RPC 端口，默认端口 2882。	必选
-u(--user)	数据库用户名。	必选
-P(--port)	SQL 端口号。	必选
-t(--tenant)	集群的租户名。	必选
-c(--cluster)	数据库的集群名。	-
--public-cloud	指定云数据库 OceanBase 运行环境。	-
--no-sys	用于标识不依赖 sys 租户。仅用于 OceanBase 数据库 V4.0.0 之前的版本。	非必选
--sys-user	用于标识依赖 sys 租户的 user。若不填，默认为 root。仅用于 OceanBase 数据库 V4.0.0 之前的版本。	非必选与 --no-sys 互斥
--sys-password	用于标识依赖 sys 租户的密码。仅用于 OceanBase 数据库 V4.0.0 之前的版本。	非必选与 --no-sys 互斥

操作示例

在存放 CSV 的机器上执行（示例为 Oracle 模式租户；请替换为实际地址、端口、用户与路径）：

bin/obloader -h <ODP或OBServer地址> -P 2881 -u <用户> -t <租户名> -c <集群名> -p \
  -D <库名> --table LINEITEM --external-data --csv \
  -f /data/tpch/bak/ \
  --truncate-table --column-separator='|' \
  --thread 16 --rpc-port 2882 --direct --parallel=16

旁路导入访问的是 RPC 端口，而非 SQL 端口。默认情况下，OBServer 的 SQL 端口为 2881，RPC 端口为 2882。

-f 指向本机可读的数据目录；工具在客户端读文件，经 RPC 旁路写入，不要求 OBServer 能访问该路径。
--rpc-port 须与当前连接目标（ OBServer）的 RPC 监听一致，勿与 SQL 端口混淆。
若直连某台 OBServer，需了解数据主副本是否与该节点一致；跨机旁路可能带来额外代价。具体路由与网络策略以运维规范为准。

数据量达到 TB 级时，旁路导入更有利于吞吐；可结合租户资源与数据导入概述、全量旁路导入中的注意项（表锁、合并等）规划窗口。

旁路模式配置文件（可选）

可在 {ob-loader-dumper}/conf/session.config.json 中配置 direct_path_load 段，用于 RPC 超时、重试、任务超时等，例如：

"direct_path_load": {
    "rpc_connect_timeout": "15000",
    "rpc_execute_timeout": "20000",
    "runtime_retry_times": "5",
    "runtime_retry_intervals": "50",
    "task_timeout": "2592000000000",
    "heartbeat_timeout": "60000000"
}

字段	含义
`rpc_connect_timeout`	RPC 连接超时（毫秒）。
`rpc_execute_timeout`	RPC 执行超时（毫秒）。
`runtime_retry_times`	运行失败时的最大重试次数。如果因为某些原因操作失败，将会根据该参数进行重试。
`runtime_retry_intervals`	重试间隔（毫秒）。在重试操作前等待的时间长度。
`task_timeout`	任务超时（微秒）；0 表示不限制。如果在配置的时限内未完成操作，则被视为超时。
`heartbeat_timeout`	心跳超时（微秒），用于检测导入操作的活跃状态。0 表示不启用。

注意事项

旁路写入需要使用 RPC 端口传输数据，并非 SQL 协议端口。
基于表粒度进行整体提交，并非会话级/事务级的提交操作。
暂不支持重试或者断点续传。
暂不支持 bit 类型数据。
暂不支持虚拟生成列。
对于数据量较小的导入任务，不建议使用旁路导入。
指定 --replace-data 命令行选项时，仍无法处理唯一索引冲突。
参数 --thread 命令行选项与 --parallel 命令行选项的区别：
- --thread 表示客户端到服务端的连接池，由客户端维护。
- --parallel 为 OBServer 可以调用的工作线程数，用于写入数据与排序。
- 使用时，建议 --thread 与 --parallel 保持一致。