Mapping limit settings

Use the following settings to limit the number of field mappings (created manually or dynamically) and prevent documents from causing a mapping explosion:

index.mapping.total_fields.limit Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

The maximum number of fields in an index. Field and object mappings, field aliases, and mapped runtime fields all count towards this limit. The default value is 1000. Beyond this limit, Elasticsearch returns the error Limit of total fields [X] has been exceeded.

Important

The limit is in place to prevent mappings and searches from becoming too large. Higher values can lead to performance degradations and memory issues, especially in clusters with a high load or few resources.

If you increase this setting, we recommend you also increase the indices.query.bool.max_clause_count setting, which limits the maximum number of clauses in a query.

Tip

If your field mappings contain a large, arbitrary set of keys, consider using the flattened data type, or setting the index setting index.mapping.total_fields.ignore_dynamic_beyond_limit to true.

The index.mapping.total_fields.limit setting counts all mappers, not just leaf fields. This includes:

• Object mappers: Each level in a dotted field path counts separately
• Field mappers: Leaf fields like keyword, text, long, etc.
• Multi-fields: Each sub-field (e.g., .keyword, .raw) counts individually
• Field aliases: Each alias counts as one mapper
• Runtime fields: Each runtime field counts towards the limit

Metadata fields (_id, _source, _routing, etc.) do not count towards this limit.

For a field path like host.os.name, Elasticsearch creates three mappers:

• host (object mapper)
• host.os (object mapper)
• host.os.name (field mapper)

A common mistake is counting only leaf fields (fields with a type property). This undercounts because object mappers have properties instead of type.

{
  "mappings": {
    "properties": {
      "host": {
        "properties": {
          "name": { "type": "keyword" }
        }
      },
      "message": {
        "type": "text",
        "fields": {
          "keyword": { "type": "keyword" }
        }
      }
    }
  }
}

This mapping counts as 4 mappers:

• host (object mapper)
• host.name (field mapper)
• message (field mapper)
• message.keyword (multi-field)

Each multi-field counts separately. A text field with multiple sub-fields can quickly add up:

{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": {
          "keyword": { "type": "keyword" },
          "raw": { "type": "keyword", "index": false }
        }
      }
    }
  }
}

This mapping counts as 3 mappers:

• title (field mapper)
• title.keyword (multi-field)
• title.raw (multi-field)

Runtime fields also count towards the limit:

{
  "mappings": {
    "properties": {
      "timestamp": { "type": "date" }
    },
    "runtime": {
      "day_of_week": {
        "type": "keyword",
        "script": {
          "source": "emit(doc['timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
        }
      }
    }
  }
}

This mapping counts as 2 mappers:

• timestamp (field mapper)
• day_of_week (runtime field)

Field aliases count towards the limit:

{
  "mappings": {
    "properties": {
      "user_id": { "type": "keyword" },
      "user": {
        "type": "alias",
        "path": "user_id"
      }
    }
  }
}

This mapping counts as 2 mappers:

• user_id (field mapper)
• user (field alias)

The subobjects setting prevents the creation of intermediate object mappers. With subobjects: false, dotted field names are stored as literal strings rather than creating nested objects.

{
  "mappings": {
    "subobjects": false,
    "properties": {
      "host.os.name": { "type": "keyword" }
    }
  }
}

This creates only 1 mapper instead of 3, because host.os.name is treated as a literal field name rather than a nested path.

For indices with deeply nested fields (such as ECS-style mappings), using subobjects: false can significantly reduce the mapper count.

index.mapping.total_fields.ignore_dynamic_beyond_limit Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

This setting determines what happens when a dynamically mapped field would exceed the total fields limit. When set to false (the default), the index request of the document that tries to add a dynamic field to the mapping will fail with the message Limit of total fields [X] has been exceeded. When set to true, the index request will not fail. Instead, fields that would exceed the limit are not added to the mapping, similar to dynamic: false. The fields that were not added to the mapping will be added to the _ignored field. The default value is false.

index.mapping.depth.limit

The maximum depth for a field, which is measured as the number of inner objects. For instance, if all fields are defined at the root object level, then the depth is 1. If there is one object mapping, then the depth is 2, etc. Default is 20.

index.mapping.nested_fields.limit

The maximum number of distinct nested mappings in an index. The nested type should only be used in special cases, when arrays of objects need to be queried independently of each other. To safeguard against poorly designed mappings, this setting limits the number of unique nested types per index. Default is 100.

index.mapping.nested_parents.limit

The maximum number of nested fields that act as parents of other nested fields. Each nested parent requires its own in-memory parent bitset. Root-level nested fields share a parent bitset, but nested fields under other nested fields require additional bitsets. This setting limits the number of unique nested parents to prevent excessive memory usage. Default is 50.

index.mapping.nested_objects.limit

The maximum number of nested JSON objects that a single document can contain across all nested types. This limit helps to prevent out of memory errors when a document contains too many nested objects. Default is 10000.

index.mapping.array_objects.limit Stack 9.5+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.5 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

The maximum cumulative number of JSON object elements that a single document can contain across all arrays. The count spans every nested and sibling array, so splitting a payload across multiple arrays cannot bypass the limit. This setting guards against "poison documents" whose arrays contain a very large number of objects, which can cause excessive memory consumption during parsing and dynamic mapping materialization. The limit is enforced on the document source at parse time, before mapping is applied: it counts JSON object elements inside arrays, not mappers, and applies whether the surrounding array is mapped (for example as object or nested) or unmapped. Field types that consume an entire array as a single value (for example completion) are not affected. Default is 50000. The minimum value is 1. To effectively disable the limit, set it to 9223372036854775807 (Long.MAX_VALUE).

index.mapping.field_name_length.limit

Setting for the maximum length of a field name. This setting isn’t really something that addresses mappings explosion but might still be useful if you want to limit the field length. It usually shouldn’t be necessary to set this setting. The default is okay unless a user starts to add a huge number of fields with really long names. Default is Long.MAX_VALUE (no limit).

index.mapping.field_name_length.ignore_dynamic_beyond_limit Stack 9.3+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.3 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

This setting determines what happens when a the name of a dynamically mapped field would exceed the configured maximum length. When set to false (the default), the index request of the document that tries to add a dynamic field to the mapping will fail with the message Field name [x] is longer than the limit of [y] characters. When set to true, the index request will not fail. Instead, fields that would exceed the limit are not added to the mapping, similar to dynamic: false. The fields that were not added to the mapping will be added to the _ignored field. The default value is false.

index.mapping.dimension_fields.limit

(Dynamic, integer) Maximum number of time series dimensions for the index. Defaults to 32768.

index.mapping.non_indexed_field.max_value_length Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

(Byte value) Maximum size of a single value in a non-indexed keyword or flattened field in a columnar index mode. For a flattened field the size covers the key and the value together. Fields that are indexed and all fields in other index modes, keep Lucene's term limit of 32766 bytes. Defaults to 1mb. The minimum value is 32766b and the maximum is 2147483647b. You can only set this setting in a columnar index mode, when you create the index. You cannot change it later.