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:

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.