› › ›

字段功能 API

字段功能 API编辑

允许您检索多个索引中字段的功能。对于数据流，API 会返回流的备份索引中的字段功能。

response = client.field_caps(
  fields: 'rating'
)
puts response

GET /_field_caps?fields=rating

请求编辑

GET /_field_caps?fields=<fields>

POST /_field_caps?fields=<fields>

GET /<target>/_field_caps?fields=<fields>

POST /<target>/_field_caps?fields=<fields>

先决条件编辑

如果启用了 Elasticsearch 安全功能，您必须拥有目标数据流、索引或别名的 view_index_metadata、read 或 manage 索引权限。

描述编辑

字段功能 API 返回有关多个索引中字段功能的信息。

字段功能 API 返回运行时字段，就像任何其他字段一样。例如，类型为 keyword 的运行时字段将像属于 keyword 系列的任何其他字段一样返回。

路径参数编辑

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

查询参数编辑

fields

(必需，字符串) 要检索功能的字段的逗号分隔列表。支持通配符 (*) 表达式。

allow_no_indices

(可选，布尔值) 如果为 false，如果任何通配符表达式、索引别名或 _all 值仅定位缺少的或关闭的索引，则请求将返回错误。即使请求定位其他打开的索引，此行为也适用。例如，如果索引以 foo 开头，但没有索引以 bar 开头，则定位 foo*,bar* 的请求将返回错误。

默认为 true。

expand_wildcards

(可选，字符串) 通配符模式可以匹配的索引类型。如果请求可以定位数据流，则此参数决定通配符表达式是否匹配隐藏的数据流。支持逗号分隔的值，例如 open,hidden。有效值为

all: 匹配任何数据流或索引，包括隐藏的数据流或索引。
open: 匹配打开的、非隐藏的索引。还匹配任何非隐藏的数据流。
closed: 匹配关闭的、非隐藏的索引。还匹配任何非隐藏的数据流。数据流不能关闭。
hidden: 匹配隐藏的数据流和隐藏的索引。必须与 open、closed 或两者结合使用。
none: 不接受通配符模式。

默认为 open。

ignore_unavailable

(可选，布尔值) 如果为 false，如果请求定位缺少的或关闭的索引，则请求将返回错误。默认为 false。

include_unmapped

(可选，布尔值) 如果为 true，则在响应中包含在某个索引中映射但在另一个索引中未映射的字段。没有映射的字段永远不会包含在内。默认为 false。

include_empty_fields

(可选，布尔值) 如果为 false，则在任何分片中从未有过值的字段将不会包含在响应中。非空字段始终包含在内。此标志不考虑删除和更新。如果一个字段是非空的，并且包含该字段的所有文档都被删除或该字段被更新删除，那么即使该标志为 false，它仍然会被返回。默认为 true。

filters

(可选，字符串) 要应用于响应的过滤器的逗号分隔列表。

对 filters 的有效值

+metadata: 仅包含元数据字段
-metadata: 排除元数据字段
-parent: 排除父字段
-nested: 排除嵌套字段
-multifield: 排除多字段

types

(可选，字符串) 要包含的字段类型的逗号分隔列表。任何不匹配这些类型之一的字段都将从结果中排除。默认为空，这意味着将返回所有字段类型。有关字段功能请求和响应中字段类型的更多信息，请参见此处。

请求主体编辑

