IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Get component template API Get index API »

› › ›

Get field mapping API

edit

Get field mapping API

edit

Retrieves mapping definitions for one or more fields. For data streams, the API retrieves field mappings for the stream’s backing indices.

This API is useful if you don’t need a complete mapping or if an index mapping contains a large number of fields.

GET /my-index-000001/_mapping/field/user

Request

edit

GET /_mapping/field/<field>

GET /<target>/_mapping/field/<field>

Prerequisites

edit

If the Elasticsearch security features are enabled, you must have the view_index_metadata or manage index privilege for the target data stream, index, or index alias.

Path parameters

edit

<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 indices in a cluster, omit this parameter or use _all or *.

<field>

(Optional, string) Comma-separated list or wildcard expression of fields used to limit returned information.

Query parameters

edit

allow_no_indices

(Optional, 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.

Defaults to true.

expand_wildcards

(Optional, string) Type of index that wildcard expressions 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. Valid values are:

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.

include_type_name

[7.0.0] Deprecated in 7.0.0. Mapping types have been deprecated. See Removal of mapping types. (Optional, boolean) If true, a mapping type is expected in the body of mappings. Defaults to false.

ignore_unavailable

(Optional, Boolean) If false, the request returns an error if it targets a missing or closed index. Defaults to false.

include_defaults

(Optional, Boolean) If true, the response includes default mapping values. Defaults to false.

local

[7.8.0] Deprecated in 7.8.0. This parameter is a no-op and field mappings are always retrieved locally (Optional, boolean) If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.

Examples

edit

Example with index setup

edit

You can provide field mappings when creating a new index. The following create index API request creates the publications index with several field mappings.

PUT /publications
{
  "mappings": {
    "properties": {
      "id": { "type": "text" },
      "title": { "type": "text" },
      "abstract": { "type": "text" },
      "author": {
        "properties": {
          "id": { "type": "text" },
          "name": { "type": "text" }
        }
      }
    }
  }
}

The following returns the mapping of the field title only:

GET publications/_mapping/field/title

The API returns the following response:

{
   "publications": {
      "mappings": {
          "title": {
             "full_name": "title",
             "mapping": {
                "title": {
                   "type": "text"
                }
             }
          }
       }
   }
}

Specifying fields

edit

The get mapping API allows you to specify a comma-separated list of fields.

For instance to select the id of the author field, you must use its full name author.id.

GET publications/_mapping/field/author.id,abstract,name

returns:

{
   "publications": {
      "mappings": {
        "author.id": {
           "full_name": "author.id",
           "mapping": {
              "id": {
                 "type": "text"
              }
           }
        },
        "abstract": {
           "full_name": "abstract",
           "mapping": {
              "abstract": {
                 "type": "text"
              }
           }
        }
     }
   }
}

The get field mapping API also supports wildcard notation.

GET publications/_mapping/field/a*

returns:

{
   "publications": {
      "mappings": {
         "author.name": {
            "full_name": "author.name",
            "mapping": {
               "name": {
                 "type": "text"
               }
            }
         },
         "abstract": {
            "full_name": "abstract",
            "mapping": {
               "abstract": {
                  "type": "text"
               }
            }
         },
         "author.id": {
            "full_name": "author.id",
            "mapping": {
               "id": {
                  "type": "text"
               }
            }
         }
      }
   }
}

Multiple targets and fields

edit

The get field mapping API can be used to get mappings for multiple fields from multiple data streams or indices with a single request.

The <target> and <field> request path parameters both support comma-separated lists and wildcard expressions.

You can omit the <target> parameter or use a value of * or _all to target all data streams and indices in a cluster.

Similarly, you can omit the <field> parameter or use a value of * to retrieve mappings for all fields in the targeted data streams or indices. However, the <field> parameter does not support the _all value.

For example, the following request retrieves mappings for the message field in any data stream or index named my-index-000001 or my-index-000002.

GET /my-index-000001,my-index-000002/_mapping/field/message

The following request retrieves mappings for the message and user.id fields in any data stream or index in the cluster.

GET /_all/_mapping/field/message

The following request retrieves mappings for fields with an id property in any data stream or index in the cluster.

GET /_all/_mapping/field/*.id

« Get component template API Get index API »