OpenSearch/docs/reference/search/field-caps.asciidoc

[[search-field-caps]]
== Field Capabilities API

The field capabilities API allows to retrieve the capabilities of fields among multiple indices.

The field capabilities API by default executes on all indices:

[source,js]
--------------------------------------------------
GET _field_caps?fields=rating
--------------------------------------------------
// CONSOLE

The request can also be restricted to specific indices:

[source,js]
--------------------------------------------------
GET twitter/_field_caps?fields=rating
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

Supported request options:

[horizontal]
`fields`::  A list of fields to compute stats for. The field name supports wildcard notation. For example, using `text_*`
            will cause all fields that match the expression to be returned.

[float]
=== Field Capabilities

The field capabilities API returns the following information per field:

[horizontal]
`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,
or null if all indices have the same 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.


[float]
=== Response format

Request:

[source,js]
--------------------------------------------------
GET _field_caps?fields=rating,title
--------------------------------------------------
// CONSOLE

[source,js]
--------------------------------------------------
{
    "fields": {
        "indices": ["index1", "index2", "index3", "index4", "index5"],
        "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

            }
        }
    }
}
--------------------------------------------------
// NOTCONSOLE

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

[float]
=== Unmapped fields

By default unmapped fields are ignored. You can include them in the response by
adding a parameter called `include_unmapped` in the request:

[source,js]
--------------------------------------------------
GET _field_caps?fields=rating,title&include_unmapped
--------------------------------------------------
// CONSOLE

In which case the response will contain an entry for each field that is present in
some indices but not all:

[source,js]
--------------------------------------------------
{
    "fields": {
        "indices": ["index1", "index2", "index3"],
        "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
            }
        }
    }
}
--------------------------------------------------
// NOTCONSOLE

<1> The `rating` field is unmapped` in `index5`.
<2> The `title` field is unmapped` in `index5`.