---
title: "查询字段数据缓存"
date: 2026-02-09
lastmod: 2026-02-09
description: "介绍如何使用 Cat API 查询 Easysearch 集群中字段数据（fielddata）的内存使用情况。"
tags: ["Cat API", "字段数据", "内存", "监控"]
summary: "此 API 用于显示集群中每个数据节点的字段数据（fielddata）当前使用的堆内存大小。
API #  GET /_cat/fielddata GET /_cat/fielddata/{fields} API 的作用 #  返回集群中每个节点上按字段分组的 fielddata 内存使用情况统计。Fielddata 是 Lucene 在排序和聚合操作时使用的缓存数据，常驻堆内存。
此 API 用于：
 内存监控：监控哪些字段占用了大量内存 性能优化：识别高内存消耗的字段 问题排查：诊断内存相关的性能问题 容量规划：评估 JVM 堆内存的使用情况  API 的参数 #  路由参数 #     参数 类型 是否必需 描述     fields string 可选 要查询的字段列表
可以用逗号分隔多个字段
例如：field1,field2
默认：显示所有字段    查询字符串参数 #     参数 类型 是否必需 默认值 描述     bytes string 可选 自动 字节显示单位"
---


此 API 用于显示集群中每个数据节点的字段数据（fielddata）当前使用的堆内存大小。

## API

```
GET /_cat/fielddata
GET /_cat/fielddata/{fields}
```

## API 的作用

返回集群中每个节点上按字段分组的 fielddata 内存使用情况统计。Fielddata 是 Lucene 在排序和聚合操作时使用的缓存数据，常驻堆内存。

此 API 用于：

- **内存监控**：监控哪些字段占用了大量内存
- **性能优化**：识别高内存消耗的字段
- **问题排查**：诊断内存相关的性能问题
- **容量规划**：评估 JVM 堆内存的使用情况

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `fields` | string | 可选 | 要查询的字段列表<br>可以用逗号分隔多个字段<br>例如：`field1,field2`<br>默认：显示所有字段 |

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `bytes` | string | 可选 | 自动 | 字节显示单位<br>可选值：`b`, `k`, `kb`, `m`, `mb`, `g`, `gb`, `t`, `tb`, `p`, `pb` |
| `fields` | string | 可选 | * | 指定要返回的字段列表（逗号分隔） |
| `format` | string | 可选 | text | 响应格式<br>可选值：`json`, `yaml`, `text` |
| `h` | string | 可选 | 默认列 | 指定显示的列，逗号分隔 |
| `help` | boolean | 可选 | false | 显示帮助信息 |
| `s` | string | 可选 | - | 排序列<br>支持 `:asc` 和 `:desc` |
| `v` | boolean | 可选 | false | 详细模式，显示列头 |

## 返回的字段信息

| 列名 | 别名 | 描述 |
|------|------|------|
| `id` | - | 节点 ID |
| `host` | `h` | 主机名 |
| `ip` | - | IP 地址 |
| `node` | `n` | 节点名称 |
| `field` | `f` | 字段名称 |
| `size` | `s` | 字段数据使用量 |

## 请求示例

