OpenSearch/docs/reference/indices/put-mapping.asciidoc

[[indices-put-mapping]]
== Put Mapping

The PUT mapping API allows you to add a new type to an existing index, or add new
fields to an existing type:

[source,js]
--------------------------------------------------
PUT twitter <1>
{
  "settings": {
    "mapping.single_type": false
  },
  "mappings": {
    "tweet": {
      "properties": {
        "message": {
          "type": "text"
        }
      }
    }
  }
}

PUT twitter/_mapping/user <2>
{
  "properties": {
    "name": {
      "type": "text"
    }
  }
}

PUT twitter/_mapping/tweet <3>
{
  "properties": {
    "user_name": {
      "type": "text"
    }
  }
}
--------------------------------------------------
// CONSOLE
<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]
=== Multi-index

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.


NOTE: When updating the `_default_` mapping with the
<<indices-put-mapping,PUT mapping>> API, the new mapping is not merged with
the existing mapping.  Instead, the new `_default_` mapping replaces the
existing one.

[[updating-field-mappings]]
[float]
=== Updating field mappings

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 <<multi-fields,multi-fields>> can be added to existing fields.
* the <<ignore-above>> parameter can be updated.

For example:

[source,js]
-----------------------------------
PUT my_index <1>
{
  "mappings": {
    "user": {
      "properties": {
        "name": {
          "properties": {
            "first": {
              "type": "text"
            }
          }
        },
        "user_id": {
          "type": "keyword"
        }
      }
    }
  }
}

PUT my_index/_mapping/user
{
  "properties": {
    "name": {
      "properties": {
        "last": { <2>
          "type": "text"
        }
      }
    },
    "user_id": {
      "type": "keyword",
      "ignore_above": 100 <3>
    }
  }
}
-----------------------------------
// CONSOLE
<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.

Each <<mapping-params,mapping parameter>> specifies whether or not its setting
can be updated on an existing field.

[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, this fails:

[source,js]
-----------------------------------
PUT my_index
{
  "settings": {
    "mapping.single_type": false
  },
  "mappings": {
    "type_one": {
      "properties": {
        "text": { <1>
          "type": "text",
          "analyzer": "standard"
        }
      }
    },
    "type_two": {
      "properties": {
        "text": { <1>
          "type": "text",
          "analyzer": "standard"
        }
      }
    }
  }
}

PUT my_index/_mapping/type_one <2>
{
  "properties": {
    "text": {
      "type": "text",
      "analyzer": "standard",
      "search_analyzer": "whitespace"
    }
  }
}
-----------------------------------
// CONSOLE
// TEST[catch:request]
<1> Create an index with two types, both of which contain a `text` field which have the same mapping.
<2> Trying to update the `search_analyzer` just for `type_one` throws an exception like `"Merge failed with failures..."`.

But this then running this succeeds:

[source,js]
-----------------------------------
PUT my_index/_mapping/type_one?update_all_types <1>
{
  "properties": {
    "text": {
      "type": "text",
      "analyzer": "standard",
      "search_analyzer": "whitespace"
    }
  }
}
-----------------------------------
// CONSOLE
// TEST[continued]
<1> Adding the `update_all_types` parameter updates the `text` field in `type_one` and `type_two`.