field_caps 是什么
field_caps 汇总一个或多个索引中字段的类型信息：每个字段的 type、是否可搜索、是否可聚合，以及它出现在哪些索引里。跨索引查询报字段类型冲突、或统计结果与预期不符时，用它先核对各索引的字段定义差异，比逐个查 mapping 快得多。带上 include_unmapped 参数还会把完全不含该字段的索引一并列出，便于确认覆盖范围是否完整。
基本信息
| 接口 | GET /<index>/_field_caps?fields=* |
|---|---|
| 常用参数 | fields、include_unmapped=true、index_filter |
| 返回内容 | type、searchable、aggregatable、indices |
| 典型问题 | 跨索引同名字段类型不同导致查询行为不一致 |
| 所属系统 | Elasticsearch / OpenSearch |
典型使用场景
- 跨索引核对：同一字段在多个索引里的定义是否一致
- 排查查询失败：类型冲突导致的报错用它先定位来源索引
- 确认聚合可行性：看字段是否可聚合，避免写出跑不动的聚合
- 检查覆盖范围：借 include_unmapped 找出缺少该字段的索引
- 迁移前体检：新一批索引导入前核对字段类型是否符合预期
常见查询
常见查询
GET /logs-*/_field_caps?fields=status,message # 只看关心的字段
GET /_field_caps?fields=*&include_unmapped=true # 全字段，并列出缺失该字段的索引
GET /logs-*/_field_caps?fields=status&index_filter={"range":{"@timestamp":{"gte":"now-7d"}}} # 只看最近索引返回项读法
| 项 | 含义 | 读法 |
|---|---|---|
| type | 字段类型 | keyword 与 text 混用会让查询行为不一致 |
| searchable | 能否用于查询 | 为 false 时该字段查不到 |
| aggregatable | 能否用于聚合 | text 字段默认不可聚合 |
| indices | 出现该字段的索引 | 用于定位差异来源 |
| unmapped | 未定义该字段的索引 | 需 include_unmapped 才显示 |
字段在部分索引缺失不会让查询报错，只是那些索引里无法命中，统计口径会因为覆盖不全而偏低；跨索引报表前先确认字段覆盖范围。
同一字段名在不同索引里一个是 keyword、一个是 text，会让排序与聚合行为互不一致，迁移期用 field_caps 找出差异后统一 mapping。
多字段（text 带 keyword 子字段）与运行时字段在输出里会各占一条，看到同一名字出现多条记录时先分清是子字段还是真的类型冲突。