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/_doc <2>
{
  "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 field called `email` to the `_doc` 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/_doc <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

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": {
    "_doc": {
      "properties": {
        "name": {
          "properties": {
            "first": {
              "type": "text"
            }
          }
        },
        "user_id": {
          "type": "keyword"
        }
      }
    }
  }
}

PUT my_index/_mapping/_doc
{
  "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]
=== Skipping types

Types are scheduled to be fully removed in Elasticsearch 8.0 and will not appear
in requests or responses anymore. You can opt in for this future behaviour by
setting `include_type_name=false`.

NOTE: This should only be done on indices that have been created with
`include_type_name=false` or that used `_doc` as a type name.

The Console script from the above section is equivalent to the below invocation:

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

PUT my_index/_mapping?include_type_name=false
{
  "properties": {
    "name": {
      "properties": {
        "last": { <2>
          "type": "text"
        }
      }
    },
    "user_id": {
      "type": "keyword",
      "ignore_above": 100 <3>
    }
  }
}
-----------------------------------
// CONSOLE