Der ultimative Leitfaden zur Verwaltung von Elasticsearch-Indizes über API-Befehle

Die Verwaltung von Elasticsearch-Indizes über die API ist alltägliche Arbeit, aber auch eine Quelle vieler teurer Fehler. Ein schlechtes Mapping kann einen Reindex erzwingen. Ein Wildcard-Löschvorgang kann mehr entfernen als beabsichtigt. Eine Replikat-Einstellung, die in der Entwicklung sinnvoll war, kann die Produktion nach einem Deployment gelb hinterlassen.

Ein Elasticsearch-Index ist nicht nur ein Bucket für JSON-Dokumente. Er hat Mappings, Einstellungen, Aliase, Shard-Anzahlen, Replikat-Anzahlen, Analyzer und Lifecycle-Verhalten. Sie müssen nicht jede API auswendig lernen, um ihn gut zu verwalten, aber Sie brauchen eine sorgfältige Routine: Indizes absichtlich erstellen, überprüfen, was Elasticsearch tatsächlich erstellt hat, nur die Einstellungen aktualisieren, die sicher geändert werden können, und mit Schutzmaßnahmen löschen.

Die folgenden Beispiele verwenden Kibana Dev Tools-ähnliche Anfragen. Wenn Sie curl bevorzugen, gelten dieselben Pfade und JSON-Bodies gegen http://host:9200.

Was ein Index enthält

Ein Index ist ein logischer Namespace für Dokumente. Unter der Haube enthalten primäre Shards die Daten, und Replikat-Shards kopieren diese Daten für Redundanz und Suchkapazität. Das genaue Standard-Shard- und Replikat-Verhalten kann je nach Elasticsearch-Version und Bereitstellungsmodus variieren, verlassen Sie sich also nicht auf Ihr Gedächtnis. Überprüfen Sie die Einstellungen in Ihrem eigenen Cluster.

Die drei Teile, die Sie am häufigsten überprüfen werden, sind:

• settings, wie number_of_shards, number_of_replicas, refresh_interval und Analysekonfiguration.
• mappings, die Feldtypen wie keyword, text, date, long, double, boolean, ip und verschachtelte/Objekt-Felder definieren.
• aliases, die es Anwendungen ermöglichen, einen stabilen Namen zu verwenden, während Sie den tatsächlichen zugrunde liegenden Index dahinter austauschen.

Ein guter Index-API-Workflow beginnt, bevor das erste Dokument indiziert wird. Dynamisches Mapping ist für die Erkundung nützlich, aber Produktionsindizes verdienen explizite Mappings für wichtige Felder. Wenn user_id versehentlich als text gemappt wird, werden Aggregationen und exakte Filter umständlich. Wenn ein Zeitstempel als text gemappt wird, verhalten sich Zeitbereichsabfragen nicht wie Datumsabfragen. Diese Fehler sind behebbar, aber normalerweise durch Erstellen eines neuen Index und Reindizieren.

Erstellen eines einfachen Index

Die kleinste Erstellungsanfrage ist:

PUT /my_first_index

Elasticsearch gibt eine Bestätigung zurück, wenn der Index erstellt wurde:

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "my_first_index"
}

Das ist für einen Testindex in Ordnung. Für echte Daten erstellen Sie den Index mit den Einstellungen und Mappings, die Sie erwarten, anstatt die ersten Dokumente die Form definieren zu lassen.

Erstellen eines Index mit Mappings und Einstellungen

Hier ist ein praktischer products-Index. Er unterstützt Volltextsuche nach Namen und Beschreibungen, exakte Filterung nach IDs und Kategorien, Datumssortierung, numerische Bereichsfilter und einfache Verfügbarkeitsprüfungen.

PUT /products-v1
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "refresh_interval": "5s"
  },
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "product_id": { "type": "keyword" },
      "sku": { "type": "keyword" },
      "name": {
        "type": "text",
        "fields": {
          "raw": { "type": "keyword", "ignore_above": 256 }
        }
      },
      "description": { "type": "text" },
      "category": { "type": "keyword" },
      "price": { "type": "scaled_float", "scaling_factor": 100 },
      "stock": { "type": "integer" },
      "available": { "type": "boolean" },
      "created_at": { "type": "date" },
      "updated_at": { "type": "date" }
    }
  }
}

Einige Entscheidungen hier sind bewusst getroffen. product_id, sku und category sind keyword, weil Sie normalerweise nach exakten Werten filtern, aggregieren oder Anwendungsverhalten verknüpfen. name ist text für die Suche, mit einem name.raw-Keyword-Unterfeld für Sortierung und exakte Übereinstimmung. price verwendet scaled_float, damit Preise als cent-ähnliche skalierte Werte anstelle von binären Gleitkomma-Näherungen gespeichert werden können. dynamic: strict lehnt unbekannte Felder ab, was nützlich ist, wenn schlechte Produzentendaten laut scheitern sollen.

