获取字段能力

检索一个或多个索引中指定字段的能力（映射和元数据）信息，包括字段类型、是否可搜索、是否可聚合等。

API 格式 #

GET /_field_caps
POST /_field_caps
GET /{index}/_field_caps
POST /{index}/_field_caps

API 作用 #

该 API 用于获取指定字段在索引中的能力信息，包括：

字段类型（text、keyword、long、date 等）
字段是否可搜索
字段是否可聚合
字段关联的元数据
哪些索引包含哪种字段类型

API 参数 #

路径参数 #

参数	类型	是否必填	默认值	描述
`{index}`	String	否	所有索引	逗号分隔的索引名称列表

查询参数 #

参数	类型	是否必填	默认值	描述
`fields`	String	是	-	逗号分隔的字段名称列表。该参数为必填项
`include_unmapped`	Boolean	否	`false`	是否在响应中包含未映射的字段
`index_filter`	Query	否	-	用于进一步限制检查范围的查询过滤器

请求示例 #

# 获取所有索引中指定字段的能力
GET /_field_caps?fields=title,content,author

# 获取特定索引中字段的能力
GET /my_index/_field_caps?fields=title&include_unmapped=true

# 使用 POST 方法
POST /_field_caps?fields=*

响应示例 #

{
  "indices": ["index1", "index2"],
  "fields": {
    "title": {
      "text": {
        "type": "text",
        "searchable": true,
        "aggregatable": false,
        "indices": ["index1", "index2"],
        "non_searchable_indices": null,
        "non_aggregatable_indices": ["index1", "index2"],
        "meta": {}
      }
    },
    "category": {
      "keyword": {
        "type": "keyword",
        "searchable": true,
        "aggregatable": true,
        "indices": ["index1"],
        "non_searchable_indices": null,
        "non_aggregatable_indices": null,
        "meta": {}
      }
    },
    "created_at": {
      "date": {
        "type": "date",
        "searchable": true,
        "aggregatable": true,
        "indices": ["index2"],
        "non_searchable_indices": null,
        "non_aggregatable_indices": null,
        "meta": {
          "format": "date_optional_time"
        }
      }
    }
  }
}

响应字段说明 #

顶层字段 #

字段	类型	描述
`indices`	Array	被检查的具体索引列表
`fields`	Object	字段信息对象，键为字段名称

fields 对象 #

每个字段包含以下信息：

字段	类型	描述
`type`	String	字段类型（如 “text”、“keyword”、“long”、“date” 等）
`searchable`	Boolean	字段是否可搜索
`aggregatable`	Boolean	字段是否可聚合
`indices`	Array	存在该字段且具有该类型的索引列表
`non_searchable_indices`	Array/null	字段不可搜索的索引列表（如果全部可搜索则为 null）
`non_aggregatable_indices`	Array/null	字段不可聚合的索引列表（如果全部可聚合则为 null）
`meta`	Object	字段元数据（如日期字段的格式等）

使用场景 #

动态查询构建：应用在构建查询前了解字段类型和能力
聚合规划：确定哪些字段可用于聚合操作
数据探索：分析工具动态了解索引结构
跨索引查询：了解多个索引中字段的差异性

注意事项 #

fields 参数为必填项，至少指定一个字段
默认情况下会合并所有索引的结果
同一字段在不同索引中可能有不同的类型
支持跨集群搜索功能
对于未映射的字段，只有设置 include_unmapped=true 时才会包含在响应中

标签

索引映射字段查询