Loading

Update mapping API examples

Elastic Stack Serverless

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

You can learn how to:

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

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

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

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

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

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