Kopieren Sie die Shard-Anzahl nicht blind. Drei primäre Shards können für einen kleinen Index zu viele und für einen großen zu wenige sein. Die Shard-Anzahl ist nach der Erstellung ohne eine Shrink-, Split- oder Reindex-Migration schwer zu ändern, also dimensionieren Sie sie basierend auf dem erwarteten Datenvolumen, der Aufbewahrungsdauer und der Knotenanzahl.

Überprüfen eines Index nach der Erstellung

Überprüfen Sie immer, was Elasticsearch akzeptiert hat:

GET /products-v1

Das gibt Einstellungen, Mappings und Aliase zurück. Für gezielte Überprüfungen verwenden Sie spezifischere Endpunkte:

GET /products-v1/_mapping
GET /products-v1/_settings
GET /products-v1/_alias

Für eine kompakte Befehlszeilenansicht vieler Indizes:

GET /_cat/indices/products-*?v

Nützliche Spalten sind Health, Status, primäre Shard-Anzahl, Replikat-Anzahl, Dokumentanzahl, gelöschte Dokumentanzahl und Speichergröße. _cat-APIs sind für Menschen gedacht. Verwenden Sie JSON-APIs für Skripte.

Wenn Sie überprüfen, ob ein Feld korrekt gemappt ist, verwenden Sie:

GET /products-v1/_mapping/field/price
GET /products-v1/_mapping/field/name.raw

Das ist schneller zu lesen, als durch ein großes Mapping zu scrollen.

Sicheres Aktualisieren von Indexeinstellungen

Einige Einstellungen sind dynamisch. Die Replikat-Anzahl ist die häufigste:

PUT /products-v1/_settings
{
  "index": {
    "number_of_replicas": 2
  }
}

Dies kann einen grünen Cluster gelb machen, wenn Sie nicht genügend geeignete Datenknoten haben. Zum Beispiel benötigt ein primärer plus zwei Replikate drei separate Orte, um Kopien zu platzieren. Allokations-Awareness-Regeln können die Anforderung strenger machen.

refresh_interval ist eine weitere Einstellung, die Sie während Bulk-Ladevorgängen ändern können:

PUT /products-v1/_settings
{
  "index": {
    "refresh_interval": "30s"
  }
}

Ein längeres Refresh-Intervall kann den Indexierungs-Overhead reduzieren, aber neu indizierte Dokumente werden weniger schnell für die Suche sichtbar. Für einen Bulk-Backfill erhöhen Teams oft das Intervall oder deaktivieren Aktualisierungen vorübergehend, laden Daten und stellen dann das normale Intervall wieder her und aktualisieren einmal:

POST /products-v1/_refresh

Einige Einstellungen sind statisch. number_of_shards kann bei einem geöffneten vorhandenen Index nicht geändert werden. Wenn Sie feststellen, dass die primäre Shard-Anzahl falsch ist, planen Sie einen neuen Index und eine Migration.

Ändern von Mappings ohne sich selbst zu belügen

Sie können einem Mapping neue Felder hinzufügen:

PUT /products-v1/_mapping
{
  "properties": {
    "brand": { "type": "keyword" }
  }
}

Sie können im Allgemeinen den Typ eines vorhandenen Feldes nicht direkt ändern. Wenn price bereits text ist, wird dies alte Werte nicht in ein nützliches numerisches Feld verwandeln. Erstellen Sie einen neuen Index mit dem korrekten Mapping und indizieren Sie neu:

POST /_reindex
{
  "source": { "index": "products-v1" },
  "dest": { "index": "products-v2" }
}

Für Produktionsmigrationen verwenden Sie Aliase, damit die Anwendung die physische Indexversion nicht kennen muss.

Verwenden von Aliasen für sichereren Anwendungszugriff

Zeigen Sie einen Alias auf die erste Version:

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v1", "alias": "products" } }
  ]
}

Ihre Anwendung liest von products. Später erstellen Sie products-v2, indizieren Daten neu, testen sie und tauschen dann den Alias atomar aus:

POST /_aliases
{
  "actions": [
    { "remove": { "index": "products-v1", "alias": "products" } },
    { "add": { "index": "products-v2", "alias": "products" } }
  ]
}

Für schreibintensive Systeme verwenden Sie einen Schreibalias und geben is_write_index explizit an:

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v2", "alias": "products-write", "is_write_index": true } }
  ]
}

Aliase sind eine der einfachsten Möglichkeiten, das Hartcodieren von Indexversionen in Diensten zu vermeiden.

Sorgfältiges Auflisten und Durchsuchen von Indexnamen

Um mehrere Indizes zu überprüfen:

