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

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
+// tag::put-field-mapping-exceptions[]
-exceptions to this rule. For instance:
 
-* new <<properties>> can be added to <<object>> fields.
+You can't change the mapping of an existing field, with the following
-* new <<multi-fields,multi-fields>> can be added to existing fields.
+exceptions:
-* the <<ignore-above>> parameter can be updated.
+
+* 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
+You can create field mappings when you <<create-mapping,create an index>> and
-<<indices-create-index,create an index>>, and you can add
+<<add-field-mapping,add fields to an existing index>>.
-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
+You can use the <<indices-create-index,create index>> API to create a new index
-updated*. Changing the mapping would mean invalidating already indexed
+with an explicit mapping.
-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.
-
-[float]
-== Example mapping
-
-A mapping can be specified when creating an index, as follows:
 
 [source,js]
----------------------------------------
+----
-PUT my_index <1>
+PUT /my-index
 {
   "mappings": {
-    "properties": { <2>
+    "properties": {
-      "title":    { "type": "text"  }, <3>
+      "age":    { "type": "integer" },  <1>
-      "name":     { "type": "text"  }, <4>
+      "email":  { "type": "keyword"  }, <2>
-      "age":      { "type": "integer" },  <5>
+      "name":   { "type": "text"  }     <3>
-      "created":  {
+    }
-        "type":   "date", <6>
+  }
-        "format": "strict_date_optional_time||epoch_millis"
+}
+----
+// CONSOLE
+
+<1> Creates `age`, an <<number,`integer`>> field
+<2> Creates `email`, a <<keyword,`keyword`>> field
+<3> Creates `name`, a <<text,`text`>> field
+
+[float]
+[[add-field-mapping]]
+== Add a field to an existing mapping
+
+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/_mapping
+{
+  "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`.
+// TEST[continued]
-<2> Specify the fields or _properties_ in the mapping.
+
-<3> Specify that the `title` field contains `text` values.
+The API returns the following response:
-<4> Specify that the `name` field contains `text` values.
+
-<5> Specify that the `age` field contains `integer` values.
+[source,js]
-<6> Specify that the `created` field contains `date` values in two possible formats.
+----
+{
+  "my-index" : {
+    "mappings" : {
+      "employee-id" : {
+        "full_name" : "employee-id",
+        "mapping" : {
+          "employee-id" : {
+            "type" : "keyword",
+            "index" : false
+          }
+        }
+      }
+    }
+  }
+}
+
+----
+// TESTRESPONSE
 
 --