IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› ›

Put Mapping

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Put Mapping

edit

The PUT mapping API allows you to add fields to an existing index or to change search only settings of existing fields.

PUT twitter 
{}

PUT twitter/_mapping/_doc 
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}

	Creates an index called `twitter` without any type mapping.
	Uses the PUT mapping API to add a new field called `email` to the `_doc` mapping type.

More information on how to define type mappings can be found in the mapping section.

Multi-index

edit

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:

# Create the two indices
PUT twitter-1
PUT twitter-2

# Update both mappings
PUT /twitter-1,twitter-2/_mapping/_doc 
{
  "properties": {
    "user_name": {
      "type": "text"
    }
  }
}

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

When updating the _default_ mapping with the PUT mapping API, the new mapping is not merged with the existing mapping. Instead, the new _default_ mapping replaces the existing one.

Updating field mappings

edit

In general, the mapping for existing fields cannot be updated. There are some exceptions to this rule. For instance:

new properties can be added to Object datatype fields.
new multi-fields can be added to existing fields.
the ignore_above parameter can be updated.

For example:

PUT my_index 
{
  "mappings": {
    "_doc": {
      "properties": {
        "name": {
          "properties": {
            "first": {
              "type": "text"
            }
          }
        },
        "user_id": {
          "type": "keyword"
        }
      }
    }
  }
}

PUT my_index/_mapping/_doc
{
  "properties": {
    "name": {
      "properties": {
        "last": { 
          "type": "text"
        }
      }
    },
    "user_id": {
      "type": "keyword",
      "ignore_above": 100 
    }
  }
}

	Create an index with a `first` field under the `name` Object datatype field, and a `user_id` field.
	Add a `last` field under the `name` object field.
	Update the `ignore_above` setting from its default of 0.

Each mapping parameter specifies whether or not its setting can be updated on an existing field.

Skipping types

edit

Types are being removed from Elasticsearch: in 7.0, the mappings element will no longer take the type name as a top-level key by default. You can already opt in for this behavior by setting include_type_name=false and putting mappings directly under mappings in the index creation call, without specifying a type name.

On indices created on Elasticsearch 5.x, such calls will actually introduce or update mappings for the _doc type. It is recommended to avoid calling the put-mapping API with include_type_name=false on 5.x indices.

Here is an example:

PUT my_index?include_type_name=false
{
  "mappings": {
    "properties": {
      "name": {
        "properties": {
          "first": {
            "type": "text"
          }
        }
      },
      "user_id": {
        "type": "keyword"
      }
    }
  }
}

« Rollover Index Get Mapping »