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>
{}

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

PUT twitter/_mapping/user <3>
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}
--------------------------------------------------
// CONSOLE
<1> <<indices-create-index,Creates an index>> called `twitter` without any type mapping.
<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 `email` to the `user` 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.
For example, we can update the `twitter-1` and `twitter-2` mappings at the same time:

[source,js]
--------------------------------------------------
# Create the two indices
PUT twitter-1
PUT twitter-2

# Update both mappings
PUT /twitter-1,twitter-2/_mapping/my_type <1>
{
  "properties": {
    "user_name": {
      "type": "text"
    }
  }
}
--------------------------------------------------
// CONSOLE
<1> Note that the indices specified (`twitter-1,twitter-2`) follows <<multi-index,multiple index names>> and wildcard format.


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.