[DOCS] Expand put mapping API docs examples (#47462)

docs/reference/indices/put-mapping.asciidoc

@@ -131,32 +131,24 @@ PUT /twitter-1,twitter-2/_mapping <1>
 
 <1> Note that the indices specified (`twitter-1,twitter-2`) follows <<multi-index,multiple index names>> and wildcard format.
 
-[[updating-field-mappings]]
-===== Update an existing field
-
-// tag::put-field-mapping-exceptions[]
-
-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.
+[[add-new-field-to-object]]
+===== Add new properties to an existing object field
 
-// end::put-field-mapping-exceptions[]
+You can use the put mapping API
+to add new properties
+to an existing <<object,`object`>> field.
+To see how this works,
+try the following example.
 
-For example:
+Use the <<indices-create-index,create index>> API
+to create an index
+with the `name` object field
+and an inner `first` text field.
 
 [source,console]
------------------------------------
-PUT /my_index <1>
+----
+PUT /my_index
 {
   "mappings": {
     "properties": {
@@ -166,35 +158,426 @@ PUT /my_index <1>
             "type": "text"
           }
         }
-      },
-      "user_id": {
-        "type": "keyword"
       }
     }
   }
 }
+----
+
+Use the put mapping API
+to add a new inner `last` text field
+to the `name` field.
 
