Claude Code Elasticsearch: Queries, Mappings und Aggregationen meistern

Elasticsearch ist eine der mächtigsten Suchmaschinen, die ein Entwickler einsetzen kann — und gleichzeitig eine der komplexesten. Die Query-DSL allein hat Dutzende Abfragetypen. Das Mapping entscheidet, ob eine Suche überhaupt funktioniert. Aggregationen können Daten auf eine Art analysieren, die mit klassischen SQL-Abfragen kaum möglich wäre. Und doch verbringen Entwickler Stunden damit, die richtige Kombination aus bool, must, should und filter zu finden — oder warum ein term-Query auf einem text-Feld nie etwas liefert.

Claude Code Elasticsearch verändert diesen Prozess grundlegend: nicht durch Abstraktion, sondern durch präzise Unterstützung genau da, wo Elasticsearch-Entwicklung schwierig wird — beim Mapping-Design, bei komplexen Queries und beim Debuggen von Aggregationen, die nicht das liefern, was man erwartet.

1. Was ist Elasticsearch?

Elasticsearch ist eine verteilte, RESTful Suchmaschine und Analyseplattform, die auf Apache Lucene aufbaut. Lucene ist die eigentliche Suchbibliothek — Elasticsearch macht sie über eine JSON-basierte HTTP-API für verteilte Systeme nutzbar. Daten werden als JSON-Dokumente in Indizes gespeichert und können in Echtzeit durchsucht und analysiert werden.

Im ELK-Stack (heute oft Elastic Stack genannt) übernimmt Elasticsearch die Speicherung und Suche: Logstash oder Beats sammeln und verarbeiten Daten, Elasticsearch indexiert und speichert sie, Kibana visualisiert sie. Das macht Elasticsearch zur zentralen Komponente für Log-Analyse, Application Performance Monitoring und Echtzeit-Suche in Web-Applikationen.

2. Index und Mapping: Das Fundament richtig legen

Der häufigste Elasticsearch-Fehler entsteht nicht beim Schreiben von Queries, sondern beim Mapping — oder genauer: beim Ignorieren des Mappings und dem Vertrauen auf Dynamic Mapping. Elasticsearch erkennt Typen automatisch, aber was es erkennt, ist nicht immer was man will.

Index erstellen mit explizitem Mapping

PUT /produkte
{
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "german",
        "fields": {
          "keyword": { "type": "keyword" }
        }
      },
      "preis": { "type": "float" },
      "kategorie": { "type": "keyword" },
      "erstellt_am": { "type": "date", "format": "yyyy-MM-dd" },
      "beschreibung": { "type": "text", "analyzer": "german" },
      "auf_lager": { "type": "boolean" }
    }
  }
}

Das Multi-Field-Pattern bei name ist entscheidend: text für Volltextsuche mit Tokenisierung, keyword für exakte Übereinstimmungen, Sortierung und Aggregationen. Wer das vergisst, wundert sich später, warum Aggregationen auf Textfeldern nicht funktionieren.

Dynamic Mapping ist praktisch für den Start, aber problematisch in der Produktion: Elasticsearch kann einen Typ nicht rückwirkend ändern. Wer ein Feld einmal als text indexiert hat, kann es nicht ohne Re-Indexierung in keyword umwandeln. Explizites Mapping von Anfang an spart diesen Aufwand.

3. Queries: Von einfach bis komplex

Die Elasticsearch Query-DSL ist mächtig und ausdrucksstark — aber auch verbose. Hier sind die wichtigsten Typen und wann man sie einsetzt.

match, term und bool

# Volltextsuche (analysiert den Suchbegriff)
GET /produkte/_search
{
  "query": {
    "match": { "beschreibung": "wasserdichte Winterjacke" }
  }
}

# Exakte Übereinstimmung (kein Analysieren)
GET /produkte/_search
{
  "query": {
    "term": { "kategorie": "Outdoor" }
  }
}

