add docs example for Ingest scripts manipulating document metadata
It may not be clear to users that the Ingest ScriptProcessor context object `ctx` can
manipulate document metadata like `_index` and `_type`.
@@ -1738,6 +1738,63 @@ numeric fields `field_a` and `field_b` multiplied by the parameter param_c:
--------------------------------------------------
// NOTCONSOLE
+It is possible to use the Script Processor to manipulate document metadata like `_index` and `_type` during
+ingestion. Here is an example of an Ingest Pipeline that renames the index and type to `my_index` no matter what
+was provided in the original index request:
+
+[source,js]
+--------------------------------------------------
+PUT _ingest/pipeline/my_index
+{
+ "description": "use index:my_index and type:my_type",
+ "processors": [
+ {
+ "script": {
+ "inline": " ctx._index = 'my_index'; ctx._type = 'my_type' "
+ }
+ }
+ ]
+}
+--------------------------------------------------
+// CONSOLE
+
+Using the above pipeline, we can attempt to index a document into the `any_index` index.
+
+[source,js]
+--------------------------------------------------
+PUT any_index/any_type/1?pipeline=my_index
+{
+ "message": "text"
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+The response from the above index request:
+
+[source,js]
+--------------------------------------------------
+{
+ "_index": "my_index",
+ "_type": "my_type",
+ "_id": "1",
+ "_version": 1,
+ "result": "created",
+ "_shards": {
+ "total": 2,
+ "successful": 1,
+ "failed": 0
+ },
+ "_seq_no": 0,
+ "_primary_term": 1,
+ "created": true
+}
+--------------------------------------------------
+// TESTRESPONSE
+
+In the above response, you can see that our document was actually indexed into `my_index` instead of
+`any_index`. This type of manipulation is often convenient in pipelines that have various branches of transformation,
+and depending on the progress made, indexed into different indices.
[[set-processor]]
=== Set Processor
