Dynamic Mapping: Risiken erkennen und gezielt kontrollieren

1. Was Dynamic Mapping ist und wie es funktioniert

Dynamic Mapping ist der Mechanismus, mit dem Elasticsearch beim Indexieren eines Dokuments automatisch ein Mapping fuer bisher unbekannte Felder erzeugt. Trifft ein Feld ohne existierende Mapping-Definition ein, analysiert Elasticsearch den JSON-Wert, leitet einen passenden Datentyp ab und erweitert das Mapping des Index um genau dieses Feld. Dieser Mechanismus ist standardmaessig aktiv und macht Elasticsearch am Anfang eines Projekts angenehm einfach zu nutzen, weil kein Mapping vorbereitet werden muss, um erste Dokumente zu indexieren.

Genau diese Bequemlichkeit ist aber auch die Wurzel des Problems, das dieser Artikel behandelt. Dynamic Mapping trifft seine Entscheidungen pro Dokument und ohne Kenntnis der Gesamtstruktur der Daten. Wenn Eingabedaten aus externen Quellen, Benutzereingaben oder sich aendernden APIs stammen, kann Dynamic Mapping unbemerkt Dutzende oder Hunderte neuer Felder pro Tag erzeugen. Die folgenden Abschnitte zeigen, wie die automatische Erkennung im Detail arbeitet, wo die eigentliche Gefahr liegt und mit welchen Mitteln man sie gezielt eindaemmt.

2. Automatische Typerkennung im Detail

Die Typerkennung von Dynamic Mapping folgt festen Regeln. Ein JSON-String wird standardmaessig sowohl als text-Feld mit Analyzer als auch als keyword-Sub-Feld angelegt, damit sowohl Volltextsuche als auch exakte Filterung moeglich sind. Eine JSON-Zahl ohne Dezimalpunkt wird zu long, eine Zahl mit Dezimalpunkt zu float. Ein Boolean-Wert wird zu boolean, ein verschachteltes Objekt zu object. Strings, die einem erkennbaren Datumsmuster entsprechen, werden als date interpretiert, sofern date_detection aktiviert ist, was standardmaessig der Fall ist.

Diese Heuristiken funktionieren fuer viele Faelle gut, scheitern aber regelmaessig an Randfaellen. Eine numerische Produkt-ID mit fuehrenden Nullen wird als Zahl erkannt und verliert dabei die Nullen. Ein String wie "12345" in einem Feld, das eigentlich immer numerisch gemeint war, kann je nach erstem beobachteten Wert inkonsistent typisiert werden. Und ein String, der zufaellig wie ein Datum aussieht, etwa eine Versionsnummer im Format "2024.01", kann durch Dynamic Mapping faelschlich als date-Feld interpretiert werden, was bei allen folgenden Dokumenten mit abweichendem Format zu Indexierungsfehlern fuehrt.

// First document determines the auto-detected mapping
POST /events/_doc
{
  "user_id": "42",
  "event": "login",
  "score": 3.5,
  "occurred_at": "2026-07-24T10:15:00Z"
}

// Elasticsearch infers roughly this mapping:
// user_id     -> text + keyword sub-field
// event       -> text + keyword sub-field
// score       -> float
// occurred_at -> date

3. Das Risiko der Field-Explosion durch unvorhersehbare Daten

Das praktisch groesste Risiko von Dynamic Mapping ist die sogenannte Field-Explosion oder Mapping-Explosion: Wenn eingehende Dokumente eine variable, nicht vorab bekannte Struktur haben, etwa weil ein JSON-Objekt mit einer benutzergenerierten ID als Schluessel verwendet wird, erzeugt Dynamic Mapping fuer jeden einzelnen Schluessel ein eigenes Feld. Ein Event-Tracking-System, das Metadaten als {"attr_" + user_id: value} speichert, kann so pro Tag hunderte neue Felder produzieren, ohne dass jemand aktiv eingreift.

