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

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

Adds new fields to an existing data stream or index. You can also use the
put mapping 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]

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 /<target>/_mapping`

`PUT /_mapping`


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

`<target>`::
(Optional, string)
Comma-separated list of data streams, indices, and index aliases used to limit
the request. Wildcard expressions (`*`) are supported.
+
To target all data streams and indices in a cluster, omit this parameter or use
`_all` or `*`.


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

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

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

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

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

include::{es-repo-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
* <<field-datatypes,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 put 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 put 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 PUT 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 put 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 put 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 put mapping API to update the `fields` mapping parameter and
enable multi-fields for an existing field.

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 put 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 put mapping API. For
example, you can use the put 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 put 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 <<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 put 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]