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

[[indices-put-mapping]]
=== Put mapping API
++++
<titleabbrev>Put mapping</titleabbrev>
++++

Adds new fields to an existing index or changes the search settings of existing
fields.

[source,js]
----
PUT /twitter/_mapping
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}
----
// CONSOLE
// TEST[setup:twitter]

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


[[put-mapping-api-request]]
==== {api-request-title}

`PUT /{index}/_mapping`

`PUT /_mapping`


[[put-mapping-api-path-params]]
==== {api-path-parms-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
To update the mapping of all indices, omit this parameter or use a value of
`_all`.


[[put-mapping-api-query-params]]
==== {api-query-parms-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]

include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.

include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]

include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]


[[put-mapping-api-request-body]]
==== {api-request-body-title}

`properties`::
+
--
(Required, <<mapping,mapping object>>) Mapping for a field. For new
fields, this mapping can include:

* Field name
* <<field-datatypes,Field datatype>>
* <<mapping-params,Mapping parameters>>

For existing fields, see <<updating-field-mappings>>.
--


[[put-mapping-api-example]]
==== {api-examples-title}

[[put-field-mapping-api-basic-ex]]
===== Example with index setup

The put mapping API requires an existing index. The following
<<indices-create-index, create index>> API request creates the `publications`
index with no mapping.

[source,js]
----
PUT /publications
----
// CONSOLE

The following put mapping API request adds `title`, a new <<text,`text`>> field,
to the `publications` index.

[source,js]
----
PUT /publications/_mapping
{
  "properties": {
    "title":  { "type": "text"}
  }
}
----
// CONSOLE
// TEST[continued]

[[put-mapping-api-multi-ex]]
===== Multiple indices

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
// TEST[setup:twitter]

<1> Note that the indices specified (`twitter-1,twitter-2`) follows <<multi-index,multiple index names>> and wildcard format.

[[updating-field-mappings]]
===== Update an existing field

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