Field capabilities APIedit
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.
GET /_field_caps?fields=rating
Requestedit
GET /_field_caps?fields=<fields>
POST /_field_caps?fields=<fields>
GET /<target>/_field_caps?fields=<fields>
POST /<target>/_field_caps?fields=<fields>
Descriptionedit
The field capabilities API returns the information about the capabilities of fields among multiple indices.
Path parametersedit
-
<target>
-
(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*
.
Query parametersedit
-
fields
-
(Required, string)
Comma-separated list of fields to retrieve capabilities for. Wildcard (
*
) expressions are supported. -
allow_no_indices
-
(Optional, Boolean) If
false
, the request returns an error when a wildcard expression, index alias, or_all
value targets only missing or closed indices.Defaults to
true
. -
expand_wildcards
-
(Optional, string) Controls what kind of indices that wildcard expressions can expand to. Multiple values are accepted when separated by a comma, as in
open,hidden
. Valid values are:-
all
- Expand to open and closed indices, including hidden indices.
-
open
- Expand only to open indices.
-
closed
- Expand only to closed indices.
-
hidden
-
Expansion of wildcards will include hidden indices.
Must be combined with
open
,closed
, or both. -
none
- Wildcard expressions are not accepted.
Defaults to
open
. -
-
ignore_unavailable
-
(Optional, Boolean) If
false
, the request returns an error if it targets a missing or closed index. Defaults tofalse
. -
include_unmapped
-
(Optional, Boolean) If
true
, unmapped fields are included in the response. Defaults tofalse
.
Request bodyedit
-
index_filter
-
(Optional, query object Allows to filter indices if the provided
query rewrites to
match_none
on every shard.
Response bodyedit
The types used in the response describe families of field types.
Normally a type family 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 type family. For example, keyword
, constant_keyword
and wildcard
field types are all described as the keyword
type family.
-
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 type family, or null if all indices have the same type family 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.
Examplesedit
The request can be restricted to specific data streams and indices:
GET my-index-000001/_field_caps?fields=rating
The next example API call requests information about the rating
and the
title
fields:
GET _field_caps?fields=rating,title
The API returns the following response:
{ "indices": [ "index1", "index2", "index3", "index4", "index5" ], "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" ] } }, "title": { "text": { "searchable": true, "aggregatable": false } } } }
The field |
|
The field |
|
The field |
|
The field |
By default unmapped fields are ignored. You can include them in the response by
adding a parameter called include_unmapped
in the request:
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:
{ "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": { "indices": [ "index5" ], "searchable": false, "aggregatable": false } }, "title": { "text": { "indices": [ "index1", "index2", "index3", "index4" ], "searchable": true, "aggregatable": false }, "unmapped": { "indices": [ "index5" ], "searchable": false, "aggregatable": false } } } }
It is also possible to filter indices with a query:
POST my-index-*/_field_caps?fields=rating { "index_filter": { "range": { "@timestamp": { "gte": "2018" } } } }
In which case indices that rewrite the provided filter to match_none
on every shard
will be filtered from the response.
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.