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:

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"
      }
    }
  }
}