Elasticsearch Add Field to Existing Index: The Put Mapping API

To add a field to an existing Elasticsearch index, send PUT /<index>/_mapping with the new field definition. The change is applied immediately and does not require closing the index or reindexing existing documents. What you cannot do this way is change the type of an existing field, modify an analyzer on an indexed text field, or remove fields. Those changes require a reindex into a new index. The put mapping API works on Elasticsearch 7.x, 8.x, and 9.x with identical syntax.

This guide covers what can be added in place, what cannot, runtime fields as the escape hatch for type changes you wish you had made differently, and how the put mapping API behaves on data streams.

The Basic API

PUT /products/_mapping
{
  "properties": {
    "in_stock": { "type": "boolean" }
  }
}

That adds a single field to the existing products index. Existing documents are not rewritten; they simply do not have the new field. Documents indexed after the mapping change can include the field, and queries on it will find them.

You can add multiple fields at once:

PUT /products/_mapping
{
  "properties": {
    "in_stock":  { "type": "boolean" },
    "warehouse": { "type": "keyword" },
    "rating":    { "type": "float" }
  }
}

What You Can Add Without Reindexing

• New top-level fields. Any field that does not exist yet, of any type.
• New properties on an existing object field. If address is mapped as an object, you can add address.country later.
• New sub-fields on a text field via fields. For example, adding a .keyword sub-field to an existing text field. New documents will populate it; existing documents will not until reindexed.
• Field aliases. Map a new logical name to an existing field with { "type": "alias", "path": "old_name" }.
• Mapping parameters with update semantics. A small set of parameters can be changed in place, such as ignore_above on a keyword field. Most cannot.

What You Cannot Change in Place

The mapping for an existing field is largely immutable once data has been indexed against it. Specifically:

• Changing a field's type (for example, text to keyword, or long to integer). The only way to do this is to create a new index with the correct mapping and reindex.
• Changing the analyzer on an indexed text field. Same rule: reindex.
• Removing a field. Mappings are append-only. You can stop sending the field in new documents, but the definition stays.
• Adding a sub-field that gets populated retroactively. New sub-fields apply only to new writes. Existing documents need a reindex (or an _update_by_query) to populate them.

If you try one of these in place, Elasticsearch returns illegal_argument_exception: mapper [field_name] cannot be changed.

Runtime Fields: The In-Place Escape Hatch

Runtime fields are the modern workaround for "I wish I had mapped this differently." They are evaluated at query time from _source rather than at index time. Adding a runtime field does not require reindexing and works on existing data.

PUT /products/_mapping
{
  "runtime": {
    "price_in_cents": {
      "type": "long",
      "script": {
        "source": "emit((long)(doc['price'].value * 100))"
      }
    }
  }
}

Now queries can use price_in_cents as if it were a regular field. The trade-off: runtime fields are evaluated per query, so they cost CPU at search time rather than at index time. For high-throughput queries on a field, eventually reindex into a properly mapped field. For occasional analyses and ad-hoc fixes, runtime fields are exactly the right tool.

See the runtime fields guide for the full breakdown.

Behavior on Data Streams

By default, a put mapping call on a data stream updates the mapping on every backing index, including historical ones. To restrict the change to only the current write index, pass write_index_only=true:

PUT /logs-app/_mapping?write_index_only=true
{
  "properties": {
    "trace_id": { "type": "keyword" }
  }
}

For consistent long-term shape across all backing indices, update the index template that backs the data stream so that future backing indices pick up the new field automatically.

Dynamic Mapping Interaction

If dynamic is set to true (the default), new fields appearing in indexed documents get auto-mapped without an explicit put mapping call. Convenient, occasionally hazardous: a typo in a field name produces a permanent new mapping entry that you cannot remove without reindexing.

For production indices, prefer dynamic: strict and add fields explicitly via the put mapping API. For exploratory work, dynamic: runtime adds new fields as runtime fields, which can be promoted to properly indexed fields later.

PUT /products/_mapping
{
  "dynamic": "strict"
}

You can also flip dynamic mode on an existing index this way without reindexing.

Common Errors

• illegal_argument_exception: mapper [field] cannot be changed: you are trying to change the type or other immutable parameter of an existing field. Reindex.
• mapper_parsing_exception: the mapping body is malformed, often a typo in a type name (keword instead of keyword) or a missing properties wrapper.
• Limit of total fields [1000] in index [...] has been exceeded: you have hit the index.mapping.total_fields.limit cap. Increase the limit, or, better, audit for field explosion caused by dynamic mapping of unconstrained nested objects.
• index_closed_exception: the index is closed. Open it before changing mappings.

How Pulse Helps With Schema Evolution

Mapping changes are deceptively easy in development and disproportionately painful in production. Most "we cannot change this field type" incidents trace back to a hasty dynamic mapping decision a year earlier. Pulse tracks mapping growth and drift on Elasticsearch and OpenSearch clusters and flags indices approaching the field limit, indices with high-cardinality dynamic mappings, and fields that are likely candidates for type changes (numeric strings mapped as text, keyword fields without ignore_above). Connect your cluster to Pulse and let it surface schema-evolution risk before it becomes a reindex.

Frequently Asked Questions

Q: Will existing documents be updated when I add a field?

No. Existing documents keep their stored _source as-is. New documents can include the field. If you need existing documents to have a populated value, use update by query with a script or reindex into a new index with the field populated.

Q: Can I add a sub-field to an existing text field?

You can add the sub-field definition. New writes will populate it. Existing documents will not, because the sub-field is built at index time. To populate it for existing data, run an _update_by_query (which forces a re-index of each document) or reindex into a new index.

Q: What is the difference between updating a mapping and updating settings?

Mappings define field types and behavior. Settings define index-level parameters like shard count, refresh interval, and ILM policy. Different APIs, different rules. Mappings via PUT /<index>/_mapping, settings via PUT /<index>/_settings.

Q: Why can't I change a field type once data has been indexed?

The indexed representation depends on the type. text fields are tokenized and stored as an inverted index; keyword fields are stored as raw tokens; numeric fields use a BKD tree. Changing the type means re-encoding every document, which is what reindex does.

Q: How do I see the current mapping?

GET /<index>/_mapping
GET /<index>/_mapping/field/<field-name>

The second form is useful when an index has a large mapping and you only care about one field.

Q: Can I add a vector field to an existing index?

Yes. dense_vector fields can be added with put mapping. The same rule applies: only new documents have the field populated, and existing documents will need a reindex (or an update-by-query that emits the vector) to gain values.