index_filter: (可选，查询对象允许过滤索引，如果提供的查询在每个分片上重写为 match_none。
runtime_mappings: (可选，对象) 在请求中定义临时运行时字段，类似于在搜索请求中完成的方式。这些字段仅作为查询的一部分存在，并优先于在索引映射中定义的具有相同名称的字段。

响应主体编辑

响应中使用的类型描述了字段类型的系列。通常，类型系列与映射中声明的字段类型相同，但为了简化起见，某些行为相同的字段类型使用类型系列进行描述。例如，keyword、constant_keyword 和 wildcard 字段类型都描述为 keyword 类型系列。

metadata_field: 此字段是否注册为元数据字段。
searchable: 此字段是否在所有索引上被索引以供搜索。
aggregatable: 此字段是否可以在所有索引上进行聚合。
time_series_dimension: 此字段是否在所有索引上用作时间序列维度。对于非时间序列索引，此字段不存在。
time_series_metric: 如果字段在所有索引上用作时间序列指标，则包含指标类型，如果字段不用作指标，则不存在。对于非时间序列索引，此字段不包含在内。
indices: 此字段具有相同类型系列的索引列表，或者如果所有索引对该字段具有相同的类型系列，则为 null。
non_searchable_indices: 此字段不可搜索的索引列表，或者如果所有索引对该字段具有相同的定义，则为 null。
non_aggregatable_indices: 此字段不可聚合的索引列表，或者如果所有索引对该字段具有相同的定义，则为 null。
non_dimension_indices: [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。如果此列表存在于响应中，则某些索引将字段标记为维度，而其他索引（此列表中的索引）则没有。
metric_conflicts_indices: [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。如果这些索引对该字段没有相同的值，则包含此字段存在的索引列表 time_series_metric。
meta: 合并所有索引的元数据，作为字符串键到值数组的映射。值长度为 1 表示所有索引对该键具有相同的值，而长度为 2 或更多表示并非所有索引对该键具有相同的值。

示例编辑

请求可以限制为特定的数据流和索引

response = client.field_caps(
  index: 'my-index-000001',
  fields: 'rating'
)
puts response

GET my-index-000001/_field_caps?fields=rating

下一个示例 API 调用请求有关 rating 和 title 字段的信息

response = client.field_caps(
  fields: 'rating,title'
)
puts response

GET _field_caps?fields=rating,title

API 返回以下响应

{
  "indices": [ "index1", "index2", "index3", "index4", "index5" ],
  "fields": {
    "rating": {                                   
      "long": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false,
        "indices": [ "index1", "index2" ],
        "non_aggregatable_indices": [ "index1" ]  
      },
      "keyword": {
        "metadata_field": false,
        "searchable": false,
        "aggregatable": true,
        "indices": [ "index3", "index4" ],
        "non_searchable_indices": [ "index4" ]    
      }
    },
    "title": {                                    
      "text": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false
      }
    }
  }
}

	字段 `rating` 在 `index1` 和 `index2` 中定义为 long，在 `index3` 和 `index4` 中定义为 `keyword`。
	字段 `rating` 在 `index1` 中不可聚合。
	字段 `rating` 在 `index4` 中不可搜索。
	字段 `title` 在所有索引中定义为 `text`。

默认情况下，未映射的字段会被忽略。您可以在请求中添加名为 include_unmapped 的参数来将它们包含在响应中

response = client.field_caps(
  fields: 'rating,title',
  include_unmapped: true
)
puts response

GET _field_caps?fields=rating,title&include_unmapped

在这种情况下，响应将包含每个在某些索引中存在但在所有索引中不存在的字段的条目

{
  "indices": [ "index1", "index2", "index3" ],
  "fields": {
    "rating": {
      "long": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false,
        "indices": [ "index1", "index2" ],
        "non_aggregatable_indices": [ "index1" ]
      },
      "keyword": {
        "metadata_field": false,
        "searchable": false,
        "aggregatable": true,
        "indices": [ "index3", "index4" ],
        "non_searchable_indices": [ "index4" ]
      },
      "unmapped": {                               
        "metadata_field": false,
        "indices": [ "index5" ],
        "searchable": false,
        "aggregatable": false
      }
    },
    "title": {
      "text": {
        "metadata_field": false,
        "indices": [ "index1", "index2", "index3", "index4" ],
        "searchable": true,
        "aggregatable": false
      },
      "unmapped": {                               
        "metadata_field": false,
        "indices": [ "index5" ],
        "searchable": false,
        "aggregatable": false
      }
    }
  }
}

	字段 `rating` 在 `index5` 中未映射`。
	字段 `title` 在 `index5` 中未映射`。

也可以使用查询来过滤索引

response = client.field_caps(
  index: 'my-index-*',
  fields: 'rating',
  body: {
    index_filter: {
      range: {
        "@timestamp": {
          gte: '2018'
        }
      }
    }
  }
)
puts response

POST my-index-*/_field_caps?fields=rating
{
  "index_filter": {
    "range": {
      "@timestamp": {
        "gte": "2018"
      }
    }
  }
}

在这种情况下，将提供的过滤器重写为 match_none 的索引将在每个分片上从响应中过滤掉。

过滤操作基于尽力而为的原则，它使用索引统计信息和映射将查询重写为 match_none，而不是完全执行请求。例如，对 date 字段的 range 查询可以重写为 match_none，如果分片中的所有文档（包括已删除的文档）都在提供的范围之外。但是，并非所有查询都可以重写为 match_none，因此即使提供的过滤器与任何文档都不匹配，此 API 也可能返回索引。

« 配置文件 API 排名评估 API »