How to Update Mapping in Elasticsearch: Syntax and Examples

In Elasticsearch, you cannot directly update existing mapping fields but can add new fields using the PUT /index/_mapping API. To change existing field types, you must create a new index with the desired mapping and reindex your data.

Syntax

To add new fields to an existing mapping, use the PUT /{index}/_mapping API with the new field definitions inside the properties object.

Example parts:

• {index}: the name of your index
• _mapping: the API endpoint to update mapping
• properties: JSON object defining new fields and their types

json

PUT /my_index/_mapping
{
  "properties": {
    "new_field": {
      "type": "text"
    }
  }
}

Example

This example adds a new field called new_field of type text to the existing my_index index mapping.

json

PUT /my_index/_mapping
{
  "properties": {
    "new_field": {
      "type": "text"
    }
  }
}

Output

{
  "acknowledged": true
}

Common Pitfalls

Elasticsearch does not allow changing the type of an existing field directly. Trying to update an existing field's type will cause an error.

To change a field type, create a new index with the desired mapping and reindex your data.

json

PUT /my_index/_mapping
{
  "properties": {
    "existing_field": {
      "type": "keyword"  
    }
  }
}

// This will fail if 'existing_field' already exists with a different type.

Output

{
  "error": {
    "type": "illegal_argument_exception",
    "reason": "Mapper for [existing_field] conflicts with existing mapping"
  },
  "status": 400
}

Quick Reference

Action	API Endpoint	Notes
Add new field	PUT /{index}/_mapping	Can add new fields anytime
Change existing field type	Not supported	Must create new index and reindex
View mapping	GET /{index}/_mapping	Check current mapping structure

Key Takeaways

You can add new fields to an existing Elasticsearch mapping using PUT /{index}/_mapping.

You cannot change the type of an existing field; reindexing with a new mapping is required.

Always check current mapping with GET /{index}/_mapping before updates.

Attempting to change existing field types causes errors.

Plan your mapping carefully to avoid costly reindexing.