---
title: "查询待办任务"
date: 2026-03-17
lastmod: 2026-03-17
description: "介绍如何使用 Cat API 查询 Easysearch 集群中待处理的集群管理任务。"
tags: ["Cat API", "集群管理", "任务"]
summary: "此 API 用于返回集群中待处理任务（Pending Cluster Tasks）的简洁表示。
API #  GET /_cat/pending_tasks API 的作用 #  以表格形式显示当前集群中等待执行的集群管理任务信息。这些任务通常是需要在主节点上执行的集群级操作，包括：
 任务插入顺序：任务在队列中的位置 等待时间：任务在队列中等待的时间 任务优先级：任务的执行优先级 任务来源：任务的来源描述  待办任务通常在主节点负载较高或网络延迟较大时堆积。长时间堆积可能表示集群管理操作存在瓶颈。
API 的参数 #  此 API 没有路由参数。
查询字符串参数 #     参数 类型 是否必需 默认值 描述     format string 可选 text 响应格式
可选值：json, yaml, text   h string 可选 默认列 指定显示的列，逗号分隔   help boolean 可选 false 显示帮助信息   local boolean 可选 false 是否从本地节点获取信息   master_timeout time 可选 30s 等待主节点响应的超时时间   s string 可选 - 排序列"
---


此 API 用于返回集群中待处理任务（Pending Cluster Tasks）的简洁表示。

## API

```
GET /_cat/pending_tasks
```

## API 的作用

以表格形式显示当前集群中等待执行的集群管理任务信息。这些任务通常是需要在主节点上执行的集群级操作，包括：

- **任务插入顺序**：任务在队列中的位置
- **等待时间**：任务在队列中等待的时间
- **任务优先级**：任务的执行优先级
- **任务来源**：任务的来源描述

待办任务通常在主节点负载较高或网络延迟较大时堆积。长时间堆积可能表示集群管理操作存在瓶颈。

## API 的参数

此 API **没有**路由参数。

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `format` | string | 可选 | text | 响应格式<br>可选值：`json`, `yaml`, `text` |
| `h` | string | 可选 | 默认列 | 指定显示的列，逗号分隔 |
| `help` | boolean | 可选 | false | 显示帮助信息 |
| `local` | boolean | 可选 | false | 是否从本地节点获取信息 |
| `master_timeout` | time | 可选 | 30s | 等待主节点响应的超时时间 |
| `s` | string | 可选 | - | 排序列<br>支持 `:asc` 和 `:desc` |
| `time` | string | 可选 | - | 时间显示单位<br>可选值：`d`, `h`, `m`, `s`, `ms`, `micros`, `nanos` |
| `v` | boolean | 可选 | false | 详细模式，显示列头 |

## 返回的字段信息

| 列名 | 别名 | 描述 | 对齐方式 |
|------|------|------|----------|
| `insertOrder` | `o` | 任务插入顺序 | 右对齐 |
| `timeInQueue` | `t` | 任务在队列中的时间 | 右对齐 |
| `priority` | `p` | 任务优先级 | 左对齐 |
| `source` | `s` | 任务来源 | 左对齐 |

## 任务优先级

任务优先级从高到低为：

| 优先级 | 描述 |
|--------|------|
| `URGENT` | 紧急任务，最高优先级 |
| `HIGH` | 高优先级任务 |
| `MEDIUM` | 中等优先级任务 |
| `LOW` | 低优先级任务 |
| `LANGUID` | 慢速任务，最低优先级 |

## 请求示例

```bash
# 查询待办任务
GET /_cat/pending_tasks

# 显示列头
GET /_cat/pending_tasks?v

# 使用 JSON 格式
GET /_cat/pending_tasks?format=json

# 按等待时间降序排序
GET /_cat/pending_tasks?s=timeInQueue:desc

# 设置时间单位为秒
GET /_cat/pending_tasks?time=s

# 只显示特定列
GET /_cat/pending_tasks?h=insertOrder,priority,source

# 显示帮助信息
GET /_cat/pending_tasks?help
```

## 响应示例

### 文本格式（默认）

```
insertOrder timeInQueue priority source
         1        2.3s HIGH     update-mapping [index1]
         2        1.8s HIGH     put-mapping [index2]
         3      850ms MEDIUM   create-index [index3]
         4      120ms LOW      cluster_reroute
```

### JSON 格式

```json
[
  {
    "insert_order": "1",
    "time_in_queue": "2.3s",
    "priority": "HIGH",
    "source": "update-mapping [index1]"
  },
  {
    "insert_order": "2",
    "time_in_queue": "1.8s",
    "priority": "HIGH",
    "source": "put-mapping [index2]"
  }
]
```

### 无待办任务时的响应

```
insertOrder timeInQueue priority source
```

### 帮助信息

```
insertOrder  | o           | task insertion order
timeInQueue  | t           | time in queue
priority     | p           | task priority
source       | s           | task source
```

## 使用场景

1. **集群监控**：监控集群管理任务的堆积情况
2. **性能诊断**：诊断主节点是否过载
3. **问题排查**：查找导致集群操作缓慢的原因
4. **容量规划**：评估是否需要增加主节点资源

## 常见任务来源

| 任务来源 | 描述 |
|----------|------|
| `update-mapping` | 更新索引映射 |
| `put-mapping` | 添加字段映射 |
| `create-index` | 创建索引 |
| `delete-index` | 删除索引 |
| `cluster_reroute` | 集群路由重分配 |
| `gateway-meta-state` | 网关元数据状态更新 |
| `master-failover` | 主节点故障切换 |

## 待办任务堆积的原因

1. **主节点过载**：主节点处理能力不足
2. **网络延迟**：节点间网络通信延迟高
3. **频繁的集群状态更新**：大量并发的集群管理操作
4. **慢速操作**：某些耗时操作阻塞了任务队列

## 排查建议

1. **检查主节点资源**：查看主节点的 CPU、内存使用情况
2. **查看任务详情**：使用 `GET /_cluster/pending_tasks` 获取更详细的信息
3. **优化集群操作**：减少频繁的小操作，合并为批量操作
4. **增加主节点资源**：考虑升级主节点配置

## 注意事项

1. 此 API 只支持 GET 方法
2. 待办任务列表动态变化，每次查询结果可能不同
3. 任务按插入顺序排列，数字越小表示越早进入队列
4. 无待办任务时返回空表格
5. `local=true` 时可能返回过时信息

## 与相关 API 的配合

| API | 功能 |
|-----|------|
| `GET /_cat/pending_tasks` | 查看待办任务的简洁视图 |
| `GET /_cluster/pending_tasks` | 查看待办任务的详细信息 |

## 最佳实践

1. **定期监控**：定期检查待办任务数量和等待时间
2. **设置告警**：当任务堆积超过阈值时告警
3. **分析模式**：分析任务来源，找出频繁操作的来源
4. **优化操作**：优化应用层逻辑，减少不必要的集群管理操作

## 相关文档

- [获取集群状态](./get-cluster-state.md)
- [查询主节点](./get-master-node.md)
- [查询节点](./get-node.md)