Jedes Feld im Mapping erzeugt zusaetzlichen Overhead in der Cluster-State-Verwaltung, die auf allen Knoten im Speicher gehalten wird. Ein Index mit zehntausenden Feldern verlangsamt Cluster-State-Updates messbar und kann im Extremfall dazu fuehren, dass der gesamte Cluster instabil wird, weil jede Mapping-Aenderung an alle Knoten repliziert werden muss. Elasticsearch begrenzt deshalb standardmaessig die Feldanzahl pro Index auf 1000, aber dieses Limit wird in unkontrollierten Szenarien mit Dynamic Mapping oft einfach erhoeht, statt das eigentliche Problem zu beheben.

Ein zweites, subtileres Risiko: Jedes automatisch erzeugte Feld bleibt dauerhaft im Mapping bestehen, selbst wenn es nur in einem einzigen Dokument vorkam. Da Feldtypen unveraenderlich sind, kann ein einzelnes fehlerhaft typisiertes Dokument, das ueber Dynamic Mapping ein falsches Feld anlegt, spaeter korrekte Dokumente mit demselben Feldnamen, aber anderem beabsichtigtem Typ, zum Scheitern bringen.

4. dynamic: false, unbekannte Felder ignorieren

Die einfachste Kontrollmassnahme ist die Einstellung "dynamic": false auf Index- oder Objekt-Ebene. Mit dieser Einstellung werden Felder, die nicht explizit im Mapping definiert sind, beim Indexieren stillschweigend ignoriert: Sie werden im _source-Dokument gespeichert und sind damit weiterhin abrufbar, aber sie werden nicht indexiert und stehen fuer Suchen, Filter oder Aggregationen nicht zur Verfuegung. Das ist die richtige Wahl, wenn ein Teil der Dokumentstruktur variabel und nicht durchsuchbar sein muss, etwa ein generisches "extra_data"-Objekt fuer Debug-Informationen.

"dynamic": false kann granular pro Objektfeld gesetzt werden, sodass der Grossteil des Dokuments weiterhin von Dynamic Mapping profitiert, waehrend ein einzelner problematischer Bereich abgeschottet wird. Diese gezielte Anwendung ist in der Praxis oft die bessere Wahl als eine pauschale Deaktivierung auf Index-Ebene, weil sie das Risiko der Field-Explosion eindaemmt, ohne die Bequemlichkeit von Dynamic Mapping fuer den restlichen, gut strukturierten Teil der Daten zu opfern.

PUT /events
{
  "mappings": {
    "properties": {
      "user_id": { "type": "keyword" },
      "event":   { "type": "keyword" },
      "score":   { "type": "float" },
      "metadata": {
        "type": "object",
        "dynamic": false
      }
    }
  }
}

// Any key inside "metadata" is stored but never indexed or searchable
POST /events/_doc
{
  "user_id": "42",
  "event": "login",
  "score": 3.5,
  "metadata": { "session_hash_abc123": "value", "custom_flag_xyz": true }
}

5. dynamic: strict, unbekannte Felder ablehnen

Wo "dynamic": false unbekannte Felder still ignoriert, geht "dynamic": "strict" einen Schritt weiter: Ein Dokument mit einem nicht im Mapping definierten Feld wird komplett abgelehnt und der Index-Request schlaegt mit einem klaren Fehler fehl. Das ist die richtige Einstellung fuer Indizes, bei denen ein unerwartetes Feld auf einen Bug in der schreibenden Anwendung hindeutet und lieber sofort auffallen soll, statt still im Hintergrund neue Felder anzuhaeufen.

In der Praxis eignet sich strict besonders fuer Systeme mit klar definiertem, vertraglich fixiertem Datenschema, etwa Log-Formate, die von einer festen Menge interner Services erzeugt werden. Der Nachteil: Jede legitime Erweiterung des Datenmodells erfordert vorab eine explizite Mapping-Aenderung, bevor neue Daten geschrieben werden koennen. Das erhoeht den Koordinationsaufwand zwischen Anwendungsentwicklung und Suchinfrastruktur, verhindert aber zuverlaessig, dass Dynamic Mapping unkontrolliert wuchert.

6. Dynamic Templates: automatische Erkennung gezielt lenken

