› › ›

字段能力 API

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

resp = client.field_caps(
    fields="rating",
)
print(resp)

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

const response = await client.fieldCaps({
  fields: "rating",
});
console.log(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 或更大的长度表示并非所有索引对此键具有相同的值。

示例

编辑

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

resp = client.field_caps(
    index="my-index-000001",
    fields="rating",
)
print(resp)

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

const response = await client.fieldCaps({
  index: "my-index-000001",
  fields: "rating",
});
console.log(response);

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

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

resp = client.field_caps(
    fields="rating,title",
)
print(resp)

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

const response = await client.fieldCaps({
  fields: "rating,title",
});
console.log(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 的参数，将其包含在响应中

resp = client.field_caps(
    fields="rating,title",
    include_unmapped=True,
)
print(resp)

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

const response = await client.fieldCaps({
  fields: "rating,title",
  include_unmapped: "true",
});
console.log(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` 中未映射。

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

resp = client.field_caps(
    index="my-index-*",
    fields="rating",
    index_filter={
        "range": {
            "@timestamp": {
                "gte": "2018"
            }
        }
    },
)
print(resp)

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

const response = await client.fieldCaps({
  index: "my-index-*",
  fields: "rating",
  index_filter: {
    range: {
      "@timestamp": {
        gte: "2018",
      },
    },
  },
});
console.log(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 也可能返回索引。

« Profile API 排名评估 API »