Get the field capabilities | Elasticsearch API documentation

Get the field capabilitiesAdded in 5.4.0

GET /{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.

Path parameters

indexstring | 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_indicesboolean
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_wildcardsstring | 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.
fieldsstring | array[string]
A comma-separated list of fields to retrieve capabilities for. Wildcard (*) expressions are supported.
ignore_unavailableboolean
If true, missing or closed indices are not included in the response.
include_unmappedboolean
If true, unmapped fields are included in the response.
filtersstring
A comma-separated list of filters to apply to the response.
typesarray[string]
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_fieldsboolean
If false, empty fields are not included in the response.

application/json

Body

fieldsstring | array[string]
index_filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
runtime_mappingsobject
Hide runtime_mappings attribute Show runtime_mappings attribute object
- *object Additional properties
  Hide * attributes Show * attributes object
  fieldsobject
  For type composite
  Hide fields attribute Show fields attribute object
  *object Additional properties
  Hide * attribute Show * attribute object
  typestring Required
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  fetch_fieldsarray[object]
  For type lookup
  Hide fetch_fields attributes Show fetch_fields attributes object
  fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  formatstring
  formatstring
  A custom format for date type runtime fields.
  input_fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  target_fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  target_indexstring
  scriptobject
  Hide script attributes Show script attributes object
  sourcestring | object
  One of:
  ScriptSourcestring SearchRequestBodyobject
  Hide attributes Show attributes
  aggregationsobject
  Defines the aggregations that are run as part of the search request.
  External documentation
  collapseobject
  External documentation
  explainboolean
  If true, the request returns detailed information about score computation as part of a hit.
  extobject
  Configuration of search extensions defined by Elasticsearch plugins.
  Hide ext attribute Show ext attribute object
  *object Additional properties
  fromnumber
  The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
  highlightobject
  track_total_hitsboolean | number
  Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
  indices_boostarray[object]
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  External documentation
  docvalue_fieldsarray[object]
  An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
  External documentation
  knnobject | array[object]
  The approximate kNN search to run.
  One of:
  KnnSearchobject array-2array[object]
  rankobject
  Hide rank attribute Show rank attribute object
  rrf
  min_scorenumber
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  post_filterobject
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  External documentation
  profileboolean
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  queryobject
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  External documentation
  rescorearray[object]
  retrieverobject
  Hide retriever attributes Show retriever attributes object
  standard
  knn
  rrf
  text_similarity_reranker
  rule
  script_fieldsobject
  Retrieve a script evaluation (based on different fields) for each hit.
  Hide script_fields attribute Show script_fields attribute object
  *object Additional properties
  search_afterarray[number | string | boolean | null]
  A field value.
  sizenumber
  The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
  sliceobject
  Hide slice attributes Show slice attributes object
  fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  idstring Required
  maxnumber Required
  sortarray[string | object]
  _sourceboolean | object
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  One of:
  SourceConfigboolean SourceFilterobject
  fieldsarray[object]
  An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
  suggestobject
  Hide suggest attribute Show suggest attribute object
  textstring
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  terminate_afternumber
  The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
  IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  If set to 0 (default), the query does not terminate early.
  timeoutstring
  The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
  track_scoresboolean
  If true, calculate and return document scores, even if the scores are not used for sorting.
  versionboolean
  If true, the request returns the document version as part of a hit.
  seq_no_primary_termboolean
  If true, the request returns sequence number and primary term of the last modification of each hit.
  External documentation
  stored_fieldsstring | array[string]
  pitobject
  Hide pit attributes Show pit attributes object
  idstring Required
  keep_alivestring
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  runtime_mappingsobject
  statsarray[string]
  The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
  idstring
  paramsobject
  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
  langstring
  Any of:
  ScriptLanguagestring ScriptLanguagestring
  Values are painless, expression, mustache, or java.
  optionsobject
  Hide options attribute Show options attribute object
  *string Additional properties
  typestring Required
  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
- indicesstring | array[string] Required
- fieldsobject Required
  Hide fields attribute Show fields attribute object
  *object Additional properties
  Hide * attribute Show * attribute object
  *object Additional properties
  Hide * attributes Show * attributes object
  aggregatableboolean Required
  Whether this field can be aggregated on all indices.
  indicesstring | array[string]
  metaobject
  Hide meta attribute Show meta attribute object
  *object Additional properties
  non_aggregatable_indicesstring | array[string]
  non_searchable_indicesstring | array[string]
  searchableboolean Required
  Whether this field is indexed for search on all indices.
  typestring Required
  metadata_fieldboolean
  Whether this field is registered as a metadata field.
  time_series_dimensionboolean Technical preview
  Whether this field is used as a time series dimension.
  time_series_metricstring
  Values are gauge, counter, summary, histogram, or position.
  non_dimension_indicesarray[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_indicesarray[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.

GET /{index}/_field_caps

curl \
 --request GET 'http://api.example.com/{index}/_field_caps' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"index_filter\": {\n    \"range\": {\n      \"@timestamp\": {\n        \"gte\": \"2018\"\n      }\n    }\n  }\n}"'

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

Get the field capabilitiesAdded in 5.4.0

Path parameters

Query parameters

Body

sourcestring | object

langstring

Responses