企业官网建设流程全解析

• 大数据
• 数据库
• 后端

Stage Resource 是 Presto 提供给用户和运维工具的一套 HTTP 接口，用于获取查询中某个 Stage（阶段）的详情，以及按需取消（删除）正在执行的 Stage。本文以官方文档 presto-docs/src/main/sphinx/rest/stage.rst 为骨架，结合本仓库源码深入讲解这两个接口的语义、参数格式、调用方式与底层实现链路，帮助你掌握通过 REST API 监控和干预 Presto 分布式查询执行的方法。

1. 接口总览

Stage Resource 暴露在 Presto coordinator 的/v1/stage路径下，包含两个接口：

这两个接口与 Query Resource、Task Resource、Node Resource 等共同组成了 Presto 面向管理监控的 REST API 体系。

其中，Stage 是 Presto 执行模型中的关键概念：一条 SQL 查询会被拆分为多个 Stage（例如根输出 Stage、聚合 Stage、表扫描 Stage），每个 Stage 由分布在集群各节点上的 Task 组成。因此，能够按 Stage 粒度查看状态和取消执行，是运维大规模分布式查询的重要能力。

2. 两个接口逐一解析

2.1GET /v1/stage— 获取 Stage 详情

原文档描述：

Returns detail about a stage in a Presto query.

即该接口返回某条查询中指定 Stage 的详细执行信息。从调用语义上看，它服务于两类场景：

• 监控与诊断：通过浏览器或脚本查看某个 Stage 下各 Task 的状态、输入输出数据量、CPU 时间、内存占用等统计信息，定位慢 Stage 或数据倾斜；
• 二次开发：作为工具链（如自定义 Web UI、监控报警系统）获取执行细节的数据源。

需要注意，文档中GET /v1/stage没有带路径参数，说明这是一个“查询入口”，Stage 详情通常在更大的查询信息结构中获取。在实践中，更常见的做法是通过GET /v1/query/{queryId}拿到查询的outputStage树，其中每个StageInfo节点（通过stageId、self等字段）就包含了对应 Stage 的状态和统计；也可直接浏览 Presto coordinator 的 Web 界面查看渲染后的查询执行树。

从源码层面看，QueryStateMachine 中通过pruneStageExecutionInfo对 Stage 信息进行剪枝，仅保留根输出 Stage（outputStage），并注释明确说明"Remove the substages"——即对外暴露的查询信息结构以输出 Stage 为根、向下展开整个 Stage 树，这正是 Stage 详细信息的载体。

2.2DELETE /v1/stage/{stageId}— 删除（取消）Stage

原文档描述：

Deletes a stage in a Presto query.

即通过DELETE方法按stageId取消查询中指定的 Stage。这是本 Resource 在源码中实际实现的核心动作，也是运维介入分布式查询执行、及时释放集群资源的重要手段（例如发现某个 Stage 长时间卡死或数据倾斜时可以定向取消）。

两个接口都要求调用者具备相应权限：在源码中，StageResource类声明了@RolesAllowed(USER)（见 StageResource.java），即仅允许具备USER角色的认证用户访问，这也是 Presto 安全模型中 REST 接口访问控制的一部分。

3.stageId的格式与解析规则

DELETE /v1/stage/{stageId}中的stageId由查询 ID + 整数序号组成，格式为<queryId>.<stageNumber>，例如：

20231229_120000_00001_abcde.2

其中：

• queryId是这条查询的全局唯一标识（形如20131229_211533_00017_dk5x2）；
• 点号后的整数是该查询内部 Stage 的序号（从 0 开始，非负）。

该解析规则在 StageId.java 中有完整实现：

@JsonCreator public static StageId valueOf(String stageId) { List<String> ids = QueryId.parseDottedId(stageId, 2, "stageId"); return valueOf(ids); } public static StageId valueOf(List<String> ids) { checkArgument(ids.size() == 2, "Expected two ids but got: %s", ids); return new StageId(new QueryId(ids.get(0)), Integer.parseInt(ids.get(1))); }

关键细节：

• 通过QueryId.parseDottedId(stageId, 2, "stageId")以点号为分隔符拆成恰好两个部分，数量不对会直接抛异常；
• 第二部分必须是非负整数（构造函数中有checkArgument(id >= 0, "id is negative: %s", id)校验，见 StageId.java）；
• 该 ID 同时支持 JSON 反序列化（@JsonCreator）与 Thrift 序列化（@ThriftStruct/@ThriftField），说明它不仅在 REST 层使用，也用于 Presto 内部节点间通信。

# 取消查询 abcde.2 中的第 2 个 Stage（注意：实际 queryId 为完整格式） curl -X DELETE "http://<coordinator-host>:8080/v1/stage/20131229_211533_00017_dk5x2.2"