+[source,console]
+----
 PUT /my_index/_mapping
 {
   "properties": {
     "name": {
       "properties": {
-        "last": { <2>
+        "last": {
           "type": "text"
         }
       }
-    },
+    }
+  }
+}
+----
+// TEST[continued]
+
+Use the <<indices-get-mapping,get mapping>> API
+to verify your changes.
+
+[source,console]
+----
+GET /my_index/_mapping
+----
+// TEST[continued]
+
+The API returns the following response:
+
+[source,console-result]
+----
+{
+  "my_index" : {
+    "mappings" : {
+      "properties" : {
+        "name" : {
+          "properties" : {
+            "first" : {
+              "type" : "text"
+            },
+            "last" : {
+              "type" : "text"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+----
+
+
+[[add-multi-fields-existing-field-ex]]
+===== Add multi-fields to an existing field
+
+<<multi-fields,Multi-fields>>
+let you index the same field
+in different ways.
+You can use the put mapping API
+to update the `fields` mapping parameter
+and enable multi-fields for an existing field.
+
+To see how this works,
+try the following example.
+
+Use the <<indices-create-index,create index>> API
+to create an index
+with the `city` <<text,text>> field.
+
+[source,console]
+----
+PUT /my_index
+{
+  "mappings": {
+    "properties": {
+      "city": {
+        "type": "text"
+      }
+    }
+  }
+}
+----
+
+While text fields work well for full-text search,
+<<keyword,keyword>> fields are not analyzed
+and may work better for sorting or aggregations.
+
+Use the put mapping API
+to enable a multi-field for the `city` field.
+This request adds the `city.raw` keyword multi-field,
+which can be used for sorting.
+
+[source,console]
+----
+PUT /my_index/_mapping
+{
+  "properties": {
+    "city": {
+      "type": "text",
+      "fields": {
+        "raw": {
+          "type": "keyword"
+        }
+      }
+    }
+  }
+}
+----
+// TEST[continued]
+
+Use the <<indices-get-mapping,get mapping>> API
+to verify your changes.
+
+[source,console]
+----
+GET /my_index/_mapping
+----
+// TEST[continued]
+
+The API returns the following response:
+
+[source,console-result]
+----
+{
+  "my_index" : {
+    "mappings" : {
+      "properties" : {
+        "city" : {
+          "type" : "text",
+          "fields" : {
+            "raw" : {
+              "type" : "keyword"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+----
+
+
+[[change-existing-mapping-parms]]
+===== Change supported mapping parameters for an existing field
+
+The documentation for each <<mapping-params,mapping parameter>>
+indicates whether you can update it
+for an existing field
+using the put mapping API.
+For example,
+you can use the put mapping API
+to update the <<ignore-above,`ignore_above`>> parameter.
+
+To see how this works,
+try the following example.
+
+Use the <<indices-create-index,create index>> API to create an index
+containing a `user_id` keyword field.
+The `user_id` field
+has an `ignore_above` parameter value
+of `20`.
+
+[source,console]
+----
+PUT /my_index
+{
+  "mappings": {
+    "properties": {
+      "user_id": {
+        "type": "keyword",
+        "ignore_above": 20
+      }
+    }
+  }
+}
+----
+
+Use the put mapping API
+to change the `ignore_above` parameter value
+to `100`.
+
+[source,console]
+----
+PUT /my_index/_mapping
+{
+  "properties": {
     "user_id": {
       "type": "keyword",
-      "ignore_above": 100 <3>
+      "ignore_above": 100
+    }
+  }
+}
+----
+// TEST[continued]
+
+Use the <<indices-get-mapping,get mapping>> API
+to verify your changes.
+
+[source,console]
+----
+GET /my_index/_mapping
+----
+// TEST[continued]
+
+The API returns the following response:
+
+[source,console-result]
+----
+{
+  "my_index" : {
+    "mappings" : {
+      "properties" : {
+        "user_id" : {
+          "type" : "keyword",
+          "ignore_above" : 100
+        }
+      }
+    }
+  }
+}
+----
+
+
+[[updating-field-mappings]]
+===== Change the mapping of an existing field
+
+// tag::change-field-mapping[]
+Except for supported <<mapping-params,mapping parameters>>,
+you can't change the mapping or field type of an existing field.
+Changing 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 mapping
+and <<docs-reindex,reindex>> your data into that index.
+// end::change-field-mapping[]
+
+To see how this works,
+try the following example.
+
+Use the <<indices-create-index,create index>> API
+to create the `users` index
+with the `user_id` field
+with the <<number,`long`>> field type.
+
+[source,console]
+----
+PUT /users
+{
+  "mappings" : {
+    "properties": {
+      "user_id": {
+        "type": "long"
+      }
+    }
+  }
+}
+----
+
+Use the <<docs-index_,index>> API
+to index several documents
+with `user_id` field values.
+
+[source,console]
+----
+POST /users/_doc?refresh=wait_for
+{
+    "user_id" : 12345
+}
+
+POST /users/_doc?refresh=wait_for
+{
+    "user_id" : 12346
+}
+----
+// TEST[continued]
+
+To change the `user_id` field
+to the <<keyword,`keyword`>> field type,
+use the create index API
+to create the `new_users` index with the correct mapping.
+
+[source,console]
+----
+PUT /new_users
+{
+  "mappings" : {
+    "properties": {
+      "user_id": {
+        "type": "keyword"
+      }
+    }
+  }
+}
+----
+// TEST[continued]
+
+Use the <<docs-reindex,reindex>> API
+to copy documents from the `users` index
+to the `new_users` index.
+
+[source,console]
+----
+POST /_reindex
+{
+  "source": {
+    "index": "users"
+  },
+  "dest": {
+    "index": "new_users"
+  }
+}
+----
+// TEST[continued]
+
+The API returns the following response:
+
+[source,console-result]
+----
+{
+  "took": 147,
+  "timed_out": false,
+  "total": 2,
+  "updated": 0,
+  "created": 2,
+  "deleted": 0,
+  "batches": 1,
+  "version_conflicts": 0,
+  "noops": 0,
+  "retries": {
+    "bulk": 0,
+    "search": 0
+  },
+  "throttled_millis": 0,
+  "requests_per_second": -1.0,
+  "throttled_until_millis": 0,
+  "failures" : [ ]
+}
+----
+// TESTRESPONSE[s/"took": 147/"took": "$body.took"/]
+
+
+[[rename-existing-field]]
+===== Rename a field
+
+// tag::rename-field[]
+Renaming a field would invalidate data already indexed under the old field name.
+Instead, add an <<alias, `alias`>> field to create an alternate field name.
+// end::rename-field[]
+
+For example,
+use the <<indices-create-index,create index>> API
+to create an index
+with the `user_identifier` field.
+
+[source,console]
+----
+PUT /my_index
+{
+  "mappings": {
+    "properties": {
+      "user_identifier": {
+        "type": "keyword"
+      }
     }
   }
 }
------------------------------------
+----
+
+Use the put mapping API to add the `user_id` field alias
+for the existing `user_identifier` field.
+
+[source,console]
+----
+PUT /my_index/_mapping
+{
+  "properties": {
+    "user_id": {
+      "type": "alias",
+      "path": "user_identifier"
+    }
+  }
+}
+----
+// TEST[continued]
 
-<1> Create an index with a `first` field under the `name` <<object>> field, and a `user_id` field.
-<2> Add a `last` field under the `name` object field.
-<3> Update the `ignore_above` setting from its default of 0.
+Use the <<indices-get-mapping,get mapping>> API
+to verify your changes.
 
-Each <<mapping-params,mapping parameter>> specifies whether or not its setting
-can be updated on an existing field.
+[source,console]
+----
+GET /my_index/_mapping
+----
+// TEST[continued]
+
+The API returns the following response:
+
+[source,console-result]
+----
+{
+  "my_index" : {
+    "mappings" : {
+      "properties" : {
+        "user_id" : {
+          "type" : "alias",
+          "path" : "user_identifier"
+        },
+        "user_identifier" : {
+          "type" : "keyword"
+        }
+      }
+    }
+  }
+}
+----

docs/reference/mapping.asciidoc

@@ -176,7 +176,9 @@ PUT /my-index/_mapping
 [[update-mapping]]
 === Update the mapping of a field
 
-include::{docdir}/indices/put-mapping.asciidoc[tag=put-field-mapping-exceptions]
+include::{docdir}/indices/put-mapping.asciidoc[tag=change-field-mapping]
+
+include::{docdir}/indices/put-mapping.asciidoc[tag=rename-field]
 
 [float]
 [[view-mapping]]