Apache Doris Stream Load RESTful 接口实操指南

Apache Doris Stream Load RESTful 接口实操指南

【免费下载链接】dorisApache Doris is a real-time analytics and hybrid search database for AI agents.项目地址: https://gitcode.com/GitHub_Trending/doris/doris

深夜告警炸了：两百 MB 的 CSV 要灌进业务库，用 MySQL 协议一行一行 INSERT 还没跑完，连接池先耗尽了。这类批量灌数场景就是 Apache Doris Stream Load 干的事儿：它是把整个文件通过一次 HTTP 请求灌进去的 RESTful 接口，下面按动手顺序过一遍。

先选对接口：什么时候用 HTTP

Stream Load 适合数据已经整理成 CSV 或 JSON、需要一次性推送几 MB 到几 GB 的场景。偶发的单条插入用 MySQL 协议更直接，不必硬套。本文只讲批量灌数这条链路。

Stream Load 请求三要素

一个完整请求就三块，缺一个都跑不通。

• URL：http://<fe_host>:8030/api/<database>/<table>/_stream_load，FE 的 HTTP 端口默认 8030
• 方法：PUT，数据直接放在请求体里
• Header：声明数据格式和认证信息

Header 里高频的就四个参数，记住够用：

• format：数据格式，csv或json
• column_separator：字段分隔符，比如,
• column：指定导入列的顺序，比如id,name
• label：导入任务标识，可选，不填由服务端生成

最小可运行的 Python 示例：

import requests from requests.auth import HTTPBasicAuth url = 'http://127.0.0.1:8030/api/db0/t_user/_stream_load' headers = { 'Content-Type': 'text/plain; charset=UTF-8', 'format': 'csv', 'column_separator': ',', } data = '1,Tom\n2,Jelly' resp = requests.put(url, headers=headers, data=data, auth=HTTPBasicAuth('root', '')) print(resp.status_code, resp.text)

完整版在 samples/stream_load/python/DorisStreamLoad.py，里面还处理了大文件需要的Expect: 100-continue。

读响应：成功看哪、失败看哪

请求返回后，先看Status字段。

• Status为Success且NumberLoadedRows符合预期，导入完成
• NumberFilteredRows大于 0，说明有行解析或校验没通过，跟着响应里的errorURL能定位到具体是哪几行、为什么错
• Message是给人看的失败原因，Label是本次导入的唯一标识

注意：失败时 HTTP 状态码也可能还是 200，判定逻辑别只写 HTTP code。

Go 还是 Java 还是 Rust SDK：怎么选

按技术栈选，没有标准答案。JVM 技术栈直接参考 Java 示例，面向对象的写法方便在内部服务里包一层连接池和重试；云原生服务用 Go 示例 更顺，goroutine 加 context 管理请求，它同时演示了用column做派生列计算和 JSON 导入；要写高吞吐的独立采集工具，Rust 示例 基于 reqwest 异步客户端，样板代码最少。不想写代码也行，Kettle 里就有 Doris Stream loader 步骤，配上 FE 地址、库表和参数后发的是同一套请求：

Stream Load 排错清单

高频问题四个，按"症状 → 动作"查：

• 401 认证失败→ 核对用户名密码，再检查 conf/fe.conf 里 HTTP 认证相关的开关
• 连接超时→ 客户端执行telnet <fe_host> 8030验证端口通不通，不通查防火墙和安全组
• 列数对不上、FilteredRows 高→ 用column参数对齐字段顺序与表结构，再跟errorURL看失败明细
• 提示 label 重复→ 同名 label 的任务还在跑或已结束，换一个 label，或等前一个任务收尾

进阶钩子：label 幂等与 TxnId 📌

label自己指定后就是导入的幂等键，同 label 重发不会重复导入，断点续传就靠它；响应里的TxnId是导入事务 ID，拿它可以在服务端跟踪这次导入的进度与状态。更多语言的现成实现都放在 samples/stream_load 目录，对照着改参数就能跑。

【免费下载链接】dorisApache Doris is a real-time analytics and hybrid search database for AI agents.项目地址: https://gitcode.com/GitHub_Trending/doris/doris