【starrocks】StarRocks 常见 HTTP 操作与导入错误排查指南

StarRocks 是一款面向分析型场景的高性能 MPP 数据库，提供了丰富的 HTTP 接口，广泛用于数据导入、系统状态查询和任务管理。本文将系统梳理 StarRocks 常用的 HTTP 操作命令，并介绍如何排查数据导入过程中的常见错误。

---

一、Stream Load：通过 HTTP 导入数据

Stream Load 是 StarRocks 最常用的数据导入方式之一，适合小批量、实时的数据写入。

示例命令：CSV 文件导入

curl -u user:password \
  -H "label: test_load_001" \
  -H "column_separator:," \
  -T ./data.csv \
  http://fe_host:8030/api/db_name/table_name/_stream_load

参数说明：

• user:password：StarRocks 用户名与密码
• label：导入任务的唯一标识符，建议每次都设置
• column_separator：列分隔符（默认是 TAB）
• -T：要上传的文件路径
• URL 格式：http://FE_HOST:8030/api/{db}/{table}/_stream_load

支持的其他参数：

• format: json：支持 JSON 格式导入
• strip_outer_array: true：JSON 数组展开导入
• Content-Encoding: gzip：支持压缩导入（如 .gz 文件）

---

二、导入状态查询

导入任务完成后，可以使用 label 查询其状态：

curl -u user:password \
  "http://fe_host:8030/api/db_name/_load?label=test_load_001"

返回内容将包含任务状态（成功、失败）、错误摘要及错误日志链接。

---

三、取消导入任务

如果某个导入任务未完成或卡住，可以通过以下命令取消：

curl -X DELETE -u user:password \
  "http://fe_host:8030/api/db_name/_load?label=test_load_001"

---

四、节点状态监控

查看所有 Backend 状态：

curl http://fe_host:8040/api/show_backends

查看所有 Frontend 状态：

curl http://fe_host:8030/api/show_frontends

---

五、导入失败的排查方式

如果导入失败，可以通过以下步骤排查问题。

1. 查询导入任务状态

curl -u user:password \
  "http://fe_host:8030/api/db_name/_load?label=test_label"

关注返回结果中的：

• status: 是否为 fail
• msg: 错误摘要
• errorURL: 下载详细错误日志链接

2. 下载详细错误日志

curl -O "http://be_host:8040/api/_load_error_log?file=be_err_log_xxx.log"

日志内容可能包括字段类型不匹配、NULL 错误等。

3. 查看 FE/BE 节点日志

FE 日志路径：

${STARROCKS_HOME}/fe/log/

• load.log：导入相关日志
• fe.log：通用日志，可搜 stream load

BE 日志路径：

${STARROCKS_HOME}/be/log/

• be.log：详细错误处理信息

grep 示例：

grep "test_label" ${STARROCKS_HOME}/fe/log/load.log

---

六、常见错误类型与建议处理方式

错误类型	原因	处理建议
Data type mismatch	数据格式与表字段不匹配	检查字段类型、NULL 值、分隔符
unexpected null	非空字段出现 NULL	检查字段是否缺失或多余分隔符
Label already exists	重复使用 label	更换 label，或使用 UUID 动态生成
File too large	单个文件过大	拆分文件、提升导入参数限制
Timeout	网络或导入超时	检查网络和 FE/BE 负载