StarRocks query_dump 接口完整抓取 SQL 执行上下文用于问题排查【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks当你在 StarRocks 中执行 SQL 遇到Unknown Error、异常报错或执行计划不符合预期分区裁剪未生效、Join 顺序不合理时仅凭一条报错信息往往无法定位根因。StarRocks 在 FE 的 HTTP 服务上提供了query_dump接口它会在 FE 侧重新走一遍查询的解析、分析与优化流程把规划器所依赖的 SQL 语句、建表语句、会话变量、统计信息、执行计划成本信息和异常堆栈一次性打包为 JSON 返回。读完本文你将掌握该接口的调用语法与参数含义、脱敏desensitize机制的原理并能结合 FE 源码理解 dump 数据是如何在查询链路中被采集、序列化的以及如何利用 dump 文件在离线测试环境中回放复现问题。适用场景根据官方 FAQ 文档 Dump_query.md 的说明遇到以下情况时适合使用query_dump抓取上下文并提交给 StarRocks 技术支持排查执行 SQL 查询或EXPLAIN时返回Unknown Error执行 SQL 查询时返回错误信息或异常查询执行效率不符合预期或执行计划存在可优化空间例如分区裁剪没有生效、Join 顺序可以调整。其核心价值在于技术支持拿到的不只是一句报错而是 FE 规划该查询时所看到的全部输入——表元数据、行数、列统计、会话变量乃至 BE 的硬件规格——从而可以在离线环境中精确复现同一份执行计划。query_dump 返回的信息query_dump接口返回 FE 执行 SQL 时依赖的信息包括字段含义源码佐证statement原始查询语句QueryDumpSerializer.java#L114 写入table_meta涉及的每张表的完整CREATE TABLE语句密码等敏感配置会被隐藏同上L126-L131 通过AstToStringBuilder.getDdlStmt生成table_row_count表/分区的行数用于规划器估算基数QueryDumpSerializer.java#L199-L207column_statistics列统计信息Min/Max、NDV 等带ESTIMATE标记同上L222-L232explain_info带成本的EXPLAIN文本TExplainLevel.COSTSStmtExecutor.java#L896 在生成执行计划后写入session_variables会话变量全量 JSON 快照QueryDumpSerializer.java#L71-L75be_number/be_core_stat存活 BE 数量、每个 BE 的硬件核数如numOfHardwareCoresPerBe、cachedAvgNumOfHardwareCoresQueryDumpSerializer.java#L77-L82exception异常信息异常堆栈无异常时为空数组StmtExecutor.java#L1622-L1625version/commit_version集群版本号与 commit hash单元测试环境不输出QueryDumpSerializer.java#L89-L93从源码结构看当前实现还会按需追加若干面向外部目录Hive/Iceberg 等与优化器特性的字段例如external_table_catalog外部目录表的真实 catalog 名称使回放可以直接按名重建外部 catalogexternal_table_row_count、external_table_partition_spec、external_table_partition_names外部表行数与 Iceberg 分区 spec用于复现分区裁剪hms_tableHive 元数据表信息view_meta涉及视图时附带的视图定义global_dict、column_min_max低基数全局字典与列 Min/Max 元数据用于复现依赖 BE 侧元数据的改写如 meta-scan 改写、低基数 Decode 优化partition_values自动分区表达式 Range/List表的代表性分区值用于回放时重建分区。这些字段均按“db.table”键组织详见 QueryDumpSerializer.java#L133-L271。元信息脱敏desensitize为保护数据隐私StarRocks 会对库名、表名、列名等元信息做脱敏处理并用脱敏后的名称重写查询语句。脱敏默认开启若脱敏过程发生异常则回退使用原始信息同时在exception数组中记录该异常如需绕过脱敏可在 HTTP URI 中附加mockfalse。从源码看脱敏判定逻辑位于 QueryDumpSerializer.java#L97-L99只要 FE 配置enable_desensitize_query_dump为true见 Config.java#L5174-L5175可动态修改或本次请求mocktrue即进入脱敏路径。脱敏重写的具体实现在 DesensitizedSQLBuilder.java 中它先由DesensitizedInfoCollector建立“原始名称 → 模拟名称”的映射字典再依次对 SQL 文本、建表语句、视图定义、explain 输出做替换。脱敏命名规则为库名 →db_mock_NNN如tpch→db_mock_000表名 →tbl_mock_NNN如lineitem→tbl_mock_001列名/别名 →mock_NNN如L_RETURNFLAG→mock_012。值得注意的两点细节脱敏路径下统计信息中可能携带真实数据样本的字段会被剥离——stripSensitiveStatisticValues会去掉直方图histogram与 min/max 字符串值QueryDumpSerializer.java#L474-L480因为这类值本身就是原始列数据explain_info通过整词正则替换脱敏QueryDumpSerializer.java#L507-L532只要有一处无法映射就放弃输出 explain避免泄漏未脱敏的名称。接口语法与参数query_dump是一个 HTTP POST 接口注册路径为/api/query_dump见 QueryDumpAction.java#L42-L55。基本语法fe_host:fe_http_port/api/query_dump?db${database}mock${value} post_data${Query}使用wget的典型调用方式查询语句放在文件中通过--post-file作为 POST body 提交wget --user${username} --password${password} --post-file ${query_file} http://${fe_host}:${fe_http_port}/api/query_dump?db${database}mock${value} -O ${dump_file}参数说明参数说明query_file包含待 dump 查询语句的文件内容作为 POST body 发送dump_file输出文件保存接口返回的 JSONdbSQL 执行所在的数据库。若查询中已包含use db该参数可省略否则必须指定mock是否启用元信息脱敏默认true两个源码级补充db参数支持catalog.database形式。QueryDumpAction.java#L66-L76 会按.拆分参数值若为两段则第一段作为 catalog、最后一段作为库名。这意味着对外部目录如 Iceberg/Hive catalog中的表做 dump 时可以写dbiceberg_catalog.mydb来明确上下文鉴权要求。当集群启用了 HTTP 认证时该接口会校验操作权限requireOperateIfHttpAuthEnabled见 QueryDumpAction.java#L57-L59因此调用账户需要相应权限。文档示例中的--userroot --password123即对应此要求。使用示例关闭脱敏mockfalse假设待分析的 TPC-H Q1 语句保存在query_file中select l_returnflag, l_linestatus, sum(l_quantity) as sum_qty, ... from lineitem where l_shipdate date 1998-12-01 group by l_returnflag, l_linestatus order by l_returnflag, l_linestatus;执行命令wget --userroot --password123 --post-file query_file http://127.0.0.1:8030/api/query_dump?dbtpchmockfalse -O dump_file返回数据为 JSON 格式。以下示例保留了关键字段session_variables与explain_info做了截断示意完整输出中它们是整段 JSON 字符串 / 多行执行计划文本{ statement: select\n l_returnflag,\n l_linestatus,\n sum(l_quantity) as sum_qty, ..., table_meta: { tpch.lineitem: CREATE TABLE lineitem (\n L_ORDERKEY int(11) NOT NULL,\n L_QUANTITY double NOT NULL,\n ... \n) ENGINEOLAP \nDUPLICATE KEY(L_ORDERKEY)\nCOMMENT \OLAP\\nDISTRIBUTED BY HASH(L_ORDERKEY) BUCKETS 20 \nPROPERTIES (\n\replication_num\ \1\,\n\in_memory\ \false\,\n\enable_persistent_index\ \true\,\n\replicated_storage\ \true\,\n\compression\ \LZ4\\n); }, table_row_count: { tpch.lineitem: { lineitem: 3 } }, column_statistics: { tpch.lineitem: { L_TAX: [1.0, 1.0, 0.0, 8.0, 1.0] ESTIMATE, L_SHIPDATE: [1.6094304E9, 1.6094304E9, 0.0, 4.0, 1.0] ESTIMATE, L_RETURNFLAG: [-Infinity, Infinity, 0.0, 1.0, 1.0] ESTIMATE } }, explain_info: PLAN FRAGMENT 0(F02) ... 0:OlapScanNode table: lineitem, rollup: lineitem preAggregation: on Predicates: [11: L_SHIPDATE, DATE, false] 1998-12-01 partitionsRatio1/1, tabletsRatio20/20 actualRows3, avgRowSize54.0 ..., session_variables: {\query_timeout\:300,\enable_profile\:false,\cbo_push_down_aggregate\:\global\, ... }, be_number: 1, be_core_stat: { numOfHardwareCoresPerBe: {\10004\:104}, cachedAvgNumOfHardwareCores: 104 }, exception: [], version: main_querydump, commit_version: 0c4d8c8d3e }各字段解读statementFE 收到的原始 SQL排查“用户到底执行了什么”时直接对照table_meta规划器视角的完整建表语句含键类型、分桶、属性如enable_persistent_index、replicated_storage可核对表设计是否与预期一致table_row_countFE 侧记录的行数示例中lineitem仅 3 行是规划器基数估算的基础——若行数统计严重失准往往直接导致选错 Join 顺序column_statistics各列统计区间与 NDVESTIMATE表示来自统计信息而非精确值explain_infoTExplainLevel.COSTS级别的执行计划包含每个 Fragment 的算子、cardinality 与列统计传播过程可直接用于分析分区裁剪partitionsRatio、tabletsRatio与聚合下推行为session_variables完整会话变量快照用于核对诸如query_timeout、cbo_*优化器开关等对计划有影响的配置be_number与be_core_statBE 数量与硬件核数规格帮助判断资源维度的问题exception若执行过程中捕获到异常堆栈会记录在此无异常则为空数组。开启脱敏默认wget --userroot --password123 --post-file query_file http://127.0.0.1:8030/api/query_dump?dbtpch -O dump_file返回的 JSON 结构与上例一致但所有元信息被替换为模拟名称查询语句也被同步重写{ statement: SELECT tbl_mock_001.mock_012, tbl_mock_001.mock_007, sum(tbl_mock_001.mock_010) AS mock_019, ... FROM db_mock_000.tbl_mock_001 WHERE tbl_mock_001.mock_013 1998-12-01 GROUP BY tbl_mock_001.mock_012, tbl_mock_001.mock_007 ORDER BY tbl_mock_001.mock_012 ASC, tbl_mock_001.mock_007 ASC, table_meta: { db_mock_000.tbl_mock_001: CREATE TABLE db_mock_000.tbl_mock_001 (\nmock_008 int(11) NOT NULL,\nmock_010 double NOT NULL, ... \n) ENGINEOLAP \nDUPLICATE KEY(mock_008)\nDISTRIBUTED BY HASH(mock_008) BUCKETS 20 \nPROPERTIES (\replication_num\ \1\); }, table_row_count: { db_mock_000.tbl_mock_001: { tbl_mock_001: 3 } }, column_statistics: { db_mock_000.tbl_mock_001: { mock_017: [1.0, 1.0, 0.0, 8.0, 1.0] ESTIMATE, mock_012: [-Infinity, Infinity, 0.0, 1.0, 1.0] ESTIMATE } }, explain_info: PLAN FRAGMENT 0(F02) ... 0:OlapScanNode table: mock_001, rollup: mock_001 ..., session_variables: {...}, be_number: 1, exception: [] }对比可见tpch/lineitem/L_*全部被替换为db_mock_000/tbl_mock_001/mock_NNN但表的形状列类型、键、分桶数、行数、统计区间形态、计划结构完整保留——这正是脱敏设计目标既不泄漏业务元数据又不丢失复现问题所需的全部结构信息。仓库中也提供了对应的脱敏 dump 样例文件如 mock_example.json可参考其完整结构。源码实现走读dump 数据从哪来从源码结构看一次query_dump请求的完整链路为HTTP 入口QueryDumpAction注册 POST/api/query_dump解析db、mock参数mock缺省即为true并将当前ConnectContext标记为 HTTP dump 请求QueryDumpAction.java#L57-L85重新执行查询规划QueryDumper.dumpQuery先校验库是否存在然后用SqlParser解析语句并构造StmtExecutor执行——注意这里走的是与正常查询相同的分析/优化路径只是不真正下发执行QueryDumper.java#L54-L109链路中持续填充 DumpInfoConnectContext内嵌DumpInfo当isHTTPQueryDump为真或会话变量enable_query_dump开启见 ConnectContext.java#L1087-L1095时分析器与元数据管理器在正常流程中“顺手”把元数据写入语句原文StmtExecutor.java#L846-L852、表统计如 MetadataMgr.java#L776-L814 中的列统计与外部表行数、explain 文本StmtExecutor.java#L896、异常堆栈StmtExecutor.java#L1622-L1625。这也解释了为什么 dump 中的统计与计划信息“与规划器所见完全一致”序列化返回执行结束后取回DumpInfo经QueryDumpSerializerGson 定制序列化器输出 JSONmock参数决定走脱敏或原始路径QueryDumper.java#L96-L103。一个值得注意的失败模式如果语句没有走 CBO 规划器dumpInfo为空接口会返回BAD_REQUEST: not use cbo planner, try again.QueryDumper.java#L101-L103。此外查询为空query is empty与库不存在Database [...] does not exists返回 404也都有明确的状态码与错误信息。dump 文件的离线回放价值dump 文件不只是“给人看的报告”QueryDumpInfo同时注册了反序列化器QueryDumpDeserializerFE 单元测试可以直接加载一个 dump JSON在无任何真实集群的环境下重建元数据并复现同一条执行计划或同一个报错。仓库中已沉淀了大量此类回放用例回放框架与测试ReplayFromDumpTest.java、ReplayFromDumpForSharedDataTest.java、ReplayWithMVFromDumpTest.java、QueryDumpHistogramReplayTest.java、QueryDumpExternalCatalogReplayTest.java覆盖典型问题的 dump 样例库sql/query_dump/ 目录下有上百个真实问题的 dump 文件例如 tpch01.jsonTPC-H Q1 基线、prune_table_npe.json表裁剪 NPE、join_reorder.jsonJoin 重排、auto_partition_month.json自动分区、hive_catalog_partition_skew.jsonHive 目录倾斜等脱敏样例mock-files/mock_example.json。这提示了一条实用工作流遇到难以复现的规划器问题时除了把 dump 文件提交给技术支持还可以参考上述测试用例的写法把 dump 文件固化为一个回放测试使问题在 CI 中可长期回归。注意事项小结db参数在查询未显式use db时必传跨 catalog 场景可用catalog.database形式指定mock缺省即开启脱敏绕过脱敏会输出真实库表列名与统计样本仅应在受控环境如技术支持协助排查、内部测试集群下使用脱敏失败不会导致请求失败而是回退为原始内容并把异常写入exception字段使用脱敏结果前可先检查该字段接口要求查询能走 CBO 规划器否则返回not use cbo planner错误集群开启 HTTP 认证时调用账户需具备相应权限文档示例中的--user/--password。通过上述机制query_dump把“用户端一条模糊报错”转化为“FE 规划器完整输入快照”是 StarRocks 问题排查中连接现场与离线复现之间的关键桥梁。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考