使用 obloader 导入数据

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

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

适用场景

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

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

命令行选项

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

操作示例

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

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，RPC 端口默认为 2885。 当 obloader 绕过 ODP 直接连接 OBServer，并显式指定 RPC 端口时，可以走旁路导入路径。

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

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

数据量达到 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 端口传输数据，并非 SQL 协议端口。

• 基于表粒度进行整体提交，并非会话级/事务级的提交操作。

• 暂不支持重试或者断点续传。

• 暂不支持 bit 类型数据。

• 暂不支持虚拟生成列。

• 对于数据量较小的导入任务，不建议使用旁路导入。

• 指定 --replace-data 命令行选项时，仍无法处理唯一索引冲突。

• 参数 --thread 命令行选项与 --parallel 命令行选项的区别：

  • --thread 表示客户端到服务端的连接池，由客户端维护。

  • --parallel 为 OBServer 可以调用的工作线程数，用于写入数据与排序。

  • 使用时，建议 --thread 与 --parallel 保持一致。