Dynamic Templates sind der differenzierteste Kontrollmechanismus: Statt Dynamic Mapping komplett zu deaktivieren, definieren sie Regeln, nach denen neu erkannte Felder einem bestimmten Typ zugeordnet werden. Eine Regel kann etwa festlegen, dass alle Felder, deren Name auf _id endet, automatisch als keyword statt als text indexiert werden, unabhaengig vom erkannten JSON-Typ. Das kombiniert die Flexibilitaet automatischer Felderkennung mit der Kontrolle expliziter Typwahl.

Dynamic Templates werden nach Kriterien wie match_mapping_type (der von Elasticsearch erkannte JSON-Typ), match (ein Muster fuer den Feldnamen) oder path_match (ein Muster fuer den vollen Feldpfad in verschachtelten Objekten) ausgewertet. Mehrere Templates werden in Reihenfolge geprueft, das erste passende gewinnt. Diese Technik ist besonders wertvoll bei teilstrukturierten Daten, bei denen die grobe Struktur bekannt ist, aber einzelne Feldnamen variieren, etwa bei Custom-Attributen in einem Produktkatalog.

PUT /catalog
{
  "mappings": {
    "dynamic_templates": [
      {
        "ids_as_keyword": {
          "match": "*_id",
          "mapping": { "type": "keyword" }
        }
      },
      {
        "strings_no_analysis": {
          "match_mapping_type": "string",
          "match": "*_code",
          "mapping": { "type": "keyword" }
        }
      },
      {
        "unmapped_json_as_flattened": {
          "path_match": "custom_attributes.*",
          "mapping": { "type": "flattened" }
        }
      }
    ]
  }
}

7. Feldlimits als zusaetzliches Sicherheitsnetz

Neben inhaltlicher Kontrolle durch dynamic-Einstellungen und Dynamic Templates bietet Elasticsearch harte Grenzwerte als letztes Sicherheitsnetz. Die Index-Einstellung index.mapping.total_fields.limit begrenzt die Gesamtzahl der Felder pro Index und steht standardmaessig auf 1000. Wird dieses Limit erreicht, schlagen weitere Indexierungsversuche mit neuen Feldern fehl, was als klares Warnsignal dient, dass Dynamic Mapping unkontrolliert Felder erzeugt.

Zusaetzlich begrenzt index.mapping.depth.limit die maximale Verschachtelungstiefe von Objekten und index.mapping.nested_fields.limit die Anzahl der nested-Felder pro Index. Diese Limits sollten nicht als Loesung fuer eine schlecht kontrollierte Datenstruktur missverstanden werden, sondern als letzte Verteidigungslinie, die einen Fehler sichtbar macht, bevor er den ganzen Cluster destabilisiert. Ein Limit stillschweigend zu erhoehen, ohne die Ursache der Field-Explosion zu beheben, verschiebt das Problem nur in die Zukunft und macht es dort groesser.

8. Field-Explosion erkennen, bevor sie zum Problem wird

Eine wachsende Feldanzahl bleibt oft lange unbemerkt, weil sie sich nicht in offensichtlichen Fehlermeldungen zeigt, sondern schleichend die Cluster-Performance verschlechtert. Die Mapping-API liefert die aktuelle Feldanzahl direkt: GET /index_name/_mapping kann per Skript geparst und die Anzahl der Feld-Schluessel gezaehlt werden. Regelmaessiges Monitoring dieser Kennzahl, etwa taeglich per Cron-Job, macht einen ploetzlichen Anstieg sichtbar, bevor das Feldlimit erreicht wird.

Ein zusaetzliches Warnsignal ist die Groesse der Cluster-State-Antwort ueber GET /_cluster/state, die bei sehr vielen Feldern spuerbar waechst und laenger zum Uebertragen braucht. In produktiven Systemen lohnt sich ein Alert, der bei Ueberschreiten eines Schwellwerts, etwa 500 von 1000 erlaubten Feldern, automatisch benachrichtigt. So bleibt Zeit, die Ursache zu untersuchen und ein Dynamic Template oder eine dynamic: false-Regel nachzuruesten, bevor Dynamic Mapping den Cluster tatsaechlich gefaehrdet.

