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 /twitter/_mapping
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}
----
// 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 /<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]


[[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 `twitter-1` and `twitter-2` indices at the same time:

[source,console]
--------------------------------------------------
# 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"
    }
  }
}
--------------------------------------------------
// TEST[setup:twitter]

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


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

Use the <<indices-get-mapping,get mapping>> API
to verify your changes.

[source,console]
----
GET /my-index-000001/_mapping
----
// TEST[continued]

The API returns the following response:

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


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

Use the <<indices-get-mapping,get mapping>> API
to verify your changes.

[source,console]
----
GET /my-index-000001/_mapping
----
// TEST[continued]

The API returns the following response:

[source,console-result]
----
{
  "my-index-000001" : {
    "mappings" : {
      "properties" : {
        "city" : {
          "type" : "text",
          "fields" : {
            "raw" : {
              "type" : "keyword"
            }
          }
        }
      }
    }
  }
}
----


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

Use the <<indices-get-mapping,get mapping>> API
to verify your changes.

[source,console]
----
GET /my-index-000001/_mapping
----
// TEST[continued]

The API returns the following response:

[source,console-result]
----
{
  "my-index-000001" : {
    "mappings" : {
      "properties" : {
        "user_id" : {
          "type" : "keyword",
          "ignore_above" : 100
        }
      }
    }
  }
}
----


[[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 the `users` index
with the `user_id` field
with the <<number,`long`>> field type.

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

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

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

POST /users/_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 the `new_users` index with the correct mapping.

[source,console]
----
PUT /new_users
{
  "mappings" : {
    "properties": {
      "user_id": {
        "type": "keyword"
      }
    }
  }
}
----
// TEST[continued]

Use the <<docs-reindex,reindex>> API
to copy documents from the `users` index
to the `new_users` index.

[source,console]
----
POST /_reindex
{
  "source": {
    "index": "users"
  },
  "dest": {
    "index": "new_users"
  }
}
----
// TEST[continued]

The API returns the following response:

[source,console-result]
----
{
  "took": 147,
  "timed_out": false,
  "total": 2,
  "updated": 0,
  "created": 2,
  "deleted": 0,
  "batches": 1,
  "version_conflicts": 0,
  "noops": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "throttled_millis": 0,
  "requests_per_second": -1.0,
  "throttled_until_millis": 0,
  "failures" : [ ]
}
----
// TESTRESPONSE[s/"took": 147/"took": "$body.took"/]


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

Use the <<indices-get-mapping,get mapping>> API
to verify your changes.

[source,console]
----
GET /my-index-000001/_mapping
----
// TEST[continued]

The API returns the following response:

[source,console-result]
----
{
  "my-index-000001" : {
    "mappings" : {
      "properties" : {
        "user_id" : {
          "type" : "alias",
          "path" : "user_identifier"
        },
        "user_identifier" : {
          "type" : "keyword"
        }
      }
    }
  }
}
----