```bash
# 查询所有字段的 fielddata 使用情况
GET /_cat/fielddata

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

# 查询特定字段
GET /_cat/fielddata/product_name,category,tags

# 查询特定字段（使用查询字符串参数）
GET /_cat/fielddata?fields=product_name,category

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

# 只显示特定列
GET /_cat/fielddata?h=field,size,node

# 按内存使用量降序排列
GET /_cat/fielddata?s=size:desc

# 设置字节单位为 MB
GET /_cat/fielddata?bytes=mb

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

## 响应示例

### 文本格式（默认）

```
id           host      ip         node         field              size
node-abc123  10.0.1.10 192.168.1.10 data-node-1 product_name      450mb
node-abc123  10.0.1.10 192.168.1.10 data-node-1 category           120mb
node-abc123  10.0.1.10 192.168.1.10 data-node-1 tags               580mb
node-def456  10.0.1.11 192.168.1.11 data-node-2 product_name      420mb
node-def456  10.0.1.11 192.168.1.11 data-node-2 category           115mb
node-def456  10.0.1.11 192.168.1.11 data-node-2 tags               560mb
```

### JSON 格式

```json
[
  {
    "id": "node-abc123",
    "host": "10.0.1.10",
    "ip": "192.168.1.10",
    "node": "data-node-1",
    "field": "product_name",
    "size": "450mb"
  },
  {
    "id": "node-abc123",
    "host": "10.0.1.10",
    "ip": "192.168.1.10",
    "node": "data-node-1",
    "field": "tags",
    "size": "580mb"
  }
]
```

### 按内存使用量排序

```bash
GET /_cat/fielddata?s=size:desc&v
```

```
id           host      ip         node         field              size
node-abc123  10.0.1.10 192.168.1.10 data-node-1 tags               580mb
node-abc123  10.0.1.10 192.168.1.10 data-node-1 product_name      450mb
node-def456  10.0.1.11 192.168.1.11 data-node-2 tags               560mb
node-def456  10.0.1.11 192.168.1.11 data-node-2 product_name      420mb
```

## 使用场景

1. **内存分析**：分析哪些字段占用了大量堆内存
2. **性能优化**：优化高内存消耗的字段配置
3. **问题排查**：诊断 OutOfMemoryError 问题
4. **容量规划**：评估 JVM 堆内存需求
5. **缓存监控**：监控 fielddata 缓存的命中率

## Fielddata 相关概念

### Fielddata 是什么？
Fielddata 是 Lucene 在内存中存储的数据结构，用于：
- 排序操作
- 聚合计算
- 脚本访问字段值

### Fielddata 的特点
- **按需加载**：字段首次被使用时加载到内存
- **常驻内存**：加载后会一直保留在堆内存中
- **全局缓存**：所有分片共享同一份 fielddata

### Fielddata 优化策略

#### 1. 使用 doc_values
对于排序和聚合字段，优先使用 `doc_values`：

```json
{
  "mappings": {
    "properties": {
      "product_name": {
        "type": "keyword",
        "doc_values": true
      }
    }
  }
}
```

#### 2. 限制 fielddata 大小
在 `easysearch.yml` 中设置：

```yaml
indices.breaker.fielddata.limit: 40%
indices.breaker.total.limit: 70%
```

#### 3. 禁用不需要的字段
对于不需要排序/聚合的字段，禁用 fielddata：

```json
{
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "fielddata": false
      }
    }
  }
}
```

## Circuit Breaker 设置

当 fielddata 达到配置的限制时，Circuit Breaker 会阻止查询以防止内存溢出：

```yaml
# fielddata 断路器限制
indices.breaker.fielddata.limit: 40%

# 请求断路器限制
indices.breaker.request.limit: 20%

# 总断路器限制
indices.breaker.total.limit: 70%
```

## 注意事项

1. 此 API 只支持 GET 方法
2. 只显示已加载 fielddata 的字段
3. 未被使用的字段不会出现在结果中
4. fielddata 会占用大量堆内存，需要合理规划
5. 高基数字段（如用户 ID）会占用大量内存

## 最佳实践

1. **使用 doc_values**：对于排序和聚合字段，使用 doc_values 替代 fielddata
2. **限制字段数量**：只对必要的字段启用 fielddata
3. **监控内存使用**：定期检查 fielddata 内存占用
4. **设置断路器**：合理配置 Circuit Breaker 限制
5. **优化数据类型**：选择合适的字段类型，如使用 keyword 而非 text

## 相关文档

- [查询节点](./get-node.md)
- [查询分段信息](./get-segment-info-cat-format.md)
- [查询节点统计](./get-node-stats.md)