4. 底层实现：从 REST 请求到 Stage 取消

4.1 REST 层的请求映射

StageResource是 JAX-RS 风格的资源类（StageResource.java）：

@Path("/v1/stage") @RolesAllowed(USER) public class StageResource { private final QueryManager queryManager; @Inject public StageResource(QueryManager queryManager) { ... } @DELETE @Path("{stageId}") public void cancelStage(@PathParam("stageId") StageId stageId) { requireNonNull(stageId, "stageId is null"); queryManager.cancelStage(stageId); } }

要点：

• @Path("{stageId}")将 URL 路径中的stageId段绑定到@PathParam，并由框架自动调用StageId.valueOf完成字符串到对象的转换；
• 依赖注入QueryManager，通过@Inject构造器注入（com.facebook.presto.execution.QueryManager），实现资源层与执行管理层的解耦；
• 值得注意的是：该类中并未实现GET /v1/stage的 JAX-RS 方法——文档描述的两个接口中，真正落到这段源码的是DELETE操作；而 Stage 详情数据的获取实际发生在QueryManager.getQueryInfo(...)返回的outputStage树结构中（详见第 2.1 节）。

4.2 执行管理层：按 queryId 定位并取消

QueryManager.cancelStage(StageId)的实现在 SqlQueryManager.java：

@Override public void cancelStage(StageId stageId) { requireNonNull(stageId, "stageId is null"); log.debug("Cancel stage %s", stageId); queryTracker.tryGetQuery(stageId.getQueryId()) .ifPresent(query -> query.cancelStage(stageId)); }

调用链可以概括为：

DELETE /v1/stage/{stageId} └─ StageResource.cancelStage() （REST 层，参数解析） └─ QueryManager.cancelStage() （接口定义，见 QueryExecution.java#L94 对应声明） └─ SqlQueryManager.cancelStage() （按 stageId.getQueryId() 找到查询） └─ QueryExecution.cancelStage() （真正的 Stage 取消逻辑）

设计要点：

• 用 queryId 而非 stageId 定位查询：cancelStage先通过stageId.getQueryId()取出所属查询 ID，再在queryTracker中查找对应的QueryExecution，找不到则静默忽略（ifPresent）——这保证了即使 Stage 已被清理，DELETE 请求也不会抛错；
• 与取消整个查询的区别：cancelQuery(QueryId)会终止整条查询（同上文件中第 339-345 行），而cancelStage(StageId)只针对查询内的单个 Stage，粒度更细；
• QueryExecution接口中对cancelStage的声明见 QueryExecution.java，表明这是一个跨 REST 层与执行引擎层的标准能力。

5. 与周边 REST 资源的关系

Stage Resource 不是孤立的，它与 Presto 的 REST API 家族协同工作：

一条典型的运维排查流程是：

1. GET /v1/query列出当前运行查询，找到目标queryId；
2. GET /v1/query/{queryId}查看outputStage树，定位需要关注的 Stage 及其stageId（其中包含各 Task 的状态、totalCpuTime、processedInputDataSize等统计字段，字段语义可参考 query.rst 中queryStats的示例）；
3. 若确认某 Stage 需要终止，调用DELETE /v1/stage/{queryId.stageNumber}定向取消。

6. 使用注意事项

• 仅在 coordinator 上暴露：/v1/stage由 coordinator 侧的StageResource提供，worker 节点不处理该路径；
• 需要认证：接口标注@RolesAllowed(USER)，在启用认证的集群中，未授权调用会返回 403；
• 取消是异步的：cancelStage通过queryTracker找到查询后调用query.cancelStage(stageId)，实际的 Stage 终止由执行引擎异步完成，DELETE 请求本身不保证立即返回最终状态；
• 参数格式敏感：stageId必须是<queryId>.<非负整数>，缺段、多段或序号非数字都会导致参数解析失败；
• GET 详情的正确入口：如需获取 Stage 详情，建议优先使用GET /v1/query/{queryId}（返回的outputStage结构即 Stage 树），这比直接调用GET /v1/stage信息更完整、可解析。

7. 小结

Stage Resource 是 Presto REST API 中面向"查询内执行单元"的管理入口：GET /v1/stage承载 Stage 详情查询的语义（详情数据在实际查询信息结构中以outputStage树呈现），DELETE /v1/stage/{stageId}则实现按 Stage 粒度的定向取消。通过 StageResource.java、SqlQueryManager.java 与 StageId.java 三处源码，可以完整串起"HTTP 请求 → 参数解析 → 查询定位 → Stage 取消"的调用链。掌握这套接口，是构建 Presto 查询监控、诊断与运维自动化能力的基础一环。

• 大数据
• 数据库
• 后端