GET /products-v1,products-v2/_settings
GET /products-*/_mapping
GET /_cat/indices/products-*?v&s=index

Seien Sie vorsichtig mit breiten Wildcards in großen Clustern. GET /* oder GET /_all kann eine riesige Antwort erzeugen und kann je nach Version, Einstellungen und Anfrageoptionen System- oder versteckte Indizes enthalten. Bevorzugen Sie ein enges Muster wie logs-prod-* oder products-*.

Um aus einem Skript zu überprüfen, ob ein Index existiert, verwenden Sie HEAD:

HEAD /products-v1

Ein 200 bedeutet, dass er existiert. Ein 404 bedeutet, dass er nicht existiert.

Löschen von Indizes mit Schutzmaßnahmen

Löschen ist einfach:

DELETE /products-v1

Das operationelle Risiko liegt nicht in der Syntax. Das Risiko besteht darin, den falschen Index zu löschen oder zu löschen, bevor ein Snapshot abgeschlossen ist.

Listen Sie vor dem Löschen genau auf, was das Muster matcht:

GET /_cat/indices/products-old-*?v&s=index

Wenn die Ausgabe korrekt ist und die Daten wiederherstellbar oder nicht mehr benötigt werden, löschen Sie dasselbe Muster:

DELETE /products-old-*

Viele Cluster schränken destruktive Wildcard-Operationen mit action.destructive_requires_name ein. Das ist eine gute Sicherheitseinstellung, da sie breite Löschvorgänge wie DELETE /* blockiert, es sei denn, explizite Namen sind erforderlich. Selbst mit diesem Schutz behandeln Sie Löschvorgänge als Produktionsänderungen: Bestätigen Sie das Indexmuster, bestätigen Sie Snapshots und bestätigen Sie, dass der Aufrufer die richtigen Berechtigungen hat.

Bevorzugen von Lifecycle-Richtlinien für Zeitreihendaten

Manuelle Löschungen sind für einmalige Bereinigungen akzeptabel. Für Logs, Metriken, Traces und andere Zeitreihendaten verwenden Sie Index Lifecycle Management oder Datenströme, wo angemessen. Eine Lifecycle-Richtlinie kann einen Index umschlagen, wenn er ein Alters- oder Größenlimit erreicht, ältere Daten in eine andere Stufe verschieben und sie nach Ablauf der Aufbewahrungsfrist löschen.

Das ist wichtig, weil manuelle Bereinigungen tendenziell zur ungünstigsten Zeit fehlschlagen. Jemand vergisst es, der Speicher füllt sich, Hochwasser-Markierungen machen Indizes schreibgeschützt, und dann muss das Team unter Druck aufräumen. Lifecycle-Richtlinien verwandeln die Aufbewahrung in eine Konfiguration anstelle einer Kalendererinnerung.

Eine einfache tägliche Routine

Für einen Produktionscluster sieht eine praktische Indexverwaltungsroutine so aus:

Gesundheitszustand prüfen:

GET /_cluster/health

Indizes nach Muster auflisten:

GET /_cat/indices/logs-*?v&s=store.size:desc

Verdächtige Einstellungen überprüfen:

GET /logs-prod-2026.05.24/_settings

Mappings vor dem Hinzufügen neuer Felder aus einem Anwendungsrelease überprüfen:

GET /logs-prod-2026.05.24/_mapping

Aliase vor und nach einer Migration bestätigen:

GET /_cat/aliases/products*?v

Das ist keine glamouröse Arbeit, aber sie fängt viele Probleme frühzeitig ein: falsche Replikat-Anzahlen, versehentliche dynamische Felder, veraltete Aliase und alte Indizes, die hätten ausgemustert werden sollen.

Häufige Fehler, die vermieden werden sollten

Lassen Sie nicht zu, dass Entwicklungsstandards zur Produktionsarchitektur werden. Ein Einzelknoten-Cluster, null Replikate und dynamische Mappings mögen für eine Demo in Ordnung sein. Sie sind kein Wiederherstellungsplan.

Ändern Sie keine Mappings in Gedanken und nehmen Sie an, Elasticsearch stimmt zu. Überprüfen Sie das tatsächliche Mapping.

Verwenden Sie keine Wildcard-Löschungen, ohne zuerst die passenden Indizes aufzulisten.

Setzen Sie keine hohen Replikat-Anzahlen ohne genügend Datenknoten und Zonen, um sie zu platzieren.

Überspringen Sie keine Aliase für Indizes, von denen Anwendungen abhängen. Die erste Migration wird viel einfacher sein, wenn die Anwendung bereits mit einem Alias spricht.

Gute Indexverwaltung ist meist disziplinierte Wiederholung. Erstellen Sie mit Absicht, überprüfen Sie, was existiert, migrieren Sie mit Aliasen, automatisieren Sie die Aufbewahrung und machen Sie destruktive Aktionen langweilig explizit.

Vorlagen sind wichtiger als einmalige Erstellungen

Wenn Sie wiederholt dieselbe Art von Index erstellen, verlassen Sie sich nicht auf manuelle PUT /index-name-Aufrufe. Verwenden Sie eine Indexvorlage oder zusammensetzbare Vorlagen, damit neue Indizes automatisch die richtigen Mappings, Einstellungen, Aliase und Lifecycle-Richtlinien erhalten.

Eine Log-Plattform ist das klassische Beispiel. Wenn logs-web-2026.05.24 ein korrektes @timestamp-Mapping hat, aber der morgige Index dynamisch durch das erste Dokument erstellt wird, kann ein einziges fehlerhaftes Ereignis ein Feld falsch mappen. Der Fehler zeigt sich möglicherweise erst, wenn Dashboards ausfallen oder Aggregationen verschwinden. Vorlagen verhindern diese Abweichung.

Eine einfache Vorlage könnte ein Muster, Einstellungen und Mappings für zukünftige Indizes definieren:

PUT /_index_template/logs_web_template
{
  "index_patterns": ["logs-web-*"],
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "@timestamp": { "type": "date" },
        "service": { "type": "keyword" },
        "level": { "type": "keyword" },
        "message": { "type": "text" },
        "trace_id": { "type": "keyword" }
      }
    }
  }
}

Vorlagen sind auch einfacher im Code zu überprüfen. Legen Sie sie in der Versionsverwaltung ab, stellen Sie sie über denselben Pfad wie Anwendungsänderungen bereit und testen Sie sie, bevor der Rollover den nächsten zugrunde liegenden Index erstellt.

Reindizieren ohne die Anwendung zu überraschen

Die sauberste Indexmigration ist normalerweise: Erstellen Sie einen neuen versionierten Index, indizieren Sie Daten neu, vergleichen Sie Anzahlen und Beispielabfragen und tauschen Sie dann einen Alias aus. Zeigen Sie die Anwendung nicht direkt auf products-v1, es sei denn, Sie genießen Notfall-Konfigurationsänderungen.

Eine sorgfältige Migration sieht so aus:

PUT /products-v2
{
  "mappings": {
    "properties": {
      "product_id": { "type": "keyword" },
      "name": { "type": "text" },
      "price": { "type": "scaled_float", "scaling_factor": 100 }
    }
  }
}

Dann neu indizieren:

POST /_reindex?wait_for_completion=false
{
  "source": { "index": "products-v1" },
  "dest": { "index": "products-v2" }
}

Die Verwendung von wait_for_completion=false gibt eine Aufgaben-ID zurück, sodass Sie einen langen Reindex überwachen können. Nachdem er abgeschlossen ist, vergleichen Sie die Dokumentanzahlen und führen repräsentative Suchen durch. Erst dann tauschen Sie die Aliase aus.

Für schreibintensive Indizes denken Sie über Dual Writes, Pausenfenster oder Wiedergabe aus einer Quelle der Wahrheit nach. Die API-Befehle sind einfach; der Konsistenzplan ist die eigentliche Arbeit.

Sicherheit und Berechtigungen

Index-APIs sollten nicht jedem Anwendungsbenutzer zur Verfügung stehen. Ein Suchdienst benötigt möglicherweise Leseberechtigungen für einen Alias. Ein Datenerfasser benötigt möglicherweise Erstellungs-, Indexierungs- und Schreibberechtigungen für einen Schreibalias. Nur sehr wenige Identitäten sollten umfassende Lösch- oder Verwaltungsberechtigungen haben.

Das ist wichtig, weil Index-APIs mächtig sind. Eine kompromittierte Anwendungsanmeldeinformation mit manage-Berechtigungen kann Replikat-Einstellungen ändern, Indizes schließen oder Daten löschen. Halten Sie destruktive Berechtigungen getrennt und machen Sie das Löschen in der Produktion zu einem Operator-Workflow anstelle eines Anwendungspfads.

Namenskonventionen reduzieren Fehler

Verwenden Sie Namen, die Zweck und Lebenszyklus kodieren: products-v3, logs-web-2026.05.24, metrics-api-000123 oder Datenstromnamen, die der Datenquelle entsprechen. Vermeiden Sie vage Namen wie newindex, test2 oder prod-final. Bei der Bereinigung ist es bei vagen Namen schwer zu wissen, was sicher gelöscht werden kann.

Für Zeitreihenindizes verwenden Sie konsistente Datumsformate und vermeiden Sie die Vermischung von Ortszeit und UTC-Annahmen. Für versionierte Geschäftsindizes halten Sie den Alias stabil und lassen Sie die physische Indexversion dahinter wechseln. Eine langweilige Namenskonvention ist ein operationelles Sicherheitsmerkmal.