Mapping and the dynamic mapping trap

Key points

• Without an explicit mapping the first document to arrive decides the type of every field it carries.
• A string that looks like 2026-08-03 is mapped as a date, so a later value of unknown fails.
• A field type cannot be changed in place - correcting it means a new index and a full reindex.
• index.mapping.total_fields.limit defaults to 1000, and user-supplied keys will reach it.
• Set dynamic: strict to reject unknown fields, or false to store without indexing.
• An array of objects loses its pairing across objects unless the field is typed as nested.

Example

PUT /events
{
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "status_code": { "type": "short" },
      "created_at":  { "type": "date" },
      "user_id":     { "type": "keyword" },
      "message":     { "type": "text" },
      "metadata":    { "type": "flattened" }
    }
  }
}

Define the mapping before the first document, and always read and write through an alias.