Link Search Menu Expand Document Documentation Menu
文档

字段功能 API

_field_caps API 提供关于一个或多个索引中字段功能的信息。客户端通常使用它来确定字段如何映射，以及它们是否可以跨多个索引用于搜索、排序和聚合。

当索引具有不同的映射并且查询需要评估它们之间的字段兼容性时，此 API 特别有用。

端点

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

路径参数

下表列出了可用的路径参数。

参数 数据类型 描述
index 列表或字符串 以逗号分隔的数据流、索引和别名列表，用于限制请求。支持通配符 (*)。要定位所有数据流和索引，请省略此参数或使用 * 或 _all。可选。

查询参数

下表列出了可用的查询参数。所有查询参数都是可选的。

参数 数据类型 描述
allow_no_indices 布尔型 如果为 false，则当任何通配符表达式、索引别名或 _all 值仅指向缺失或关闭的索引时，请求将返回错误。即使请求指向其他打开的索引，此行为也适用。例如，如果某个索引以 foo 开头但没有索引以 bar 开头，则针对 foo*,bar* 的请求会返回错误。默认值为 true。
expand_wildcards 列表或字符串 通配符模式可以匹配的索引类型。如果请求可以针对数据流，此参数将确定通配符表达式是否匹配隐藏数据流。支持逗号分隔值，例如 open,hidden。
有效值为
- all：匹配任何索引，包括隐藏索引。
- closed：匹配已关闭的非隐藏索引。
- hidden: 匹配隐藏索引。必须与 open、closed 或两者结合使用。
- none：不接受通配符表达式。
- open：匹配已打开的非隐藏索引。
默认值为 open。
fields 列表或字符串 以逗号分隔的字段列表，用于检索其功能。支持通配符 (*) 表达式。
ignore_unavailable 布尔型 如果为 true，则响应中不包含缺失或关闭的索引。默认值为 false。
include_unmapped 布尔型 如果为 true，则响应中包含未映射的字段。默认值为 false。

请求正文字段

下表列出了可用的请求正文字段。

字段 数据类型 描述
index_filter 对象 一个用于过滤请求中包含的索引的查询 DSL 对象。参见示例：使用索引过滤器。可选。

示例

创建两个对同一字段具有不同映射的索引

PUT /store-west
{
  "mappings": {
    "properties": {
      "product": { "type": "text" },
      "price": { "type": "float" }
    }
  }
}


PUT /store-east
{
  "mappings": {
    "properties": {
      "product": { "type": "keyword" },
      "price": { "type": "float" }
    }
  }
}

查询两个索引的字段功能

GET /store-west,store-east/_field_caps?fields=product,price

示例响应

响应提供了可用字段的功能

{
  "indices": [
    "store-east",
    "store-west"
  ],
  "fields": {
    "product": {
      "text": {
        "type": "text",
        "searchable": true,
        "aggregatable": false,
        "indices": [
          "store-west"
        ]
      },
      "keyword": {
        "type": "keyword",
        "searchable": true,
        "aggregatable": true,
        "indices": [
          "store-east"
        ]
      }
    },
    "price": {
      "float": {
        "type": "float",
        "searchable": true,
        "aggregatable": true
      }
    }
  }
}

示例：使用索引过滤器

您可以使用 index_filter 限制考虑的索引。index_filter 根据字段级元数据而非实际文档内容过滤索引。以下请求将索引选择限制为包含映射中包含 product 字段的索引，即使没有文档被索引也是如此

POST /_field_caps?fields=product,price
{
  "index_filter": {
    "term": {
      "product": "notebook"
    }
  }
}

示例响应

响应只包含来自那些包含值是 notebook 的 product 字段的索引的字段。

{
  "indices": [
    "store-east",
    "store-west"
  ],
  "fields": {
    "product": {
      "text": {
        "type": "text",
        "searchable": true,
        "aggregatable": false,
        "indices": [
          "store-west"
        ]
      },
      "keyword": {
        "type": "keyword",
        "searchable": true,
        "aggregatable": true,
        "indices": [
          "store-east"
        ]
      }
    },
    "price": {
      "float": {
        "type": "float",
        "searchable": true,
        "aggregatable": true
      }
    }
  }
}

响应正文字段

下表列出了所有响应正文字段。

字段 数据类型 描述
索引 列表 响应中包含的索引列表。
fields 对象 类型到字段功能的映射，其中每个键是字段名称，其值是一个对象。
fields.<field>.<type>.type 字符串 字段的数据类型（例如，float、text、keyword）。
fields.<field>.<type>.searchable 布尔型 字段是否已索引且可搜索。
fields.<field>.<type>.aggregatable 布尔型 字段是否可用于 sum 或 terms 等聚合。
fields.<field>.<type>.indices 列表 此字段及其对应类型出现的所有索引列表。
fields.<field>.<type>.non_searchable_indices 列表或 null 字段不可搜索的索引列表。null 表示该字段在任何索引中都不可搜索。
fields.<field>.<type>.non_aggregatable_indices 列表或 null 字段不可聚合的索引列表。null 表示该字段在任何索引中都不可聚合。
fields.<field>.<type>.meta 对象 所有映射中合并的元数据值。键是自定义元数据键，值是跨索引的值数组。
剩余 350 字符

有问题？。

想贡献？ 或 。