[[indices-get-field-mapping]]
== Get Field Mapping

The get field mapping API allows you to retrieve mapping definitions for one or more fields.
This is useful when you do not need the complete type mapping returned by
the <<indices-get-mapping>> API.

The following returns the mapping of the field `text` only:

[source,js]
--------------------------------------------------
curl -XGET 'http://localhost:9200/twitter/tweet/_mapping/field/text'
--------------------------------------------------

For which the response is (assuming `text` is a default string field):

[source,js]
--------------------------------------------------
{
   "twitter": {
      "tweet": {
         "text": {
            "full_name": "text",
            "mapping": {
               "text": { "type": "string" }
            }
         }
      }
   }
}
--------------------------------------------------



[float]
=== Multiple Indices, Types and Fields

The get field mapping API can be used to get the mapping of multiple fields from more than one index or type
with a single call. General usage of the API follows the
following syntax: `host:port/{index}/{type}/_mapping/field/{field}` where
`{index}`, `{type}` and `{field}` can stand for comma-separated list of names. To
get mappings for all indices you can use `_all` for `{index}`. The
following are some examples:

[source,js]
--------------------------------------------------
curl -XGET 'http://localhost:9200/twitter,kimchy/_mapping/field/message'

curl -XGET 'http://localhost:9200/_all/tweet,book/_mapping/field/message,user.id'
--------------------------------------------------

[float]
=== Specifying fields

The get mapping api allows you to specify fields using any of the following:

[horizontal]
Full names:: the full path, including any parent object name the field is
   part of (ex. `user.id`).
Index names:: the name of the lucene field (can be different than the
   field name if the `index_name` option of the mapping is used).
Field names:: the name of the field without the path to it (ex. `id` for `{ "user" : { "id" : 1 } }`).

The above options are specified in the order the `field` parameter is resolved.
The first field found which matches is returned. This is especially important
if index names or field names are used as those can be ambiguous.

For example, consider the following mapping:

[source,js]
--------------------------------------------------
 {
     "article": {
         "properties": {
             "id": { "type": "string" },
             "title":  { "type": "string", "index_name": "text" },
             "abstract": { "type": "string", "index_name": "text" },
             "author": {
                 "properties": {
                     "id": { "type": "string" },
                     "name": { "type": "string", "index_name": "author" }
                 }
             }
         }
     }
 }
--------------------------------------------------

To select the `id` of the `author` field, you can use its full name `author.id`. Using `text` will return
the mapping of `abstract` as it is one of the fields which map to the Lucene field `text`. `name` will return
the field `author.name`:

[source,js]
--------------------------------------------------
curl -XGET "http://localhost:9200/publications/article/_mapping/field/author.id,text,name"
--------------------------------------------------

returns:

[source,js]
--------------------------------------------------
{
   "publications": {
      "article": {
         "text": {
            "full_name": "abstract",
            "mapping": {
               "abstract": { "type": "string", "index_name": "text" }
            }
         },
         "author.id": {
            "full_name": "author.id",
            "mapping": {
               "id": { "type": "string" }
            }
         },
         "name": {
            "full_name": "author.name",
            "mapping": {
               "name": { "type": "string", "index_name": "author" }
            }
         }
      }
   }
}
--------------------------------------------------

Note how the response always use the same fields specified in the request as keys.
The `full_name` in every entry contains the full name of the field whose mapping were returned.
This is useful when the request can refer to to multiple fields (like `text` above).

[float]
=== Other options

[horizontal]
include_defaults:: adding `include_defaults=true` to the query string will cause the response to
include default values, which are normally suppressed.