---
title: "使用 obloader 导入数据 - OceanBase 数据库 V4.6.0 | OceanBase 文档中心"
description: 使用 obloader 导入数据 数据文件所在环境无法被 OBServer 直接访问，即与 Observer 网络不通、或不便把文件拷贝到 OBServer 本地路径时，可以使用 obloader 将数据写入 OceanBase。 与在 OBServer 侧通过 SQL 执行 LOAD DATA 、 LOAD DAT…
---
切换语言

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

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

# 使用 obloader 导入数据

更新时间：2026-06-18 10:13:19

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.6.0/zh-CN/620.obap/300.obap-data-transfer/300.data-import/500.import-data-with-obloader.md)  

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

与在 OBServer 侧通过 SQL 执行 [`LOAD DATA`](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006277725)、[`LOAD DATA FROM FILES`](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006277725) 等不同，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](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006277725)、[LOAD DATA INFILE](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006277725) 及 [数据导入概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006277724) 中的路径选型。

## 命令行选项

以 [导数工具文档](https://www.oceanbase.com/docs/oceanbase-dumper-loader) 与实际环境配置为准。

| 命令行选项 | 说明 | 云数据库 OceanBase & ODP | OceanBase 数据库 & ODP | OceanBase 数据库 & OBServer |
| --- | --- | --- | --- | --- |
| --direct | 标识使用旁路导入。 | 必选 | 必选 | 必选 |
| --parallel | 服务端并发度。默认值 1，建议与租户 CPU 规格一致。   **建议指定该选项以保证性能稳定。** | 非必选 | 非必选 | 非必选 |
| --rpc-port | 服务端 inner rpc port。获取方式：   - 连接 ODP 服务端时：      - 云数据库 OceanBase 环境下，ODP RPC Port 默认 3307。     - OceanBase 数据库环境下，默认端口 2885；如果需要自定义，可以在启动 ODP 时通过 `-s` 选项进行指定。 - 连接 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 互斥 | 非必选   与 --no-sys 互斥 | 非必选   与 --no-sys 互斥 |
| --sys-password | 用于标识依赖 sys 租户的密码。仅用于 OceanBase 数据库 V4.0.0 之前的版本。 | 非必选   与 --no-sys 互斥 | 非必选   与 --no-sys 互斥 | 非必选   与 --no-sys 互斥 |

## 操作示例

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

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

```

旁路导入访问的是 RPC 端口，而非 SQL 端口。默认情况下，OBServer 的 SQL 端口为 2881，RPC 端口为 2882；对于 ODP V4.3.0，RPC 端口默认为 2885。 当 obloader 绕过 ODP 直接连接 OBServer，并显式指定 RPC 端口时，可以走旁路导入路径。

需要注意的是，生产环境通常不建议客户端绕过 ODP 直连 OBServer。通过 ODP 访问时，数据主副本的位置对客户端透明，路由由 ODP 统一处理；而直连某个 OBServer 时，如果目标数据的主副本不在当前节点，写入过程可能涉及跨节点事务协调，增加网络与事务开销。

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

数据量达到 TB 级时，旁路导入更有利于吞吐；可结合租户资源与 [数据导入概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006277724)、[全量旁路导入](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006277724) 中的注意项（表锁、合并等）规划窗口。

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

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

```JSON
"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` 保持一致。

 上一篇 下一篇 ![有帮助](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) 咨询热线