# Count fields currently defined in an index mapping
curl -s "https://localhost:9200/events/_mapping" -u elastic:changeme \
  | jq '[.. | objects | select(has("type"))] | length'

# Check the configured field limit for an index
curl -s "https://localhost:9200/events/_settings/index.mapping.total_fields.limit?pretty" \
  -u elastic:changeme

9. Eine pragmatische Dynamic-Mapping-Strategie

In der Praxis bewaehrt sich eine Kombination aus mehreren Schutzebenen statt einer einzelnen Massnahme. Fuer den Kernbereich eines Dokuments, dessen Struktur bekannt und stabil ist, empfiehlt sich explizites Mapping ohne Dynamic Mapping. Fuer klar begrenzte, aber inhaltlich variable Bereiche wie Custom-Attribute eignen sich Dynamic Templates mit klaren Namensmustern. Fuer wirklich unstrukturierte Zusatzdaten, die nie durchsucht werden muessen, ist dynamic: false auf Objekt-Ebene die richtige Wahl, kombiniert mit total_fields.limit als letztem Sicherheitsnetz.

dynamic: strict lohnt sich vor allem in Systemen mit hoher Datenqualitaetsanforderung, bei denen ein unerwartetes Feld tatsaechlich einen Bug in der schreibenden Anwendung bedeutet. Der Typ flattened, seit Elasticsearch 7.3 verfuegbar, ist eine oft uebersehene Alternative fuer variable Key-Value-Strukturen: Er indexiert ein ganzes Objekt als einen einzigen Feld-Eintrag im Mapping, unabhaengig davon, wie viele Schluessel es enthaelt, und verhindert damit Field-Explosion strukturell, wenn auch mit eingeschraenkten Query-Moeglichkeiten gegenueber vollem Dynamic Mapping.

Fuer Magento-Betreiber mit dem Elasticsearch-Katalogindex ist relevant, dass Custom-Attribute mit dynamischen Werten, etwa konfigurierbare technische Spezifikationen, dieselbe Field-Explosion-Gefahr bergen wie in einem selbst gebauten Index. Wer regelmaessig neue Produktattribute anlegt, sollte periodisch pruefen, wie viele Felder der generierte Katalogindex tatsaechlich enthaelt, statt sich blind auf die Magento-Standardkonfiguration zu verlassen.

Diese Gegenueberstellung zeigt, dass keine der Einstellungen universell richtig ist. Die Wahl haengt davon ab, wie vorhersehbar die Datenstruktur ist und wie kritisch Suchbarkeit fuer den jeweiligen Datenbereich ist. Eine bewusste, dokumentierte Entscheidung pro Index ist in jedem Fall besser als die unreflektierte Beibehaltung des Standardverhaltens von Dynamic Mapping.

10. Zusammenfassung

Dynamic Mapping ist ein nuetzliches Werkzeug fuer schnellen Einstieg, birgt aber bei variablen oder externen Datenquellen ein reales Risiko: unkontrolliertes Wachstum der Feldanzahl bis hin zur Field-Explosion, die Cluster-Performance und Stabilitaet gefaehrdet. Die automatische Typerkennung folgt festen, aber nicht immer passenden Heuristiken, und weil Feldtypen unveraenderlich sind, bleibt ein einmal falsch erzeugtes Feld dauerhaft im Mapping bestehen.

Die Kontrollmechanismen dynamic: false, dynamic: strict und Dynamic Templates erlauben, das Verhalten gezielt pro Bereich eines Dokuments zu steuern, statt Dynamic Mapping pauschal ein- oder auszuschalten. Feldlimits und regelmaessiges Monitoring der Feldanzahl bilden das letzte Sicherheitsnetz. Wer diese Werkzeuge kombiniert, behaelt die Bequemlichkeit automatischer Felderkennung dort, wo sie sinnvoll ist, und verhindert die typische Field-Explosion dort, wo Eingabedaten unvorhersehbar sind.

11. FAQ: Dynamic Mapping in Elasticsearch