# Kombinierte Query mit bool
GET /produkte/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "beschreibung": "Winterjacke" } }
      ],
      "filter": [
        { "term": { "auf_lager": true } },
        { "range": { "preis": { "lte": 200 } } }
      ],
      "should": [
        { "term": { "kategorie": "Outdoor" } }
      ]
    }
  }
}

Der Unterschied zwischen must und filter im bool-Query ist für Performance entscheidend: must beeinflusst den Relevanz-Score, filter nicht — und Elasticsearch kann filter-Ergebnisse cachen. Reine Ja/Nein-Bedingungen (Status, Preis, Datum) gehören immer in filter.

fuzzy und multi_match

# Tippfehler-tolerante Suche
GET /produkte/_search
{
  "query": {
    "fuzzy": {
      "name": { "value": "Jackke", "fuzziness": "AUTO" }
    }
  }
}

# Suche über mehrere Felder
GET /produkte/_search
{
  "query": {
    "multi_match": {
      "query": "wasserdicht",
      "fields": ["name^2", "beschreibung"],
      "type": "best_fields"
    }
  }
}

Das ^2 beim Feldnamen ist Boosting: Treffer im name-Feld werden doppelt gewichtet. multi_match mit type: best_fields nimmt den höchsten Score eines Feldes, cross_fields behandelt alle Felder wie einen einzigen Text.

4. Aggregationen: Daten analysieren statt nur suchen

Aggregationen sind das Werkzeug, mit dem Elasticsearch weit über einfache Suche hinausgeht. Sie erlauben Echtzeit-Analysen direkt auf den indexierten Daten — ohne separate Datenbank-Abfragen.

GET /produkte/_search
{
  "size": 0,
  "aggs": {
    "nach_kategorie": {
      "terms": { "field": "kategorie", "size": 10 }
    },
    "preis_stats": {
      "stats": { "field": "preis" }
    },
    "bestellungen_pro_monat": {
      "date_histogram": {
        "field": "erstellt_am",
        "calendar_interval": "month"
      },
      "aggs": {
        "umsatz": { "sum": { "field": "preis" } }
      }
    }
  }
}

size: 0 unterdrückt die Dokumenten-Hits — wenn man nur Aggregations-Ergebnisse braucht, spart das Bandbreite und Verarbeitungszeit. Verschachtelte Aggregationen (hier: umsatz innerhalb von bestellungen_pro_monat) ermöglichen mehrdimensionale Analysen in einer einzigen Anfrage.

5. Python-Client: elasticsearch-py im Einsatz

Die offizielle Python-Bibliothek elasticsearch-py bildet die REST-API direkt ab — was man in der API-Dokumentation findet, funktioniert im Python-Client genauso.

from elasticsearch import Elasticsearch, AsyncElasticsearch
from elasticsearch.helpers import bulk

# Synchroner Client
es = Elasticsearch("http://localhost:9200")

# Dokument indexieren
es.index(index="produkte", document={
    "name": "Gore-Tex Winterjacke",
    "preis": 189.99,
    "kategorie": "Outdoor",
    "auf_lager": True
})

# Bulk-Indexierung für große Datenmengen
def generate_docs(data):
    for item in data:
        yield {"_index": "produkte", "_source": item}

success, errors = bulk(es, generate_docs(produkt_liste))

# Async-Client für concurrent Workflows
async def search_async(query_text):
    async with AsyncElasticsearch("http://localhost:9200") as aes:
        result = await aes.search(
            index="produkte",
            body={"query": {"match": {"beschreibung": query_text}}}
        )
        return result["hits"]["hits"]

Bulk-Indexierung ist bei größeren Datenmengen unverzichtbar: statt jedes Dokument einzeln zu senden, werden Batches von mehreren Hundert oder Tausend Dokumenten in einer HTTP-Anfrage übertragen. Die Faustregel: ab 100 Dokumenten Bulk verwenden, Batch-Größe zwischen 500 und 5000 Dokumenten je nach Dokumentgröße.

