WARNING: Version 5.2 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

› ›

Put Mapping

edit

Put Mapping

edit

The PUT mapping API allows you to add a new type to an existing index, or add new fields to an existing type:

PUT twitter 
{
  "mappings": {
    "tweet": {
      "properties": {
        "message": {
          "type": "text"
        }
      }
    }
  }
}

PUT twitter/_mapping/user 
{
  "properties": {
    "name": {
      "type": "text"
    }
  }
}

PUT twitter/_mapping/tweet 
{
  "properties": {
    "user_name": {
      "type": "text"
    }
  }
}

	Creates an index called `twitter` with the `message` field in the `tweet` mapping type.
	Uses the PUT mapping API to add a new mapping type called `user`.
	Uses the PUT mapping API to add a new field called `user_name` to the `tweet` 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. It has the following format:

PUT /{index}/_mapping/{type}
{ body }

{index} accepts multiple index names and wildcards.
{type} is the name of the type to update.
{body} contains the mapping changes that should be applied.

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": {
    "user": {
      "properties": {
        "name": {
          "properties": {
            "first": {
              "type": "text"
            }
          }
        },
        "user_id": {
          "type": "keyword"
        }
      }
    }
  }
}

PUT my_index/_mapping/user
{
  "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.

Conflicts between fields in different types

edit

Fields in the same index with the same name in two different types must have the same mapping, as they are backed by the same field internally. Trying to update a mapping parameter for a field which exists in more than one type will throw an exception, unless you specify the update_all_types parameter, in which case it will update that parameter across all fields with the same name in the same index.

The only parameters which are exempt from this rule — they can be set to different values on each field — can be found in Fields are shared across mapping types.

For example, this fails:

PUT my_index
{
  "mappings": {
    "type_one": {
      "properties": {
        "text": { 
          "type": "text",
          "analyzer": "standard"
        }
      }
    },
    "type_two": {
      "properties": {
        "text": { 
          "type": "text",
          "analyzer": "standard"
        }
      }
    }
  }
}

PUT my_index/_mapping/type_one 
{
  "properties": {
    "text": {
      "type": "text",
      "analyzer": "standard",
      "search_analyzer": "whitespace"
    }
  }
}

	Create an index with two types, both of which contain a `text` field which have the same mapping.
	Trying to update the `search_analyzer` just for `type_one` throws an exception like `"Merge failed with failures..."`.

But this then running this succeeds:

PUT my_index/_mapping/type_one?update_all_types 
{
  "properties": {
    "text": {
      "type": "text",
      "analyzer": "standard",
      "search_analyzer": "whitespace"
    }
  }
}

Adding the update_all_types parameter updates the text field in type_one and type_two.

« Rollover Index Get Mapping »