Documented the update_all_types setting on PUT mapping

Added docs to each mapping param to specify which ones can be updated when

docs/reference/indices/put-mapping.asciidoc

@@ -1,80 +1,195 @@
 [[indices-put-mapping]]
 == Put Mapping
 
-The put mapping API allows to register specific mapping definition for a
-specific type.
+The PUT mapping API allows you to add a new type to an existing index, or new
+fields to an existing type:
 
 [source,js]
 --------------------------------------------------
-$ curl -XPUT 'http://localhost:9200/twitter/_mapping/tweet' -d '
+PUT twitter <1>
 {
-    "tweet" : {
-        "properties" : {
-            "message" : {"type" : "string", "store" : true }
+  "mappings": {
+    "tweet": {
+      "properties": {
+        "message": {
+          "type": "string"
         }
+      }
     }
+  }
 }
-'
---------------------------------------------------
 
-The above example creates a mapping called `tweet` within the `twitter`
-index. The mapping simply defines that the `message` field should be
-stored (by default, fields are not stored, just indexed) so we can
-retrieve it later on using selective loading.
+PUT twitter/_mapping/user <2>
+{
+  "properties": {
+    "name": {
+      "type": "string"
+    }
+  }
+}
+
+PUT twitter/_mapping/tweet <3>
+{
+  "properties": {
+    "user_name": {
+      "type": "string"
+    }
+  }
+}
+--------------------------------------------------
+// AUTOSENSE
+<1> <<indices-create-index,Creates an index>> called `twitter` with the `message` field in the `tweet` <<mapping-type,mapping type>>.
+<2> Uses the PUT mapping API to add a new mapping type called `user`.
+<3> Uses the PUT mapping API to add a new field called `user_name` to the `tweet` mapping type.
 
 More information on how to define type mappings can be found in the
 <<mapping,mapping>> section.
 
 [float]
-[[merging-conflicts]]
-=== Merging & Conflicts
+=== Multi-index
 
-When an existing mapping already exists under the given type, the two
-mapping definitions, the one already defined, and the new ones are
-merged. If there are conflicts then the update will be rejected.
+The PUT mapping API can be applied to multiple indices with a single request.
+It has the following format:
+
+[source,js]
+--------------------------------------------------
+PUT /{index}/_mapping/{type}
+{ body }
+--------------------------------------------------
+
+* `{index}` accepts <<multi-index,multiple index names>> and wildcards.
+* `{type}` is the name of the type to update.
+* `{body}` contains the mapping changes that should be applied.
 
-The definition of conflict is really dependent on the type merged, but
-in general, if a different core type is defined, it is considered as a
-conflict. New mapping definitions can be added to object types, and core
-type mappings can be upgraded by specifying multi fields on a core type.
 
+[[updating-field-mappings]]
 [float]
-[[put-mapping-multi-index]]
-=== Multi Index
+=== Updating field mappings
 
-The put mapping API can be applied to more than one index with a single
-call, or even on `_all` the indices.
+In general, the mapping for existing fields cannot be updated.  There are some
+exceptions to this rule. For instance:
+
+* new <<properties>> can be added to <<object>> fields.
+* new <<fields,multi-fields>> can be added to existing fields.
+* <<doc-values>> can be disabled, but not enabled.
+* the <<ignore-above>> parameter can be updated.
+
+For example:
 
 [source,js]
---------------------------------------------------
-$ curl -XPUT 'http://localhost:9200/kimchy,elasticsearch/_mapping/tweet' -d '
+-----------------------------------
+PUT my_index <1>
 {
-    "tweet" : {
-        "properties" : {
-            "message" : {"type" : "string", "store" : true }
+  "mappings": {
+    "user": {
+      "properties": {
+        "name": {
+          "properties": {
+            "first": {
+              "type": "string"
+            }
+          }
+        },
+        "user_id": {
+          "type": "string",
+          "index": "not_analyzed"
         }
+      }
     }
+  }
 }
-'
---------------------------------------------------
 
-All options:
+PUT my_index/mapping/user
+{
+  "properties": {
+    "name": {
+      "properties": {
+        "last": { <2>
+          "type": "string"
+        }
+      }
+    },
+    "user_id": {
+      "type": "string",
+      "index": "not_analyzed",
+      "ignore_above": 100 <3>
+    }
+  }
+}
+-----------------------------------
+// AUTOSENSE
+<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.
 
-[source,js]
---------------------------------------------------
+Each <<mapping-params,mapping parameter>> specifies whether or not its setting
+can be updated on an existing field.
 
-PUT /{index}/_mapping/{type}
+[float]
+[[merging-conflicts]]
+=== Conflicts between fields in different types
 
+Fields in the same index with the same name in two different types must have
+the same mapping, as they are backed by the same field internally.  Trying to
+<<updating-field-mappings,update a mapping parameter>> for a field which
+exists in more than one type will throw an exception, unless you specify the
+`update_all_types` parameter, in which case it will update that parameter
+across all fields with the same name in the same index.
 
---------------------------------------------------
+TIP: The only parameters which are exempt from this rule -- they can be set to
+different values on each field -- can be found in  <<field-conflicts>>.
 
+For example:
 
-where
+[source,js]
+-----------------------------------
+PUT my_index
+{
+  "mappings": {
+    "type_one": {
+      "properties": {
+        "text": { <1>
+          "type": "string",
+          "analyzer": "standard"
+        }
+      }
+    },
+    "type_two": {
+      "properties": {
+        "text": { <1>
+          "type": "string",
+          "analyzer": "standard"
+        }
+      }
+    }
+  }
+}
 
-[horizontal]
-`{index}`:: `blank | * | _all | glob pattern | name1, name2, …`
+PUT my_index/_mapping/type_one <2>
+{
+  "properties": {
+    "text": {
+      "type": "string",
+      "analyzer": "standard",
+      "search_analyzer": "whitespace"
+    }
+  }
+}
 
-`{type}`:: Name of the type to add. Must be the name of the type defined in the body.
+PUT my_index/_mapping/type_one?update_all_types <3>
+{
+  "properties": {
+    "text": {
+      "type": "string",
+      "analyzer": "standard",
+      "search_analyzer": "whitespace"
+    }
+  }
+}
+-----------------------------------
+// AUTOSENSE
+<1> Create an index with two types, both of which contain a `text` field which have the same mapping.
+<2> Tring to update the `search_analyzer` just for `type_one` throws an exception like `"Merge failed with failures..."`.
+<3> Adding the `update_all_types` parameter updates the `text` field in `type_one` and `type_two`.
 
 
-Instead of `_mapping` you can also use the plural `_mappings`.

docs/reference/mapping/params/coerce.asciidoc

@@ -49,6 +49,10 @@ PUT my_index/my_type/2
 <1> The `number_one` field will contain the integer `10`.
 <2> This document will be rejected because coercion is disabled.
 
+TIP: The `coerce` setting is allowed to have different settings for fields of
+the same name in the same index.  Its value can be updated on existing fields
+using the <<indices-put-mapping,PUT mapping API>>.
+
 [[coerce-setting]]
 ==== Index-level default
 

docs/reference/mapping/params/doc-values.asciidoc

@@ -44,3 +44,8 @@ PUT my_index
 <1> The `status_code` field has `doc_values` enabled by default.
 <2> The `session_id` has `doc_values` disabled, but can still be queried.
 
+TIP: The `doc_values` setting is allowed to have different settings for fields
+of the same name in the same index.  It can be disabled (set to `false`) on
+existing fields using the <<indices-put-mapping,PUT mapping API>>.
+
+

docs/reference/mapping/params/dynamic.asciidoc

@@ -85,3 +85,8 @@ PUT my_index
 <2> The `user` object inherits the type-level setting.
 <3> The `user.social_networks` object enables dynamic mapping, so new fields may be added to this inner object.
 
+TIP: The `dynamic` setting is allowed to have different settings for fields of
+the same name in the same index.  Its value can be updated on existing fields
+using the <<indices-put-mapping,PUT mapping API>>.
+
+

docs/reference/mapping/params/enabled.asciidoc

@@ -92,3 +92,8 @@ GET my_index/_mapping <3>
 <1> The entire `session` mapping type is disabled.
 <2> The document can be retrieved.
 <3> Checking the mapping reveals that no fields have been added.
+
+TIP: The `enabled` setting is allowed to have different settings for fields of
+the same name in the same index.  Its value can be updated on existing fields
+using the <<indices-put-mapping,PUT mapping API>>.
+

docs/reference/mapping/params/fielddata.asciidoc

@@ -22,7 +22,6 @@ by reading the entire inverted index for each segment from disk, inverting the
 term ↔︎ document relationship, and storing the result in memory, in the
 JVM heap.
 
-
 Loading fielddata is an expensive process so, once it has been loaded, it
 remains in memory for the lifetime of the segment.
 
@@ -38,6 +37,11 @@ aggregation).  Always think about whether a `not_analyzed` field (which can
 use `doc_values`) would be  a better fit for your use case.
 ==============================================================================
 
+TIP: The `fielddata.*` settings must have the same settings for fields of the
+same name in the same index.  Its value can be updated on existing fields
+using the <<indices-put-mapping,PUT mapping API>>.
+
+
 [[fielddata-format]]
 ==== `fielddata.format`
 

docs/reference/mapping/params/format.asciidoc

@@ -31,6 +31,11 @@ Many APIs which support date values also support <<date-math,date math>>
 expressions, such as `now-1m/d` -- the current time, minus one month, rounded
 down to the nearest day.
 
+TIP: The `format` setting must have the same setting for fields of the same
+name in the same index.  Its value can be updated on existing fields using the
+<<indices-put-mapping,PUT mapping API>>.
+
+
 [[custom-date-formats]]
 ==== Custom date formats
 

docs/reference/mapping/params/ignore-above.asciidoc

@@ -52,6 +52,11 @@ GET _search <4>
 <3> This document will be indexed, but without indexing the `message` field.
 <4> Search returns both documents, but only the first is present in the terms aggregation.
 
+TIP: The `ignore_above` setting is allowed to have different settings for
+fields of the same name in the same index.  Its value can be updated on
+existing fields using the <<indices-put-mapping,PUT mapping API>>.
+
+
 This option is also useful for protecting against Lucene's term byte-length
 limit of `32766`.
 

docs/reference/mapping/params/ignore-malformed.asciidoc

@@ -47,6 +47,10 @@ PUT my_index/my_type/2
 <1> This document will be rejected because `number_one` does not allow malformed values.
 <2> This document will have the `text` field indexed, but not the `number_two` field.
 
+TIP: The `ignore_malformed` setting is allowed to have different settings for
+fields of the same name in the same index.  Its value can be updated on
+existing fields using the <<indices-put-mapping,PUT mapping API>>.
+
 
 [[ignore-malformed-setting]]
 ==== Index-level default

docs/reference/mapping/params/include-in-all.asciidoc

@@ -33,6 +33,11 @@ PUT my_index
 <1> The `title` and `content` fields with be included in the `_all` field.
 <2> The `date` field will not be included in the `_all` field.
 
+TIP: The `include_in_all` setting is allowed to have different settings for
+fields of the same name in the same index.  Its value can be updated on
+existing fields using the <<indices-put-mapping,PUT mapping API>>.
+
+
 The `include_in_all` parameter can also be set at the type level and on
 <<object,`object`>> or <<nested,`nested`>> fields, in which case all sub-
 fields inherit that setting.  For instance:

docs/reference/mapping/params/multi-fields.asciidoc

@@ -63,6 +63,10 @@ GET /my_index/_search
 
 NOTE: Multi-fields do not change the original `_source` field.
 
+TIP: The `fields` setting is allowed to have different settings for fields of
+the same name in the same index.  New multi-fields can be added to existing
+fields using the <<indices-put-mapping,PUT mapping API>>.
+
 ==== Multi-fields with multiple analyzers
 
 Another use case of multi-fields is to analyze the same field in different

docs/reference/mapping/params/norms.asciidoc

@@ -13,6 +13,10 @@ don't need scoring on a specific field, you should disable norms on that
 field. In  particular, this is the case for fields that are used solely for
 filtering or aggregations.
 
+TIP: The `norms.enabled` setting must have the same setting for fields of the
+same name in the same index.  Norms can be disabled on existing fields using
+the <<indices-put-mapping,PUT mapping API>>.
+
 Norms can be disabled (but not reenabled) after the fact, using the
 <<indices-put-mapping,PUT mapping API>> like so:
 
@@ -38,6 +42,7 @@ computation on a field that has had norms removed might return inconsistent
 results since some documents won't have norms anymore while other documents
 might still have norms.
 
+
 ==== Lazy loading of norms
 
 Norms can be loaded into memory eagerly (`eager`), whenever a new segment
@@ -62,3 +67,7 @@ PUT my_index/_mapping/my_type
 ------------
 // AUTOSENSE
 
+TIP: The `norms.loading` setting must have the same setting for fields of the
+same name in the same index.  Its value can be updated on existing fields
+using the <<indices-put-mapping,PUT mapping API>>.
+

docs/reference/mapping/params/null-value.asciidoc

@@ -56,3 +56,4 @@ analyzer.
 
 Also see the <<query-dsl-missing-query,`missing` query>> for its `null_value` support.
 
+

docs/reference/mapping/params/position-offset-gap.asciidoc

@@ -65,4 +65,9 @@ GET /my_index/groups/_search
 // AUTOSENSE
 <1> The first term in the next array element will be 50 terms apart from the
     last term in the previous array element.
-<2> The phrase query no longer matches our document.
+<2> The phrase query no longer matches our document.
+
+TIP: The `position_offset_gap` setting is allowed to have different settings
+for fields of the same name in the same index.  Its value can be updated on
+existing fields using the <<indices-put-mapping,PUT mapping API>>.
+

docs/reference/mapping/params/properties.asciidoc

@@ -63,6 +63,10 @@ PUT my_index/my_type/1 <4>
 <3> Properties under the `employees` nested field.
 <4> An example document which corresponds to the above mapping.
 
+TIP: The `properties` setting is allowed to have different settings for fields
+of the same name in the same index.  New properties can be added to existing
+fields using the <<indices-put-mapping,PUT mapping API>>.
+
 ==== Dot notation
 
 Inner fields can be referred to in queries, aggregations, etc., using _dot

docs/reference/mapping/params/search-analyzer.asciidoc

@@ -77,3 +77,9 @@ GET my_index/_search
 
 See {defguide}/_index_time_search_as_you_type.html[Index time search-as-you-
 type] for a full explanation of this example.
+
+TIP: The `search_analyzer` setting must have the same setting for fields of
+the same name in the same index.  Its value can be updated on existing fields
+using the <<indices-put-mapping,PUT mapping API>>.
+
+