6. Relevanz-Tuning: Boosting und function_score

Standardmäßig berechnet Elasticsearch Relevanz nach TF/IDF und BM25. Das reicht für viele Anwendungsfälle — aber wenn Aktionsartikel höher gewichtet werden sollen als vergriffene, oder wenn neuere Produkte vor älteren erscheinen sollen, braucht man Eingriffsmöglichkeiten.

GET /produkte/_search
{
  "query": {
    "function_score": {
      "query": {
        "match": { "beschreibung": "Winterjacke" }
      },
      "functions": [
        {
          "filter": { "term": { "auf_lager": true } },
          "weight": 2
        },
        {
          "gauss": {
            "erstellt_am": {
              "origin": "now",
              "scale": "30d",
              "decay": 0.5
            }
          }
        }
      ],
      "score_mode": "multiply",
      "boost_mode": "multiply"
    }
  }
}

Die Gauss-Funktion sorgt dafür, dass Produkte, die älter als 30 Tage sind, mit einem Score-Faktor von 0,5 abgewertet werden — je älter, desto stärker. In Kombination mit dem Lagerbestand-Boost entstehen Rankings, die Geschäftslogik direkt widerspiegeln.

7. Claude Code Elasticsearch: Konkrete Tipps

Wo hilft Claude Code bei Elasticsearch konkret? Vor allem dort, wo die Query-DSL komplex wird und kleine Fehler schwer zu finden sind.

Queries aus natürlicher Sprache generieren

claude "Schreibe einen Elasticsearch-bool-Query der:
- Produkte sucht die 'Winterjacke' im Namen oder in der Beschreibung enthalten
- Nur Produkte unter 250 Euro zurückgibt
- Lagerbestand muss vorhanden sein
- Produkte der Kategorie 'Outdoor' werden höher gewichtet
Mein Mapping: name (text+keyword), preis (float), kategorie (keyword), auf_lager (boolean)"

Claude Code liest das Mapping, versteht die Geschäftsanforderungen und schreibt einen korrekten bool-Query — inklusive des wichtigen Details, dass Lagerbestand und Preis in filter gehören (kein Einfluss auf Score, cachebar), während das Kategorie-Boosting in should gehört.

Mapping optimieren lassen

claude "Analysiere dieses Elasticsearch-Mapping und zeige,
welche Felder falsch typisiert sind oder welche Multi-Field-Definitionen fehlen:
$(curl -s localhost:9200/produkte/_mapping)"

Claude Code erkennt typische Probleme: Textfelder ohne keyword-Subfield, Datumsfelder ohne explizites Format, numerische Felder die fälschlicherweise als Text indexiert wurden. Statt selbst jedes Feld zu prüfen, bekommt man eine priorisierte Liste mit konkreten Fix-Vorschlägen.

Aggregationen debuggen

Aggregationen die 0 zurückgeben oder unerwartete Ergebnisse liefern, sind schwer zu debuggen, weil die Fehlerquelle an mehreren Stellen liegen kann: falsche Feldtypen, falscher Query-Scope, falsche Bucket-Größe, falsches Date-Format. Claude Code analysiert die Aggregation, das Mapping und die Antwort gemeinsam:

claude "Diese Aggregation gibt 0 Buckets zurück, obwohl Daten vorhanden sind.
Aggregation: [JSON]
Mapping des Index: [JSON]
Beispiel-Dokument: [JSON]
Was ist der Fehler?"

In den meisten Fällen ist die Ursache sofort erkennbar: eine terms-Aggregation auf einem text-Feld (statt keyword), oder ein Datumsfeld das als String indexiert wurde und deshalb keine date_histogram-Aggregation erlaubt.

Zwei verwandte Artikel, die auf diesem Thema aufbauen:

• Claude Code für Python-Projekte — Python-Workflows und Datenbank-Integrationen mit Claude Code
• Claude Code Debugging — systematisches Debuggen von API-Fehlern und Response-Problemen