[DOCS] Clarify copy_to behavior with strict dynamic mappings (#111408) (#111513)

* [DOCS] Clarify copy_to behavior with strict dynamic mappings

* Add id

* De-verbosify

* Delete pesky comma

* More info about root and nest

* Fixes per review, clarify non-recursive explanation

* Skip tests for illustrative example

* Fix example syntax

* Fix typo

Author: leemthompo

docs/reference/mapping/params/copy-to.asciidoc

@@ -64,16 +64,104 @@ Some important points:
 * It is the field _value_ which is copied, not the terms (which result from the analysis process).
 * The original <<mapping-source-field,`_source`>> field will not be modified to show the copied values.
 * The same value can be copied to multiple fields, with `"copy_to": [ "field_1", "field_2" ]`
-* You cannot copy recursively via intermediary fields such as a `copy_to` on 
-`field_1` to `field_2` and `copy_to` on `field_2` to `field_3` expecting 
-indexing into `field_1` will eventuate in `field_3`, instead use copy_to 
-directly to multiple fields from the originating field.
+* You cannot copy recursively using intermediary fields.
+The following configuration will not copy data from `field_1` to `field_3`:
++
+[source,console]
+----
+PUT bad_example_index
+{
+  "mappings": {
+    "properties": {
+      "field_1": {
+        "type": "text",
+        "copy_to": "field_2"
+      },
+      "field_2": {
+        "type": "text",
+        "copy_to": "field_3"
+      },
+      "field_3": {
+        "type": "text"
+      }
+    }
+  }
+}
+----
+Instead, copy to multiple fields from the source field:
++
+[source,console]
+----
+PUT good_example_index
+{
+  "mappings": {
+    "properties": {
+      "field_1": {
+        "type": "text",
+        "copy_to": ["field_2", "field_3"]
+      },
+      "field_2": {
+        "type": "text"
+      },
+      "field_3": {
+        "type": "text"
+      }
+    }
+  }
+}
+----
+
+NOTE: `copy_to` is not supported for field types where values take the form of objects, e.g. `date_range`.
+
+[float]
+[[copy-to-dynamic-mapping]]
+==== Dynamic mapping
+
+Consider the following points when using `copy_to` with dynamic mappings:
+
 * If the target field does not exist in the index mappings, the usual
 <<dynamic-mapping,dynamic mapping>> behavior applies. By default, with
 <<dynamic,`dynamic`>> set to `true`, a non-existent target field will be
-dynamically added to the index mappings. If `dynamic` is set to `false`, the
+dynamically added to the index mappings.
+* If `dynamic` is set to `false`, the
 target field will not be added to the index mappings, and the value will not be
-copied. If `dynamic` is set to `strict`, copying to a non-existent field will
+copied.
+* If `dynamic` is set to `strict`, copying to a non-existent field will
 result in an error.
++
+** If the target field is nested, then `copy_to` fields must specify the full path to the nested field.
+Omitting the full path will lead to a `strict_dynamic_mapping_exception`.
+Use `"copy_to": ["parent_field.child_field"]` to correctly target a nested field.
++
+For example:
++
+[source,console]
+--------------------------------------------------
+PUT /test_index
+{
+  "mappings": {
+    "dynamic": "strict",
+    "properties": {
+      "description": {
+        "properties": {
+          "notes": {
+            "type": "text",
+            "copy_to": [ "description.notes_raw"], <1>
+            "analyzer": "standard",
+            "search_analyzer": "standard"
+          },
+          "notes_raw": {
+            "type": "keyword"
+          }
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
 
-NOTE: `copy_to` is _not_ supported for field types where values take the form of objects, e.g. `date_range`
+<1> The `notes` field is copied to the `notes_raw` field. Targeting `notes_raw` alone instead of `description.notes_raw`
+would lead to a `strict_dynamic_mapping_exception`.
++
+In this example, `notes_raw` is not defined at the root of the mapping, but under the `description` field.
+Without the fully qualified path, {es} would interpret the `copy_to` target as a root-level field, not as a nested field under `description`.