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.

GET /_field_caps?fields=rating

Request

GET /_field_caps?fields=<fields>

POST /_field_caps?fields=<fields>

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

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

Description

The field capabilities API returns the information about the capabilities of fields among multiple indices.

Path parameters

<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 parameters

fields

(Required, string) Comma-separated list of fields to retrieve capabilities for. Wildcard (*) expressions are supported.

allow_no_indices

(Optional, boolean) If true, the request does not return an error if a wildcard expression or _all value retrieves only missing or closed indices.

This parameter also applies to index aliases that point to a missing or closed index.

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 true, missing or closed indices are not included in the response. Defaults to false.

include_unmapped

(Optional, boolean) If true, unmapped fields are included in the response. Defaults to false.

Request body

index_filter

(Optional, query object Allows to filter indices if the provided query rewrites to match_none on every shard.

Response body

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.

Examples

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
      }
    }
  }
}

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.