Preventing Mapping Explosion in Elasticsearch: Strategies and Examples

1. What is Mapping “Explosion”?

Elasticsearch mapping has dynamic set to true by default, meaning it automatically infers field types from incoming data, which can lead to an uncontrolled increase in the number of fields.

When the number of fields exceeds the default limit (index.mapping.total_fields.limit, default 1000), performance degrades and memory issues arise, especially under high load.

2. Problems Caused by Mapping Explosion

“We have a wide table with 2000+ fields, but Elasticsearch default limit is 1000, causing memory and performance problems. How to solve?”

If sub‑fields keep expanding, the mapping “explodes”. Example request shows many nested fields being created.

POST dynamic-mapping-test/_doc
{
  "message": "hello",
  "transaction": {
    "user": "hey",
    "amount": 3.14,
    "field3": "hey there, new field",
    "field4": {
      "sub_user": "a sub field",
      "sub_amount": "another sub field",
      ...
    }
  }
}

All string fields are mapped as text+keyword, wasting memory and disk even if never queried.

3. How to Avoid Mapping Explosion

First, clarify business requirements to avoid large schema changes later.

Second, model fields according to future usage.

3.1 Solution 1: Set dynamic to strict

With dynamic: strict, any field not defined in the mapping is rejected.

DELETE dynamic-mapping-test
PUT dynamic-mapping-test
{
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "message": { "type": "text" },
      "transaction": {
        "properties": {
          "user": { "type": "keyword" },
          "amount": { "type": "long" }
        }
      }
    }
  }
}
POST dynamic-mapping-test/_doc
{
  "message": "hello",
  "transaction": { "user": "hey", "amount": 3.14, "field3": "hey there, new field" }
}

Attempting to index “field3” results in an error.

When the mapping is finalized and will not change, strict is safe.

3.2 Solution 2: Set dynamic to false

dynamic:false allows unknown fields to be indexed but they are not searchable or aggregatable; they only appear in _source.

PUT dynamic-mapping-disabled
{
  "mappings": {
    "dynamic": "false",
    "properties": { "message": { "type": "text" } }
  }
}
POST dynamic-mapping-disabled/_bulk
{ "index": { "_id": 1 } }
{ "title": "elasticsearch is very good!" }

Mapping after indexing shows only the defined fields.

Search and aggregation on “title” return no hits.

3.3 Solution 3: Set dynamic to runtime

runtime fields act as schema‑on‑read: they do not consume storage but may slow queries.

DELETE dynamic-mapping-runtime
PUT dynamic-mapping-runtime
{
  "mappings": {
    "dynamic": "runtime",
    "properties": {
      "message": { "type": "text" },
      "transaction": {
        "properties": {
          "user": { "type": "keyword" },
          "amount": { "type": "long" }
        }
      }
    }
  }
}
POST dynamic-mapping-runtime/_doc
{
  "message": "hello",
  "transaction": { ... }
}

Runtime fields can be queried, e.g., term query on a sub‑field.

Useful when the exact document structure is unknown, balancing flexibility and performance.

4. Summary

Each approach has advantages and drawbacks; choose based on business needs.

Mode

Pros

Cons

strict

Fields must be explicitly defined

Undefined fields are rejected

false

All fields can be written

Undefined fields cannot be searched or aggregated

runtime

Flexible, no storage overhead

Potentially slower query performance