Update mapping API examples

This page provides examples of how to use the update mapping API to modify index mappings after creation.

You can learn how to:

Add a new field to a single index
Update multiple indices at once
Add new properties to an object field
Enable multi-fields for an existing field
Update supported mapping parameters
Change the mapping of a field using reindexing
Rename a field using field aliases

Example with single target

The update mapping API requires an existing data stream or index. The following create index API request creates the publications index with no mapping.

PUT /publications

The following update mapping API request adds title, a new text field, to the publications index.

PUT /publications/_mapping
{
  "properties": {
    "title": { "type": "text" }
  }
}

The update mapping API can be applied to multiple data streams or indices in a single request. For example, you can update mappings for the my-index-000001 and my-index-000002 indices at the same time:


# Create the two indices
PUT /my-index-000001
PUT /my-index-000002
# Update both mappings
PUT /my-index-000001,my-index-000002/_mapping
{
  "properties": {
    "user": {
      "properties": {
        "name": {
          "type": "keyword"
        }
      }
    }
  }
}

Add new properties to an existing object field

You can use the update mapping API to add new properties to an existing object field.

First, create an index with the name object field and an inner first text field:

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "name": {
        "properties": {
          "first": {
            "type": "text"
          }
        }
      }
    }
  }
}

Then, use the update mapping API to add a new inner last text field to the name field:

PUT /my-index-000001/_mapping
{
  "properties": {
    "name": {
      "properties": {
        "last": {
          "type": "text"
        }
      }
    }
  }
}

Add multi-fields to an existing field

Multi-fields let you index the same field in different ways. You can use the update mapping API to update the fields mapping parameter and enable multi-fields for an existing field.

Warning

If an index (or data stream) contains documents when you add a multi-field, those documents will not have values for the new multi-field. You can populate the new multi-field with the update by query API.

To see how this works, try the following example.

Use the create index API to create an index with the city text field:

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "city": {
        "type": "text"
      }
    }
  }
}

Enable a multi-field for city:

PUT /my-index-000001/_mapping
{
  "properties": {
    "city": {
      "type": "text",
      "fields": {
        "raw": {
          "type": "keyword"
        }
      }
    }
  }
}

Change supported mapping parameters for an existing field

Not all mapping parameters are updateable, but some like ignore_above can be changed.

Create an index with ignore_above: 20:

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_id": {
        "type": "keyword",
        "ignore_above": 20
      }
    }
  }
}

Update ignore_above to 100:

PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "keyword",
      "ignore_above": 100
    }
  }
}

Change the mapping of an existing field

You cannot change the field type of an existing field. Instead, create a new index with the desired mapping and reindex your data.

Create an index with a user_id field of type long:

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_id": {
        "type": "long"
      }
    }
  }
}

Index some documents:

POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id": 12345
}

POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id": 12346
}

Create a new index with the user_id field as keyword:

PUT /my-new-index-000001
{
  "mappings": {
    "properties": {
      "user_id": {
        "type": "keyword"
      }
    }
  }
}

Reindex the data:

POST /_reindex
{
  "source": {
    "index": "my-index-000001"
  },
  "dest": {
    "index": "my-new-index-000001"
  }
}

Rename a field

You cannot rename a field directly. Instead, use a field alias.

Create an index with the user_identifier field:

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_identifier": {
        "type": "keyword"
      }
    }
  }
}

Add the user_id alias:

PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "alias",
      "path": "user_identifier"
    }
  }
}