Indizierung und Aktualisierung von Dokumenten mit der Elasticsearch REST API

Elasticsearch ist eine leistungsstarke, verteilte Such- und Analyse-Engine, die auf gut strukturierten Daten-Ingestion basiert. Die Verwaltung dieser Daten umfasst grundlegende CRUD-Operationen (Create, Read, Update, Delete), die hauptsächlich über seine vielseitige REST API ausgeführt werden. Zu verstehen, wie neue Dokumente korrekt indiziert und vorhandene effizient aktualisiert werden, ist entscheidend für die Aufrechterhaltung eines Echtzeit-Datenspeichers.

Diese Anleitung führt Sie durch die wesentlichen HTTP-Methoden und API-Endpunkte, die für die Indizierung neuer Datensätze und die Änderung vorhandener Dokumente in Ihrem Elasticsearch-Cluster verwendet werden. Wir konzentrieren uns auf die Syntax, die erforderlichen JSON-Payloads und die Interpretation der Antwortcodes, um eine nahtlose Datenverwaltung zu gewährleisten.

---

Voraussetzungen

Stellen Sie vor Beginn sicher, dass Sie Folgendes haben:

• Einen aktiven Elasticsearch-Cluster, der läuft.
• Ein Befehlszeilentool, das HTTP-Anfragen stellen kann (wie curl) oder einen HTTP-Client (wie Postman).
• Kenntnisse über den Namen Ihres Zielindex.

---

1. Indizierung neuer Dokumente

Indizierung ist der Prozess der Speicherung eines JSON-Dokuments in einem Elasticsearch-Index. Elasticsearch weist dem Dokument automatisch eine eindeutige ID zu, sofern keine explizit angegeben wird. Die primäre Methode zur Indizierung ist die HTTP-Methode PUT oder POST.

1.1 Indizierung mit einer automatischen ID (POST)

Wenn Sie POST an den Index-Endpunkt verwenden, generiert Elasticsearch eine eindeutige Dokumenten-ID für Sie. Dies ist oft die bevorzugte Methode für die anfängliche Datenerfassung, wenn IDs intern verwaltet werden.

Endpunkt: POST /{index_name}/_doc/

Beispielanfrage (mit curl):

curl -X POST "localhost:9200/products/_doc/" -H 'Content-Type: application/json' -d'
{
  "name": "Wireless Mouse X1",
  "price": 25.99,
  "in_stock": true
}
'

Snippet einer erfolgreichen Antwort:

{
  "_index": "products",
  "_id": "c7BwJ3gBpV4wT-eH_aY1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

Das Feld result mit dem Wert created bestätigt, dass ein neues Dokument hinzugefügt wurde.

1.2 Indizierung mit einer spezifischen ID (PUT)

Wenn Ihr Quellsystem eine eindeutige Kennung für das Dokument bereitstellt, sollten Sie die PUT-Methode verwenden, die auf eine bestimmte ID abzielt. Wenn ein Dokument mit dieser ID bereits existiert, wird dieses Dokument von PUT überschrieben.

Endpunkt: PUT /{index_name}/_doc/{document_id}

Beispielanfrage: Indizierung eines Dokuments mit der ID 1001.

curl -X PUT "localhost:9200/products/_doc/1001" -H 'Content-Type: application/json' -d'
{
  "name": "Mechanical Keyboard K90",
  "price": 129.99,
  "in_stock": true
}
'

Snippet einer erfolgreichen Antwort:

{
  "_index": "products",
  "_id": "1001",
  "_version": 1,
  "result": "created",
  "_shards": { ... }
}

Tipp zum Überschreiben: Wenn Sie dieselbe PUT-Anfrage mit derselben ID erneut ausführen, ändert sich das result zu updated, und die Nummer _version wird inkrementiert.

---

2. Aktualisierung vorhandener Dokumente

Die Aktualisierung von Dokumenten unterscheidet sich vom Überschreiben. Wenn Sie nur bestimmte Felder in einem vorhandenen Dokument ändern möchten, ohne unveränderte Felder zu beeinträchtigen, verwenden Sie den Endpunkt _update, normalerweise mit der POST-Methode.

2.1 Teilaktualisierungen mit _update

Die _update-API ist entscheidend für atomare Aktualisierungen. Sie erfordert einen doc-Block innerhalb der Payload, der nur die zu ändernden Felder enthält. Elasticsearch ruft das Dokument ab, führt die Änderungen zusammen und indiziert es neu.

Endpunkt: POST /{index_name}/_update/{document_id}

Beispielszenario: Wir möchten den Preis des Produkts mit der ID 1001 von 129,99 $ auf 119,99 $ ändern und es als nicht auf Lager markieren.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "doc": {
    "price": 119.99,
    "in_stock": false
  }
}
'

