elasticsearch/docs/reference/indices/get-field-mapping.asciidoc

[[indices-get-field-mapping]]
=== Get field mapping API
++++
<titleabbrev>Get field mapping</titleabbrev>
++++

Retrieves <<mapping,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 <<indices-get-mapping,complete mapping>>
or if an index mapping contains a large number of fields.

[source,console]
----
GET /my-index-000001/_mapping/field/user
----
// TEST[setup:my_index]


[[get-field-mapping-api-request]]
==== {api-request-title}

`GET /_mapping/field/<field>`

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

[[get-field-mapping-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the
`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
for the target data stream, index, or alias.

[[get-field-mapping-api-path-params]]
==== {api-path-parms-title}

`<target>`::
(Optional, string) 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`.

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


[[get-field-mapping-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `true`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

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


[[get-field-mapping-api-example]]
==== {api-examples-title}

[[get-field-mapping-api-basic-ex]]
===== Example with index setup

You can provide field mappings when creating a new index. The following
<<indices-create-index, create index>> API request creates the `publications`
index with several field mappings.

[source,console]
--------------------------------------------------
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:

[source,console]
--------------------------------------------------
GET publications/_mapping/field/title
--------------------------------------------------
// TEST[continued]

The API returns the following response:

[source,console-result]
--------------------------------------------------
{
   "publications": {
      "mappings": {
          "title": {
             "full_name": "title",
             "mapping": {
                "title": {
                   "type": "text"
                }
             }
          }
       }
   }
}
--------------------------------------------------

[[get-field-mapping-api-specific-fields-ex]]
===== Specifying fields

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

[source,console]
--------------------------------------------------
GET publications/_mapping/field/author.id,abstract,name
--------------------------------------------------
// TEST[continued]

returns:

[source,console-result]
--------------------------------------------------
{
   "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.

[source,console]
--------------------------------------------------
GET publications/_mapping/field/a*
--------------------------------------------------
// TEST[continued]

returns:

[source,console-result]
--------------------------------------------------
{
   "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"
               }
            }
         }
      }
   }
}
--------------------------------------------------

[[get-field-mapping-api-multi-index-ex]]
===== Multiple targets and fields

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

[source,console]
----
GET /my-index-000001,my-index-000002/_mapping/field/message
----
// TEST[setup:my_index]
// TEST[s/^/PUT my-index-000002\n/]

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

[source,console]
----
GET /_all/_mapping/field/message
----
// TEST[setup:my_index]

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

[source,console]
----
GET /_all/_mapping/field/*.id
----
// TEST[setup:my_index]