---
title: "获取字段能力"
date: 2026-01-27
lastmod: 2026-01-27
description: "获取指定字段在索引中的能力信息"
tags: ["索引", "映射", "字段", "查询"]
summary: "检索一个或多个索引中指定字段的能力（映射和元数据）信息，包括字段类型、是否可搜索、是否可聚合等。
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?"
---


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

## 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=*
```

## 响应示例

```json
{
  "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 | 字段元数据（如日期字段的格式等） |

## 使用场景

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

## 注意事项

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