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

Adds new fields to an existing data stream or index. You can also use this
API to change the search settings of existing fields.

For data streams, these changes are applied to all backing indices by default.

[source,console]
----
PUT /my-index-000001/_mapping
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}
----
// TEST[setup:my_index]

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

`PUT /<target>/_mapping`

[[put-mapping-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `manage`
<<privileges-list-indices,index privilege>> for the target data stream, index,
or alias.
+
deprecated:[7.9] If the request targets an index or index alias, you can also
update its mapping with the `create`, `create_doc`, `index`, or `write` index
privilege.


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

`<target>`::
(Required, string) Comma-separated list of data streams, indices, and aliases
used to limit the request. Supports wildcards (`*`). To target all data streams
and indices, omit this parameter or use `*` or `_all`.

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

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `false`.

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

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

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

`write_index_only`::
(Optional, Boolean)
If `true`,
the mappings are applied only to the current write index for the target.
Defaults to `false`.


[[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
* <<mapping-types,Field data type>>
* <<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 single target

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

[source,console]
----
PUT /publications
----

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

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

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

The update mapping API can be applied to multiple data streams or indices with a single request.
For example, you can update mappings for the `my-index-000001` and `my-index-000002` indices at the same time:

[source,console]
--------------------------------------------------
# Create the two indices
PUT /my-index-000001
PUT /my-index-000002

# Update both mappings
PUT /my-index-000001,my-index-000002/_mapping
{
  "properties": {
    "user": {
      "properties": {
        "name": {
          "type": "keyword"
        }
      }
    }
  }
}
--------------------------------------------------


[[add-new-field-to-object]]
===== Add new properties to an existing object field

You can use the update mapping API to add new properties to an existing
<<object,`object`>> field. To see how this works, try the following example.

Use the <<indices-create-index,create index>> API to create an index with the
`name` object field and an inner `first` text field.

[source,console]
----
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "name": {
        "properties": {
          "first": {
            "type": "text"
          }
        }
      }
    }
  }
}
----

Use the update mapping API to add a new inner `last` text field to the `name`
field.

[source,console]
----
PUT /my-index-000001/_mapping
{
  "properties": {
    "name": {
      "properties": {
        "last": {
          "type": "text"
        }
      }
    }
  }
}
----
// TEST[continued]


[[add-multi-fields-existing-field-ex]]
===== Add multi-fields to an existing field

<<multi-fields,Multi-fields>> let you index the same field in different ways.
You can use the update mapping API to update the `fields` mapping parameter and
enable multi-fields for an existing field.

WARNING: If an index (or data stream) contains documents when you add a
multi-field, those documents will not have values for the new multi-field. You
can populate the new multi-field with the <<picking-up-a-new-property,update by
query API>>.

To see how this works, try the following example.

Use the <<indices-create-index,create index>> API to create an index with the
`city` <<text,text>> field.

[source,console]
----
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "city": {
        "type": "text"
      }
    }
  }
}
----

While text fields work well for full-text search, <<keyword,keyword>> fields are
not analyzed and may work better for sorting or aggregations.

Use the update mapping API to enable a multi-field for the `city` field. This
request adds the `city.raw` keyword multi-field, which can be used for sorting.

[source,console]
----
PUT /my-index-000001/_mapping
{
  "properties": {
    "city": {
      "type": "text",
      "fields": {
        "raw": {
          "type": "keyword"
        }
      }
    }
  }
}
----
// TEST[continued]


[[change-existing-mapping-parms]]
===== Change supported mapping parameters for an existing field

The documentation for each <<mapping-params,mapping parameter>> indicates
whether you can update it for an existing field using the update mapping API. For
example, you can use the update mapping API to update the
<<ignore-above,`ignore_above`>> parameter.

To see how this works, try the following example.

Use the <<indices-create-index,create index>> API to create an index containing
a `user_id` keyword field. The `user_id` field has an `ignore_above` parameter
value of `20`.

[source,console]
----
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_id": {
        "type": "keyword",
        "ignore_above": 20
      }
    }
  }
}
----

Use the update mapping API to change the `ignore_above` parameter value to `100`.

[source,console]
----
PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "keyword",
      "ignore_above": 100
    }
  }
}
----
// TEST[continued]


[[updating-field-mappings]]
===== Change the mapping of an existing field

// tag::change-field-mapping[]
Except for supported <<mapping-params,mapping parameters>>,
you can't change the mapping or field type of an existing field.
Changing an existing field could invalidate data that's already indexed.

If you need to change the mapping of a field in a data stream's backing indices,
see <<data-streams-change-mappings-and-settings>>.

If you need to change the mapping of a field in other indices,
create a new index with the correct mapping
and <<docs-reindex,reindex>> your data into that index.
// end::change-field-mapping[]

To see how you can change the mapping of an existing field in an index,
try the following example.

Use the <<indices-create-index,create index>> API
to create an index
with the `user_id` field
with the <<number,`long`>> field type.

[source,console]
----
PUT /my-index-000001
{
  "mappings" : {
    "properties": {
      "user_id": {
        "type": "long"
      }
    }
  }
}
----

Use the <<docs-index_,index>> API
to index several documents
with `user_id` field values.

[source,console]
----
POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id" : 12345
}

POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id" : 12346
}
----
// TEST[continued]

To change the `user_id` field
to the <<keyword,`keyword`>> field type,
use the create index API
to create a new index with the correct mapping.

[source,console]
----
PUT /my-new-index-000001
{
  "mappings" : {
    "properties": {
      "user_id": {
        "type": "keyword"
      }
    }
  }
}
----
// TEST[continued]

Use the <<docs-reindex,reindex>> API
to copy documents from the old index
to the new one.

[source,console]
----
POST /_reindex
{
  "source": {
    "index": "my-index-000001"
  },
  "dest": {
    "index": "my-new-index-000001"
  }
}
----
// TEST[continued]


[[rename-existing-field]]
===== Rename a field

// tag::rename-field[]
Renaming a field would invalidate data already indexed under the old field name.
Instead, add an <<field-alias, `alias`>> field to create an alternate field name.
// end::rename-field[]

For example,
use the <<indices-create-index,create index>> API
to create an index
with the `user_identifier` field.

[source,console]
----
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_identifier": {
        "type": "keyword"
      }
    }
  }
}
----

Use the update mapping API to add the `user_id` field alias
for the existing `user_identifier` field.

[source,console]
----
PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "alias",
      "path": "user_identifier"
    }
  }
}
----
// TEST[continued]