[DOCS] Add examples to the mapping docs

docs/reference/mapping.asciidoc

@@ -123,44 +123,159 @@ You can create field mappings when you
 fields to an existing index with the <<indices-put-mapping,PUT mapping API>>.
 
 [float]
-== Updating existing field mappings
+[[create-mapping]]
+== Create an index with an explicit mapping
 
-Other than where documented, *existing field mappings cannot be
-updated*. Changing the mapping would mean invalidating already indexed
-documents. Instead, you should create a new index with the correct mappings
-and <<docs-reindex,reindex>> your data into that index. If you only wish
-to rename a field and not change its mappings, it may make sense to introduce
-an <<alias, `alias`>> field.
+You can use the <<indices-create-index,create index>> API to create a new index
+with an explicit mapping.
+
+[source,js]
+----
+PUT my-index
+{
+  "mappings": {
+    "properties": {
+      "age":    { "type": "integer" },  <1>
+      "email":  { "type": "keyword"  }, <2>
+      "name":   { "type": "text"  }     <3>
+    }
+  }
+}
+----
+// CONSOLE
+
+<1> Creates `age`, an <<number,`integer`>> field
+<2> Creates `email`, a <<keyword,`keyword`>> field
+<3> Creates `name`, a <<text,`text`>> field
 
 [float]
-== Example mapping
+[[add-field-mapping]]
+== Add a field to an existing mapping
 
-A mapping can be specified when creating an index, as follows:
+You can use the <<indices-put-mapping, put mapping>> API to add one or more new
+fields to an existing index.
+
+The following example adds `employee-id`, a `keyword` field with an
+<<mapping-index,`index`>> mapping parameter value of `false`. This means values
+for the `employee-id` field are stored but not indexed or available for search.
 
 [source,js]
----------------------------------------
-PUT my_index <1>
+----
+PUT /my-index/_mapping
 {
-  "mappings": {
-    "properties": { <2>
-      "title":    { "type": "text"  }, <3>
-      "name":     { "type": "text"  }, <4>
-      "age":      { "type": "integer" },  <5>
-      "created":  {
-        "type":   "date", <6>
-        "format": "strict_date_optional_time||epoch_millis"
+  "properties": {
+    "employee-id": {
+      "type": "keyword",
+      "index": false
+    }
+  }
+}
+----
+// CONSOLE
+// TEST[continued]
+
+[float]
+[[update-mapping]]
+== Update the mapping of a field
+
+You can't change the mapping of an existing field, with the following
+exceptions:
+
+* You can add new <<properties,properties>> to an <<object,`object`>> field.
+* You can use the <<multi-fields,`field`>> mapping parameter to enable
+multi-fields.
+* You can change the value of the <<ignore-above,`ignore_above`>> mapping
+parameter.
+
+Changing the mapping of an existing field could invalidate data that's already
+indexed. If you need to change the mapping of a field, create a new index with
+the correct mappings and <<docs-reindex,reindex>> your data into that index. If
+you only want to rename a field, consider adding an <<alias, `alias`>> field.
+
+[float]
+[[view-mapping]]
+== View the mapping of an index
+
+You can use the <<indices-get-mapping, get mapping>> API to view the mapping of
+an existing index.
+
+[source,js]
+----
+GET /my-index/_mapping
+----
+// CONSOLE
+// TEST[continued]
+
+The API returns the following response:
+
+[source,js]
+----
+{
+  "my-index" : {
+    "mappings" : {
+      "properties" : {
+        "age" : {
+          "type" : "integer"
+        },
+        "email" : {
+          "type" : "keyword"
+        },
+        "employee-id" : {
+          "type" : "keyword",
+          "index" : false
+        },
+        "name" : {
+          "type" : "text"
+        }
       }
     }
   }
 }
----------------------------------------
+----
+// TESTRESPONSE
+
+
+[float]
+[[view-field-mapping]]
+== View the mapping of specific fields
+
+If you only want to view the mapping of one or more specific fields, you can use
+the <<indices-get-field-mapping, get field mapping>> API.
+
+This is useful if you don't need the complete mapping of an index or your index
+contains a large number of fields.
+
+The following request retrieves the mapping for the `employee-id` field.
+
+[source,js]
+----
+GET /my-index/_mapping/field/employee-id
+----
 // CONSOLE
-<1> Create an index called `my_index`.
-<2> Specify the fields or _properties_ in the mapping.
-<3> Specify that the `title` field contains `text` values.
-<4> Specify that the `name` field contains `text` values.
-<5> Specify that the `age` field contains `integer` values.
-<6> Specify that the `created` field contains `date` values in two possible formats.
+// TEST[continued]
+
+The API returns the following response:
+
+[source,js]
+----
+{
+  "my-index" : {
+    "mappings" : {
+      "employee-id" : {
+        "full_name" : "employee-id",
+        "mapping" : {
+          "employee-id" : {
+            "type" : "keyword",
+            "index" : false
+          }
+        }
+      }
+    }
+  }
+}
+
+----
+// TESTRESPONSE
 
 --