How Dynamic Mapping Works
When dynamic mapping is enabled, the default behavior, Elasticsearch inspects the first document containing a previously unseen field and guesses its type: a JSON string becomes both a text field and a keyword sub-field, a JSON number becomes a long or double, a JSON boolean becomes boolean, and an ISO-formatted date string is detected and mapped as date. This is convenient for prototyping but risky in production because the very first document's shape permanently determines the field's type for the life of the index.
Cricket analogy: A young player's first net session determines which coach labels them 'batsman' or 'bowler' for the rest of the academy program, similar to how the first document's field shape permanently sets a field's dynamic type.
# Dynamic mapping in action: the very first document defines the types
curl -X POST "localhost:9200/events/_doc" -H "Content-Type: application/json" -d '
{
"event_name": "Product Launch",
"attendees": 250,
"is_virtual": false,
"scheduled_at": "2026-08-01T09:00:00Z"
}'
# Elasticsearch now infers:
# event_name -> text + keyword sub-field
# attendees -> long
# is_virtual -> boolean
# scheduled_at -> date
Why Explicit Mapping Wins in Production
Explicit mapping means you define the mappings object yourself at index creation time, either through the same PUT call used to create the index or through a separate _mapping API call before any data arrives, and it eliminates ambiguity: a price field can be forced to scaled_float instead of Elasticsearch guessing double from a string, and a status field can be forced to keyword even if the first document happens to look like a date. Explicit mapping also protects against a subtle failure mode called a mapping explosion, where dynamic mapping on highly variable, user-generated field names creates thousands of distinct fields and degrades cluster performance.
Cricket analogy: A team management drawing up a fixed batting order card before the toss, rather than letting the umpire improvise it from who happens to walk out first, mirrors defining explicit mappings up front.
You can combine both approaches: define explicit mappings for known, important fields while leaving dynamic: true for genuinely unpredictable fields, or set dynamic: 'strict' on an object to reject any undeclared field outright rather than silently mapping it.
Controlling Dynamic Behavior
The dynamic setting can be applied at the index, object, or nested field level with three meaningful values: true (default, new fields are added to the mapping automatically), false (new fields are stored in _source and searchable there, but not indexed as mapped fields, so they're not queryable via structured queries), and strict (new fields cause the entire indexing request to be rejected with an error). Choosing strict at the top level for a well-understood schema is a common production safeguard against accidental mapping explosions from typos or unexpected client payloads.
Cricket analogy: A strict dress code enforced at the pavilion gate that turns away anyone not in whites, versus a lenient gate that lets anyone in regardless of attire, mirrors dynamic: strict versus dynamic: true.
A common production incident is the 'mapping explosion': ingesting logs where a field name is dynamically generated per-event (like a raw JSON blob turned into individual fields) can create tens of thousands of unique mapped fields, bloating cluster state and slowing every operation. Set dynamic: false or strict on such objects, or flatten them into a single flattened-type field instead.
- Dynamic mapping infers a field's type from the first document that introduces it, and that type is then permanent.
- Explicit mapping defines field types up front via the mappings object, removing ambiguity and guesswork.
- The dynamic setting can be true (auto-add fields), false (unindexed but stored), or strict (reject unknown fields).
- Explicit mapping protects against mapping explosions caused by highly variable or user-generated field names.
- You can mix approaches: explicit mappings for known fields, dynamic: true for a genuinely unpredictable sub-object.
- The flattened field type is a good alternative for arbitrary nested JSON that would otherwise explode the mapping.
- In production, prefer explicit mappings for well-understood schemas and reserve dynamic mapping for prototyping.
Practice what you learned
1. What determines a field's type under dynamic mapping?
2. What does setting dynamic: 'strict' do?
3. What is a 'mapping explosion'?
4. Which field type is a good alternative for arbitrary nested JSON that would otherwise trigger a mapping explosion?
5. What is the main advantage of explicit mapping over dynamic mapping in production?
Was this page helpful?
You May Also Like
Mapping Types Explained
Understand the core Elasticsearch field data types, text vs keyword, numbers, dates, and objects, and how each shapes search behavior.
Creating an Index
Learn how Elasticsearch indices are created, configured with shards and replicas, and named for reliable, scalable search.
Analyzers and Tokenizers
See how Elasticsearch breaks raw text into searchable terms using character filters, tokenizers, and token filters.