[DOCS] Add examples to the mapping docs (#45520)

Author: jrodewig

docs/reference/indices/put-mapping.asciidoc

@@ -57,12 +57,23 @@ PUT /twitter-1,twitter-2/_mapping <1>
 [float]
 ==== Updating field mappings
 
-In general, the mapping for existing fields cannot be updated.  There are some
-exceptions to this rule. For instance:
+// tag::put-field-mapping-exceptions[]
 
-* new <<properties>> can be added to <<object>> fields.
-* new <<multi-fields,multi-fields>> can be added to existing fields.
-* the <<ignore-above>> parameter can be updated.
+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.
+
+// end::put-field-mapping-exceptions[]
 
 For example:
 

docs/reference/mapping.asciidoc

@@ -118,49 +118,151 @@ You know more about your data than Elasticsearch can guess, so while dynamic
 mapping can be useful to get started, at some point you will want to specify
 your own explicit mappings.
 
-You can create field mappings when you
-<<indices-create-index,create an index>>, and you can add
-fields to an existing index with the <<indices-put-mapping,PUT mapping API>>.
+You can create field mappings when you <<create-mapping,create an index>> and
+<<add-field-mapping,add fields to an existing index>>.
 
 [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
+
+include::{docdir}/indices/put-mapping.asciidoc[tag=put-field-mapping-exceptions]
+
+[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
 
 --