【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

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