[[search-field-caps]] === Field Capabilities API Allows you to retrieve the capabilities of fields among multiple indices. For data streams, the API returns field capabilities among the stream's backing indices. [source,console] -------------------------------------------------- GET /_field_caps?fields=rating -------------------------------------------------- [[search-field-caps-api-request]] ==== {api-request-title} `GET /_field_caps` `POST /_field_caps` `GET //_field_caps` `POST //_field_caps` [[search-field-caps-api-desc]] ==== {api-description-title} The field capabilities API returns the information about the capabilities of fields among multiple indices. [[search-field-caps-api-path-params]] ==== {api-path-parms-title} ``:: (Optional, string) Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (`*`) are supported. + To target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`. [[search-field-caps-api-query-params]] ==== {api-query-parms-title} include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] + Defaults to `true`. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] + -- Defaults to `open`. -- include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=fields] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] `include_unmapped`:: (Optional, boolean) If `true`, unmapped fields are included in the response. Defaults to `false`. [[search-field-caps-api-request-body]] ==== {api-request-body-title} `index_filter`:: (Optional, <> Allows to filter indices if the provided query rewrites to `match_none` on every shard. [[search-field-caps-api-response-body]] ==== {api-response-body-title} The types used in the response describe _families_ of field types. Normally a family type is the same as the field type declared in the mapping, but to simplify matters certain field types that behave identically are described using a family type. For example, `keyword`, `constant_keyword` and `wildcard` field types are all described as the `keyword` family type. `searchable`:: Whether this field is indexed for search on all indices. `aggregatable`:: Whether this field can be aggregated on all indices. `indices`:: The list of indices where this field has the same family type, or null if all indices have the same family type for the field. `non_searchable_indices`:: The list of indices where this field is not searchable, or null if all indices have the same definition for the field. `non_aggregatable_indices`:: The list of indices where this field is not aggregatable, or null if all indices have the same definition for the field. `meta`:: Merged metadata across all indices as a map of string keys to arrays of values. A value length of 1 indicates that all indices had the same value for this key, while a length of 2 or more indicates that not all indices had the same value for this key. [[search-field-caps-api-example]] ==== {api-examples-title} The request can be restricted to specific data streams and indices: [source,console] -------------------------------------------------- GET twitter/_field_caps?fields=rating -------------------------------------------------- // TEST[setup:twitter] The next example API call requests information about the `rating` and the `title` fields: [source,console] -------------------------------------------------- GET _field_caps?fields=rating,title -------------------------------------------------- The API returns the following response: [source,console-result] -------------------------------------------------- { "indices": ["index1", "index2", "index3", "index4", "index5"], "fields": { "rating": { <1> "long": { "searchable": true, "aggregatable": false, "indices": ["index1", "index2"], "non_aggregatable_indices": ["index1"] <2> }, "keyword": { "searchable": false, "aggregatable": true, "indices": ["index3", "index4"], "non_searchable_indices": ["index4"] <3> } }, "title": { <4> "text": { "searchable": true, "aggregatable": false } } } } -------------------------------------------------- // TESTRESPONSE[skip:historically skipped] <1> The field `rating` is defined as a long in `index1` and `index2` and as a `keyword` in `index3` and `index4`. <2> The field `rating` is not aggregatable in `index1`. <3> The field `rating` is not searchable in `index4`. <4> The field `title` is defined as `text` in all indices. By default unmapped fields are ignored. You can include them in the response by adding a parameter called `include_unmapped` in the request: [source,console] -------------------------------------------------- GET _field_caps?fields=rating,title&include_unmapped -------------------------------------------------- In which case the response will contain an entry for each field that is present in some indices but not all: [source,console-result] -------------------------------------------------- { "indices": ["index1", "index2", "index3"], "fields": { "rating": { "long": { "searchable": true, "aggregatable": false, "indices": ["index1", "index2"], "non_aggregatable_indices": ["index1"] }, "keyword": { "searchable": false, "aggregatable": true, "indices": ["index3", "index4"], "non_searchable_indices": ["index4"] }, "unmapped": { <1> "indices": ["index5"], "searchable": false, "aggregatable": false } }, "title": { "text": { "indices": ["index1", "index2", "index3", "index4"], "searchable": true, "aggregatable": false }, "unmapped": { <2> "indices": ["index5"] "searchable": false, "aggregatable": false } } } } -------------------------------------------------- // TESTRESPONSE[skip:historically skipped] <1> The `rating` field is unmapped` in `index5`. <2> The `title` field is unmapped` in `index5`. It is also possible to filter indices with a query: [source,console] -------------------------------------------------- POST twitter*/_field_caps?fields=rating { "index_filter": { "range": { "@timestamp": { "gte": "2018" } } } } -------------------------------------------------- // TEST[setup:twitter] In which case indices that rewrite the provided filter to `match_none` on every shard will be filtered from the response. -- [IMPORTANT] ==== The filtering is done on a best-effort basis, it uses index statistics and mappings to rewrite queries to `match_none` instead of fully executing the request. For instance a `range` query over a `date` field can rewrite to `match_none` if all documents within a shard (including deleted documents) are outside of the provided range. However, not all queries can rewrite to `match_none` so this API may return an index even if the provided filter matches no document. ==== --