Link Search Menu Expand Document Documentation Menu
Documentation

You're viewing version 2.5 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Create or update mappings

Introduced 1.0

If you want to create or add mappings and fields to an index, you can use the put mapping API operation. For an existing mapping, this operation updates the mapping.

You can’t use this operation to update mappings that already map to existing data in the index. You must first create a new index with your desired mappings, and then use the reindex API operation to map all the documents from your old index to the new index. If you don’t want any downtime while you re-index your indexes, you can use aliases.

Required path parameter

The only required path parameter is the index with which to associate the mapping. If you don’t specify an index, you will get an error. You can specify a single index, or multiple indexes separated by a comma as follows:

PUT /<target-index>/_mapping
PUT /<target-index1>,<target-index2>/_mapping

Required request body field

The request body must contain properties, which has all of the mappings that you want to create or update.

{
  "properties":{
    "color":{
      "type": "text"
    },
    "year":{
      "type": "integer"
    }
  }
}

Optional request body fields

dynamic

You can make the document structure match the structure of the index mapping by setting the dynamic request body field to strict, as seen in the following example:

{
  "properties":{
    "dynamic": "strict",
    "color":{
      "type": "text"
    }
  }
}

Optional query parameters

Optionally, you can add query parameters to make a more specific request. For example, to skip any missing or closed indexes in the response, you can add the ignore_unavailable query parameter to your request as follows:

PUT /sample-index/_mapping?ignore_unavailable

The following table defines the put mapping query parameters:

Parameter Data type Description
allow_no_indices Boolean Whether to ignore wildcards that don’t match any indexes. Default is true.
expand_wildcards String Expands wildcard expressions to different indexes. Combine multiple values with commas. Available values are all (match all indexes), open (match open indexes), closed (match closed indexes), hidden (match hidden indexes), and none (do not accept wildcard expressions), which must be used with open, closed, or both. Default is open.
ignore_unavailable Boolean If true, OpenSearch does not include missing or closed indexes in the response.
ignore_malformed Boolean Use this parameter with the ip_range data type to specify that OpenSearch should ignore malformed fields. If true, OpenSearch does not include entries that do not match the IP range specified in the index in the response. The default is false.
cluster_manager_timeout Time How long to wait for a connection to the cluster manager node. Default is 30s.
timeout Time How long to wait for the response to return. Default is 30s.
write_index_only Boolean Whether OpenSearch should apply mapping updates only to the write index.

Sample Request

The following request creates a new mapping for the sample-index index:

PUT /sample-index/_mapping

{
  "properties": {
    "age": {
      "type": "integer"
    },
    "occupation":{
      "type": "text"
    }
  }
}

Sample Response

Upon success, the response returns "acknowledged": true.

{
    "acknowledged": true
}
350 characters left

Have a question? .

Want to contribute? or .