Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 43 ยท Mappings and Data Modeling

Dynamic Mapping and Index Templates

See how Elasticsearch guesses field types, how dynamic true, false and strict differ, and how dynamic, component and composable index templates help.

You can index a document into an index that does not exist, with no mapping at all, and Elasticsearch will happily create both. It looks at each JSON value, guesses a field type, and adds that field to the mapping. This is dynamic mapping. It is wonderful for experiments and risky in production, because the guess is made from the first value it sees and then it is fixed.

In this lesson you will learn the exact guessing rules, the three dynamic modes, dynamic templates that steer the guesses, and index templates that apply a mapping automatically whenever a matching index is created. A JavaScript stand-in infers mappings from documents so you can see the pitfalls yourself. The real requests are read-only.

The default type guesses

JSON value Mapped as
true / false boolean
whole number long
decimal number float
string that looks like a date (default formats) date
any other string text with a keyword sub-field (ignore_above: 256)
object object with its own properties
array the type of its first non-null value
null or [] nothing is mapped

Two details matter. Numeric strings stay text: "price": "12.50" becomes a text field unless you turn on numeric_detection. Dates are detected in strings such as "2025-03-01", which is usually what you want, until a free-text field happens to contain a date-shaped value in the first document.

JS A mapping inferred from documents

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Look at price. The first document had 59, so it became long. The later 9.99 would be accepted and truncated in the index to fit a long (the original stays in _source), and "12.50" would be coerced. The mapping never changes after the first guess. That is the main pitfall: the first document decides the type for everyone after it.

The three dynamic modes

The dynamic parameter, set on the mapping or on any object inside it, controls unknown fields:

HTTP
PUT /orders
{
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "id":    { "type": "keyword" },
      "total": { "type": "scaled_float", "scaling_factor": 100 },
      "meta": {
        "type": "object",
        "dynamic": true
      }
    }
  }
}
  • true (default): new fields are added to the mapping automatically.
  • false: new fields are kept in _source but not indexed, so you cannot search them. No error.
  • strict: a document with an unknown field is rejected with an error.
  • runtime: new fields become runtime fields (computed at query time, never indexed). Handy for exploring.

Here the top level is strict, so a typo like "totl" fails loudly, while meta stays open for free-form extras. Choose strict for core business data and false or true only where the shape really varies.

JS true versus false versus strict

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Dynamic templates

A dynamic template is a rule that says "when a new field matches this condition, map it like that". It replaces the default guess for matching fields, and is how you avoid, for example, mapping every string as both text and keyword.

HTTP
PUT /events
{
  "mappings": {
    "dynamic_templates": [
      {
        "ids_are_keywords": {
          "match": "*_id",
          "mapping": { "type": "keyword" }
        }
      },
      {
        "strings_as_keywords": {
          "match_mapping_type": "string",
          "mapping": { "type": "keyword", "ignore_above": 256 }
        }
      }
    ]
  }
}

Templates are checked in order and the first match wins. You can match on the detected JSON type (match_mapping_type), on the field name (match, unmatch, with wildcards or regular expressions) and on the full dotted path (path_match, path_unmatch). With the rules above, user_id becomes keyword by the first rule, and any other string becomes keyword by the second, with no analyzed copy.

Index templates

Dynamic templates live inside one index. An index template applies settings and mappings to every new index whose name matches a pattern, which is essential for daily log indexes and data streams. Modern Elasticsearch uses composable templates built from reusable component templates:

HTTP
PUT /_component_template/common-settings
{
  "template": {
    "settings": { "number_of_shards": 1, "number_of_replicas": 1 }
  }
}

PUT /_component_template/log-fields
{
  "template": {
    "mappings": {
      "properties": {
        "@timestamp": { "type": "date" },
        "level":      { "type": "keyword" },
        "message":    { "type": "text" }
      }
    }
  }
}

PUT /_index_template/app-logs
{
  "index_patterns": ["app-logs-*"],
  "composed_of": ["common-settings", "log-fields"],
  "priority": 200,
  "template": {
    "mappings": { "dynamic": "strict" }
  }
}

Create app-logs-2025.03.01 and it gets all three pieces. Points to remember:

  • Component templates are merged in the order of composed_of; the template's own template section is applied last, so it wins.
  • If two index templates match the same name, the one with the higher priority is used. Overlapping patterns with equal priority are an error.
  • A template affects only new indexes. Existing ones are not changed.
  • The older "legacy" _template API still exists but is deprecated; use _index_template.
  • You can test a template without creating anything: POST /_index_template/_simulate_index/app-logs-2025.03.01.

Practical guidance

  1. Explore with dynamic mapping, then copy the generated mapping (GET /index/_mapping), fix it and use it as your explicit mapping.
  2. Set strict on indexes whose shape you control, and add a dynamic template for the parts that vary.
  3. Make IDs, codes and enumerations keyword, never numbers or analyzed text.
  4. Put shared settings and fields in component templates so every index family stays consistent.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. The first document has "price": 59 and a later one has "price": 9.99. What type does dynamic mapping give price?

    The first value decides: 59 is a whole number, so price becomes long. The mapping is not revised for later documents.
  2. 2. With "dynamic": "false", what happens to a field that is not in the mapping?

    false keeps the data in _source without indexing it. Only strict rejects the document.
  3. 3. Two dynamic templates both match a new field. Which one is used?

    Dynamic templates are evaluated in order and the first match wins, so put specific rules before general ones.
  4. 4. Does changing an index template update indexes that already exist?

    Templates are used at index creation time. To change existing indexes you update their mappings or reindex.

Summary

  • Dynamic mapping guesses a type from the first value of each field, and the guess is permanent.
  • Numeric strings stay text, decimals become float, date-like strings become date.
  • dynamic can be true, false, strict or runtime; use strict for data you control.
  • Dynamic templates map new fields by type, name or path, first match wins.
  • Composable index templates built from component templates configure every new index matching a pattern, by priority.

Next: Objects, Arrays and Nested Fields.