Get the field capabilities | Elasticsearch Serverless API documentation

Get the field capabilities Generally available

POST /{index}/_field_caps

Api key auth

All methods and paths for this operation:

GET /_field_caps

POST /_field_caps

GET /{index}/_field_caps

POST /{index}/_field_caps

Get information about the capabilities of fields among multiple indices.

For data streams, the API returns field capabilities among the stream’s backing indices. It returns runtime fields like any other field. For example, a runtime field with a type of keyword is returned the same as any other field that belongs to the keyword family.

Required authorization

Index privileges: view_index_metadata,read

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
expand_wildcards string | array[string]
The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
Values are all, open, closed, hidden, or none.
fields string | array[string]

A comma-separated list of fields to retrieve capabilities for. Wildcard (*) expressions are supported.
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
include_unmapped boolean

If true, unmapped fields are included in the response.
filters string Generally available

A comma-separated list of filters to apply to the response.
types array[string] Generally available

A comma-separated list of field types to include. Any fields that do not match one of these types will be excluded from the results. It defaults to empty, meaning that all field types are returned.
include_empty_fields boolean Generally available

If false, empty fields are not included in the response.

application/json

Body

fields string | array[string]

A list of fields to retrieve capabilities for. Wildcard (*) expressions are supported.
index_filter object

Filter indices if the provided query rewrites to match_none on every shard.

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

External documentation
runtime_mappings object

Define ad-hoc runtime fields in the request similar to the way it is done in search requests. These fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings.
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  For type lookup
  
  target_field string
  
  For type lookup
  
  target_index string
  
  For type lookup
  
  script object
  
  Painless script executed at query time.
  
  Hide script attributes Show script attributes object
  
  source
  
  id string
  
  The id for a stored script.
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Field type, which can be: boolean, composite, date, double, geo_point, ip,keyword, long, or lookup.
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

Responses

200 application/json
Hide response attributes Show response attributes object
- indices string | array[string] Required
  
  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.
- fields object Required
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  aggregatable boolean Required
  
  Whether this field can be aggregated on all indices.
  
  indices string | array[string]
  
  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.
  
  meta object
  
  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.
  
  Hide meta attribute Show meta attribute object
  
  * object Additional properties
  
  non_aggregatable_indices string | array[string]
  
  The list of indices where this field is not aggregatable, or null if all indices have the same definition for the field.
  
  non_searchable_indices string | array[string]
  
  The list of indices where this field is not searchable, or null if all indices have the same definition for the field.
  
  searchable boolean Required
  
  Whether this field is indexed for search on all indices.
  
  type string Required
  
  metadata_field boolean
  
  Whether this field is registered as a metadata field.
  
  time_series_dimension boolean Technical preview
  
  Whether this field is used as a time series dimension.
  
  time_series_metric string
  
  Contains metric type if this fields is used as a time series metrics, absent if the field is not used as metric.
  
  Values are gauge, counter, summary, histogram, or position.
  
  non_dimension_indices array[string] Technical preview
  
  If this list is present in response then some indices have the field marked as a dimension and other indices, the ones in this list, do not.
  
  metric_conflicts_indices array[string] Technical preview
  
  The list of indices where this field is present if these indices don’t have the same time_series_metric value for this field.

POST /{index}/_field_caps

POST my-index-*/_field_caps?fields=rating
{
  "index_filter": {
    "range": {
      "@timestamp": {
        "gte": "2018"
      }
    }
  }
}

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

const response = await client.fieldCaps({
  index: "my-index-*",
  fields: "rating",
  index_filter: {
    range: {
      "@timestamp": {
        gte: "2018",
      },
    },
  },
});

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

$resp = $client->fieldCaps([
    "index" => "my-index-*",
    "fields" => "rating",
    "body" => [
        "index_filter" => [
            "range" => [
                "@timestamp" => [
                    "gte" => "2018",
                ],
            ],
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index_filter":{"range":{"@timestamp":{"gte":"2018"}}}}' "$ELASTICSEARCH_URL/my-index-*/_field_caps?fields=rating"

Request example

Run `POST my-index-*/_field_caps?fields=rating` to get field capabilities and filter indices with a query. Indices that rewrite the provided filter to `match_none` on every shard will be filtered from the response.

{
  "index_filter": {
    "range": {
      "@timestamp": {
        "gte": "2018"
      }
    }
  }
}

Response examples (200)

A successful response from `GET _field_caps?fields=rating,title`. The field `rating` is defined as a long in `index1` and `index2` and as a `keyword` in `index3` and `index4`. The field `rating` is not aggregatable in `index1`. The field `rating` is not searchable in `index4`. The field `title` is defined as text in all indices.

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

A successful response from `GET _field_caps?fields=rating,title&include_unmapped`. The response contains an entry for each field that is present in some indices but not all. For example, the `rating` and `title` fields are unmapped in `index5`.

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