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

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

The PUT mapping API allows you to add fields to an existing index or to change search only settings of existing fields.

[source,js]
--------------------------------------------------
PUT twitter <1>
{}

PUT twitter/_mapping <2>
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}
--------------------------------------------------
// CONSOLE
<1> <<indices-create-index,Creates an index>> called `twitter` without any mapping.
<2> Uses the PUT mapping API to add a new field called `email`.

More information on how to define mappings can be found in the <<mapping,mapping>> section.

NOTE: Before 7.0.0, the 'mappings' definition used to include a type name. Although specifying
types in requests is now deprecated, a type can still be provided if the request parameter
include_type_name is set. For more details, please see <<removal-of-types>>.

[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 <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.


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

// tag::put-field-mapping-exceptions[]

You can't change the mapping of an existing field, with the following
exceptions:

* You can add new <<properties,properties>> to an <<object,`object`>> field.
* You can use the <<multi-fields,`field`>> mapping parameter to enable
multi-fields.
* You can change the value of the <<ignore-above,`ignore_above`>> mapping
parameter.

Changing the mapping of an existing field could invalidate data that's already
indexed. If you need to change the mapping of a field, create a new index with
the correct mappings and <<docs-reindex,reindex>> your data into that index. If
you only want to rename a field, consider adding an <<alias, `alias`>> field.

// end::put-field-mapping-exceptions[]

For example:

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

PUT my_index/_mapping
{
  "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.