Snippet einer erfolgreichen Antwort:

{
  "_index": "products",
  "_id": "1001",
  "_version": 2, 
  "result": "updated",
  "_shards": { ... }
}

Beachten Sie, dass _version von 1 auf 2 inkrementiert wurde, was die Änderung widerspiegelt.

2.2 Verwendung von Skript-Updates

Für komplexere, bedingte oder mathematische Aktualisierungen unterstützt Elasticsearch Painless Scripting innerhalb der _update-API. Dies ermöglicht Ihnen, Operationen wie das Inkrementieren von Zählern oder das Setzen von Feldern basierend auf ihren aktuellen Werten durchzuführen.

Beispielszenario: Erhöhen Sie den Lagerbestand für das Dokument mit der ID 1001 um 5.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "script": {
    "source": "ctx._source.stock += params.count",
    "params": {
      "count": 5
    }
  }
}
'

Wichtiges Skriptkonzept: ctx._source bezieht sich auf die aktuelle Dokumentenquelle.

Warnung zu Skripten: Obwohl leistungsstark, können komplexe Skripte die Leistung beeinträchtigen. Verwenden Sie nach Möglichkeit einfache Feldaktualisierungen (doc), da diese im Allgemeinen schneller und sicherer sind.

---

3. Massenindizierung und -aktualisierung

Bei Massendatenoperationen ist das Senden einzelner Anfragen für jedes Dokument ineffizient. Elasticsearch stellt die _bulk-API bereit, um mehrere Indizierungs-, Aktualisierungs- oder Löschoperationen in einer einzigen Anfrage zu verarbeiten.

3.1 Struktur einer Bulk-Anfrage

Bulk-Anfragen verwenden ein spezifisches, zeilengetrenntes JSON-Format (NDJSON). Jede Operation wird durch eine Metadatenzeile (die die Aktion, den Index und optional die ID angibt) definiert, gefolgt unmittelbar von der Quelldokumentation (falls erforderlich).

Aktionstypen für Bulk: index, create, update, delete.

Beispiel einer Bulk-Anfrage (Mischen von Indizierung und Aktualisierung):

curl -X POST "localhost:9200/products/_bulk" -H 'Content-Type: application/x-ndjson' -d'

{"index": {"_id": "2001"}}
{"name": "USB-C Hub", "price": 45.00, "in_stock": true}
{"update": {"_id": "1001"}}
{"doc": {"price": 115.00}}
{"delete": {"_id": "3003"}}

'

In diesem Beispiel:

1. Dokument 2001 wird indiziert.
2. Dokument 1001 wird teilweise aktualisiert (Preis wird gesenkt).
3. Dokument 3003 wird gelöscht.

Bulk-Antwort: Die Antwort wird den Erfolg oder Misserfolg jeder einzelnen Operation innerhalb des Batches detailliert beschreiben, sodass Sie genau bestimmen können, welche Dokumente erfolgreich waren und welche fehlgeschlagen sind.

---

Zusammenfassung der wichtigsten API-Befehle

Operation	HTTP-Methode	Endpunkt-Muster	Auswirkung
Index (Auto-ID)	POST	/{index}/_doc/	Erstellt ein neues Dokument mit automatisch generierter ID.
Index/Überschreiben	PUT	/{index}/_doc/{id}	Erstellt oder ersetzt ein Dokument an der angegebenen ID vollständig.
Teilweise Aktualisierung	POST	/{index}/_update/{id}	Fügt die im doc-Block angegebenen Änderungen zusammen.
Bulk-Operationen	POST	/{index}/_bulk	Führt mehrere Operationen in einer einzigen Anfrage aus.

Die Beherrschung dieser grundlegenden REST-API-Interaktionen bildet das Rückgrat für die dynamische Datenverwaltung innerhalb jeder Elasticsearch-Anwendung.