1 files changed, 140 insertions, 0 deletions
diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc
new file mode 100644
index 0000000..0633744
--- /dev/null
+++ b/docs/reference/indices/get-field-mapping.asciidoc
@@ -0,0 +1,140 @@
+[[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 or wild cards. 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'
+
+curl -XGET 'http://localhost:9200/_all/tw*/_mapping/field/*.id'
+--------------------------------------------------
+
+[float]
+=== Specifying fields
+
+The get mapping api allows you to specify one or more fields separated with by a comma.
+You can also use wildcards. The field names can be 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.