查询字段数据缓存

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

API #

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

API 的作用 #

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

此 API 用于：

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

API 的参数 #

路由参数 #

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

查询字符串参数 #

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

返回的字段信息 #

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

请求示例 #

# 查询所有字段的 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 格式 #

[
  {
    "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"
  }
]

按内存使用量排序 #

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

使用场景 #

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

Fielddata 相关概念 #

Fielddata 是什么？ #

Fielddata 是 Lucene 在内存中存储的数据结构，用于：

排序操作
聚合计算
脚本访问字段值

Fielddata 的特点 #

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

Fielddata 优化策略 #

1. 使用 doc_values #

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

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

2. 限制 fielddata 大小 #

在 easysearch.yml 中设置：

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

3. 禁用不需要的字段 #

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

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

Circuit Breaker 设置 #

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

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

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

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

注意事项 #

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

最佳实践 #

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