---
title: "使用 OBLOADER 旁路导入数据 - OceanBase 数据库 V4.4.0 | OceanBase 文档中心"
description: 使用 OBLOADER 旁路导入数据 本文介绍如何使用 OBLOADER 旁路导入数据。OBLOADER 旁路导入模式的相关命令行选项如下： 注意 OBLOADER 旁路导入模式支持连接 OBServer 和 ODP。对应的版本要求： 连接 OBServer 时：要求 OBServer 必须为 V4.2.0 及之后版…
---
切换语言

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

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

# 使用 OBLOADER 旁路导入数据

更新时间：2026-01-23 16:41:04

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.4.0/zh-CN/620.obap/300.obap-data-collection/300.obap-import-data/20.bypass-import/400.obloader-bypass-import.md)  

本文介绍如何使用 OBLOADER 旁路导入数据。OBLOADER 旁路导入模式的相关命令行选项如下：

#### 注意

OBLOADER 旁路导入模式支持连接 OBServer 和 ODP。对应的版本要求：

- 连接 OBServer 时：要求 OBServer 必须为 V4.2.0 及之后版本。
 - 连接 ODP 时：要求 ODP V4.3.0 及之后版本，且 OBServer 必须为 V4.2.1 及之后版本。

| 命令行选项 | 说明 | 云数据库 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 互斥 |

## 导入示例

使用以下命令，将数据导入至 OceanBase 数据库：

```shell
bin/obloader -h xx.x.x.xx -P 2883 -u TPCH -t oboracle -c OB4216 -p -D TPCH --table LINEITEM --external-data --csv -f /data/1/tpch/s4/bak/   --truncate-table --column-separator='|' --thread 16 --rpc-port=2885 --direct --parallel=16

```

旁路导入不是连接 OBServer 的 SQL 端口（默认 2881）而是连接 RPC 端口（默认 2882）。OBLOADER 如果绕过 ODP 而直连 OBServer，通过额外指定 RPC 端口即可实现旁路导入。ODP V4.3.0 的 RPC 端口是 2885。但是生产中不推荐客户端绕过 ODP。因为原本业务数据的主副本位置对应用客户端是透明的（客户端不需要知道数据在哪个 OBServer 节点上，ODP 会负责 SQL 路由）。直连 OBServer 旁路写入数据，如果主副本不在这个节点，将产生跨机事务。

以上命令将 `/data/1/tpch/s4/bak/` 目录下所有已支持的 CSV 数据文件导入到表 `LINEITEM` 中。如果您的数据文件大小为 TB 以上，请使用旁路导入提高效率。配合更大的租户资源规格，效率将更高。

## 旁路导入模式相关参数

您可以在 `{ob-loader-dumper}/conf` 目录下的 `session.config.json` 文件中配置旁路导入参数。

示例：

```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) 咨询热线