Die Explain API für Scoring-Debugging systematisch nutzen

1. Warum Scoring-Debugging in der Praxis unverzichtbar wird

Jede Elasticsearch-Suche liefert nicht nur Treffer, sondern auch eine implizite Rangfolge dieser Treffer über den Relevanz-Score. Dieser Score entscheidet, welches Dokument auf Position eins landet und welches auf Seite drei verschwindet, und ist damit direkt geschäftskritisch, etwa bei Produktsuchen in einem Online-Shop. Sobald Nutzer oder Product Owner fragen, warum ein bestimmtes Dokument über einem vermeintlich passenderen Dokument steht, reicht ein Blick auf die Query allein nicht aus. Man braucht Einblick in die tatsächliche Score-Berechnung.

Genau hier setzt Scoring-Debugging an: Statt zu raten, ob ein Boost zu stark gewichtet ist oder ein Term-Frequenz-Effekt den Ausschlag gibt, zeigt die Explain API die vollständige Rechnung, aus der sich der finale Score zusammensetzt. Das ist besonders wertvoll bei komplexen Queries mit mehreren should-Klauseln, Function Score, Boosting und Multi-Match-Feldern, bei denen der Gesamteffekt aus dem bloßen Lesen der Query-DSL kaum vorhersehbar ist.

Ein zentraler Grundsatz für effektives Scoring-Debugging: Die Explain API liefert Fakten, keine Bewertung. Sie zeigt, wie der Score zustande kam, nicht ob dieser Score "richtig" oder "falsch" ist. Die Interpretation, ob eine Gewichtung angemessen ist, bleibt Aufgabe des Menschen, der die Domäne und die Nutzerintention kennt. Die folgenden Abschnitte zeigen, wie man mit der Explain API systematisch von der Symptomebene zur Ursache im Scoring vordringt.

2. Der _explain Endpoint: Aufbau und Aufruf

Der dedizierte _explain Endpoint beantwortet eine ganz konkrete Frage: Warum hat genau dieses eine Dokument diesen Score für diese Query erhalten? Der Aufruf erfolgt gegen einen bekannten Index, eine bekannte Dokument-ID und dieselbe Query, die auch in der Suche verwendet wurde. Die Antwort enthält ein explanation-Objekt mit dem finalen Score als Wurzel und einer verschachtelten Baumstruktur von Teilberechnungen darunter.

Der _explain Endpoint ist bewusst auf ein einzelnes Dokument fokussiert, weil eine vollständige Erklärung für jeden Treffer einer großen Trefferliste zu viel Overhead erzeugen würde. In der Praxis nutzt man diesen Endpoint typischerweise, nachdem man in der regulären Suche bereits die verdächtige Dokument-ID identifiziert hat, etwa weil sie unerwartet weit oben oder weit unten in der Trefferliste steht.

GET /produkte/_explain/4711
{
  "query": {
    "bool": {
      "must": [
        { "match": { "titel": "wanderschuhe herren" } }
      ],
      "should": [
        { "term": { "marke.keyword": "TrailPro" } }
      ]
    }
  }
}

# Antwort (gekuerzt):
# {
#   "matched": true,
#   "explanation": {
#     "value": 8.42,
#     "description": "sum of:",
#     "details": [
#       { "value": 6.10, "description": "weight(titel:wanderschuhe ...) ..." },
#       { "value": 2.32, "description": "weight(marke.keyword:TrailPro ...) ..." }
#     ]
#   }
# }

Wichtig ist das Feld matched: Steht es auf false, hat das Dokument die Query gar nicht erfüllt und taucht folgerichtig nicht in den Suchergebnissen auf, unabhängig von der Score-Berechnung darunter. Das ist der erste Diagnose-Schritt bei der Frage "Warum finde ich dieses Dokument nicht?" noch vor jeder Score-Analyse.

3. Die Score-Breakdown-Baumstruktur systematisch lesen

Die Explanation-Struktur ist rekursiv aufgebaut: Jeder Knoten hat einen value, eine textuelle description und optional eine Liste von details, die selbst wieder dieselbe Struktur haben. Ein Knoten mit der Beschreibung sum of: addiert die Werte seiner Kinder, ein Knoten mit max of: übernimmt den höchsten Wert seiner Kinder, typisch für dis_max Queries und Multi-Match mit best_fields. Diese Struktur systematisch von der Wurzel nach unten zu lesen ist der Schlüssel zum Verständnis eines komplexen Scores.

Beim Lesen hilft es, sich zunächst nur die oberste Ebene der details anzuschauen und zu identifizieren, welcher Teilbaum den größten Anteil am Gesamtscore hat. Erst danach lohnt es sich, in diesen dominanten Teilbaum weiter hinabzusteigen. Wer stattdessen versucht, die gesamte verschachtelte Struktur auf einmal zu erfassen, verliert schnell den Überblick, besonders bei Queries mit mehreren should-Klauseln und verschachtelten Bool-Queries.

# Typische Baumstruktur einer Bool-Query mit zwei must-Klauseln
{
  "value": 12.87,
  "description": "sum of:",
  "details": [
    {
      "value": 9.55,
      "description": "weight(titel:wanderschuhe in 42) [PerFieldSimilarity], result of:",
      "details": [
        {
          "value": 9.55,
          "description": "score(freq=2.0), computed as boost * idf * tf from:",
          "details": [
            { "value": 2.2, "description": "boost" },
            { "value": 3.8, "description": "idf, computed as log(1 + (N - n + 0.5) / (n + 0.5))" },
            { "value": 1.14, "description": "tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl))" }
          ]
        }
      ]
    },
    {
      "value": 3.32,
      "description": "weight(marke.keyword:TrailPro in 42) [PerFieldSimilarity], result of:",
      "details": [ ]
    }
  ]
}

Die Bezeichner in eckigen Klammern wie [PerFieldSimilarity] zeigen an, welche Similarity-Implementierung für dieses Feld konfiguriert ist. Weicht diese vom erwarteten BM25 ab, etwa weil versehentlich eine boolean Similarity ohne Term-Frequenz-Gewichtung aktiv ist, erklärt das häufig, warum sich ein Score unerwartet verhält.

4. BM25 verstehen: Was die Explain-Ausgabe wirklich zeigt

Seit Elasticsearch 5 ist BM25 die Standard-Similarity-Funktion, und die Explain-Ausgabe folgt konsequent deren Formel. Drei Komponenten dominieren jeden Score-Knoten: boost, ein manuell oder durch Query-Struktur vergebener Multiplikator, idf (Inverse Document Frequency), das seltene Terme höher gewichtet als häufige, und tf (Term Frequency), das die Häufigkeit des Terms im Dokument berücksichtigt, aber im Gegensatz zu klassischem TF-IDF mit den Parametern k1 und b saturiert wird, sodass wiederholte Vorkommen abnehmenden Grenznutzen haben.

Der Parameter b steuert die Längen-Normalisierung: Ein langes Dokument mit vielen Vorkommen eines Terms bekommt nicht automatisch einen proportional höheren Score als ein kurzes, fokussiertes Dokument. Das ist der Grund, warum kurze, präzise Produkttitel bei BM25 oft besser abschneiden als lange Fließtext-Beschreibungen mit demselben Term, selbst wenn der Term in beiden gleich oft vorkommt. Die Explain-Ausgabe zeigt dl (document length) und avgdl (average document length) explizit, sodass sich dieser Effekt direkt nachvollziehen lässt.

GET /produkte/_explain/4711
{
  "query": { "match": { "beschreibung": "wasserdicht" } }
}

# Ausschnitt der Explanation mit BM25-Detailwerten:
# "description": "score(freq=1.0), computed as boost * idf * tf from:",
# "details": [
#   { "value": 2.2, "description": "boost" },
#   { "value": 4.1, "description": "idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from: n, N" },
#   {
#     "value": 0.87,
#     "description": "tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
#     "details": [
#       { "value": 1.0, "description": "freq, occurrences of term within document" },
#       { "value": 1.2, "description": "k1, term saturation parameter" },
#       { "value": 0.75, "description": "b, length normalization parameter" },
#       { "value": 42.0, "description": "dl, length of field" },
#       { "value": 38.5, "description": "avgdl, average length of field" }
#     ]
#   }
# ]

Wer die idf-Werte zwischen zwei Dokumenten vergleicht, erkennt sofort, ob ein Term im Gesamtindex selten (hoher idf, starker Einfluss) oder häufig (niedriger idf, schwacher Einfluss) ist. Das erklärt oft, warum ein scheinbar zentraler Suchbegriff nur wenig zum Score beiträgt, weil er im Index schlicht zu verbreitet ist, um noch als Unterscheidungsmerkmal zu wirken.

5. explain:true in _search statt Einzeldokument-Explain

Der _explain Endpoint eignet sich gut, wenn die verdächtige Dokument-ID bereits bekannt ist. Für die Analyse mehrerer Treffer gleichzeitig ist der Parameter "explain": true direkt im _search Request effizienter: Er liefert die Explanation für jeden zurückgegebenen Treffer in einem einzigen Request, sodass sich die Score-Zusammensetzung mehrerer Dokumente direkt nebeneinander vergleichen lässt.

Dieser Modus ist besonders hilfreich, um die Reihenfolge der Top-Treffer nachzuvollziehen: Warum steht Dokument A vor Dokument B, obwohl B intuitiv der bessere Treffer wäre? Mit explain:true lassen sich die beiden Explanation-Bäume Seite an Seite vergleichen und der entscheidende Unterschied, etwa ein fehlender Boost oder ein kürzeres Feld mit besserer Längen-Normalisierung, wird direkt sichtbar.

GET /produkte/_search
{
  "explain": true,
  "size": 5,
  "query": {
    "multi_match": {
      "query": "wanderschuhe wasserdicht",
      "fields": ["titel^3", "beschreibung"]
    }
  }
}

# Jeder Treffer im Response-Array enthaelt zusaetzlich:
# "_explanation": {
#   "value": 15.02,
#   "description": "max of:",
#   "details": [ ... ]
# }

Ein Hinweis zur Produktionsnutzung: explain: true erhöht die Antwortgröße und die Rechenzeit pro Query spürbar, weil für jeden Treffer die vollständige Berechnung mitgeliefert wird. Dieser Parameter gehört daher in Debugging-Sessions und automatisierte Relevanz-Tests, nicht in Live-Queries im Produktivbetrieb.

6. Typische Score-Anomalien erkennen und diagnostizieren

Eine der häufigsten Score-Anomalien ist ein Dokument, das trotz exakter Übereinstimmung im wichtigsten Feld niedriger rankt als ein Dokument mit nur teilweiser Übereinstimmung. Die Explain-Ausgabe zeigt in solchen Fällen häufig, dass das erste Dokument ein sehr langes Feld hat, wodurch die BM25-Längen-Normalisierung den tf-Anteil trotz exaktem Treffer deutlich dämpft. Die Lösung ist meist, ein zusätzliches, kürzeres Feld wie titel.exact für Boosting bei exakten Treffern einzurichten, statt sich allein auf das lange Volltext-Feld zu verlassen.

Eine zweite häufige Anomalie entsteht durch unerwartet niedrige idf-Werte: Ein Suchbegriff, der subjektiv als selten und relevant wahrgenommen wird, kommt im Index tatsächlich sehr häufig vor, etwa weil er Teil eines Boilerplate-Textes ist, der in jedem Dokument steht. Die Explain-Ausgabe deckt das über einen niedrigen idf-Wert sofort auf. Eine dritte Anomalie zeigt sich bei Function Score Queries, wenn eine additive oder multiplikative Funktion den textuellen Relevanz-Score komplett überlagert, sodass am Ende nur noch die Funktion, nicht mehr die eigentliche Textübereinstimmung, das Ranking bestimmt.

# Diagnose: Wieso rankt Dokument 99 vor Dokument 42, obwohl 42 der exaktere Treffer ist?
GET /produkte/_search
{
  "explain": true,
  "query": {
    "ids": { "values": ["42", "99"] }
  }
}
# Vergleich der beiden _explanation-Baeume zeigt haeufig:
# - Dokument 42: hohes dl (document length) -> tf gedaempft trotz freq=3
# - Dokument 99: niedriges dl -> tf naeher an 1.0 trotz freq=1

7. Explain mit Function Score und Boosting kombinieren

Function Score Queries multiplizieren oder addieren zusätzliche Signale wie Verkaufszahlen, Bewertungen oder Aktualität auf den textuellen Relevanz-Score. Die Explain-Ausgabe zeigt bei diesen Queries einen zusätzlichen Knoten mit der Beschreibung function score, product of: oder sum of:, je nach gewähltem score_mode, und listet darunter jede einzelne Funktion mit ihrem individuellen Beitrag auf. Das macht sichtbar, ob eine einzelne Funktion, etwa ein field_value_factor auf Verkaufszahlen, den textuellen Score dominiert.

Besonders aufschlussreich ist der Vergleich zwischen dem _score vor und nach Anwendung der Function Score. Übersteigt der Funktions-Beitrag den textuellen Relevanz-Anteil um ein Vielfaches, ist das ein starkes Indiz dafür, dass die Gewichtung der Funktion neu kalibriert werden sollte, etwa durch Normalisierung der Eingabewerte oder eine geringere weight-Angabe.

GET /produkte/_explain/4711
{
  "query": {
    "function_score": {
      "query": { "match": { "titel": "wanderschuhe" } },
      "functions": [
        { "field_value_factor": { "field": "verkaufszahl", "modifier": "log1p", "factor": 0.3 } }
      ],
      "boost_mode": "sum"
    }
  }
}

# Explanation zeigt getrennt:
# 1. Textueller BM25-Score aus dem match
# 2. function score, computed with field_value_factor
# 3. sum of: (finales Ergebnis aus boost_mode "sum")

8. Explain API und Aggregationen: die Grenzen des Werkzeugs

Die Explain API beantwortet ausschließlich Fragen zum Relevanz-Score einer Query, nicht zu Aggregationen. Wer wissen will, warum ein bestimmter Aggregations-Bucket eine bestimmte Anzahl an Dokumenten enthält oder warum eine Metric-Aggregation einen bestimmten Wert liefert, findet in der Explain API keine Antwort, weil Aggregationen komplett unabhängig von der Score-Berechnung laufen. Für solche Fragen helfen stattdessen gezielte Filter-Queries, um die Grundmenge der Aggregation manuell nachzuvollziehen.

Eine weitere Grenze betrifft constant_score und reine Filter-Kontexte: Dokumente, die nur über einen Filter gematcht werden, erhalten pauschal den Score 1.0 oder den konfigurierten boost-Wert, unabhängig von Term-Frequenz oder idf. Die Explain-Ausgabe zeigt hier entsprechend wenig Tiefe, weil in einem Filter-Kontext gar keine feingranulare Score-Berechnung stattfindet. Das ist kein Fehler der Explain API, sondern spiegelt exakt wider, dass Filter-Kontexte bewusst auf Scoring verzichten, um Performance zu gewinnen.

9. Von Explain zu Produktion: die Profile API als Ergänzung

Während die Explain API die inhaltliche Frage "Warum dieser Score?" beantwortet, beantwortet die verwandte _search Profile API die Performance-Frage "Warum dauert diese Query so lange?". Beide Werkzeuge ergänzen sich: Ein Score-Problem, das durch eine ineffiziente Query-Struktur mit vielen teuren should-Klauseln entsteht, zeigt sich in der Explain-Ausgabe als komplexer Baum und in der Profile-Ausgabe als hohe Ausführungszeit für genau diese Klauseln.

In der Praxis empfiehlt sich, Scoring-Debugging nicht als einmalige Aktion zu betrachten, sondern als festen Bestandteil der Relevanz-Pflege. Ein kleines Set an "goldenen Queries" mit erwarteter Trefferreihenfolge, regelmäßig mit explain:true gegen den aktuellen Index laufen gelassen, deckt Relevanz-Regressionen auf, bevor Nutzer sie in Form schlechterer Suchergebnisse bemerken.

Kein Werkzeug allein liefert das vollständige Bild. Erst die Kombination aus Explain API für die inhaltliche Score-Frage und Profile API für die Performance-Frage ermöglicht eine vollständige Diagnose, wenn eine Suche gleichzeitig falsch rankt und langsam ist.

10. Zusammenfassung

Die Explain API verwandelt Scoring-Debugging von einer Vermutung in eine nachvollziehbare Analyse. Der _explain Endpoint liefert die vollständige Score-Berechnung für ein einzelnes Dokument als verschachtelten Baum, während explain:true im _search Request denselben Einblick für mehrere Treffer gleichzeitig liefert und den direkten Vergleich zweier Rankings ermöglicht. Die BM25-Formel mit ihren Komponenten boost, idf und tf lässt sich in der Explain-Ausgabe Schritt für Schritt nachvollziehen, inklusive der Längen-Normalisierung, die kurze, präzise Dokumente gegenüber langen Fließtexten bevorzugt.

Typische Score-Anomalien wie ein durch Dokumentlänge gedämpfter tf-Wert oder ein von Function Score überlagerter Textscore lassen sich mit der Explain API gezielt diagnostizieren. Wichtig ist, die Grenzen des Werkzeugs zu kennen: Aggregationen und reine Filter-Kontexte liegen außerhalb der Score-Erklärung. In Kombination mit der Profile API für Performance-Fragen deckt die Explain API damit den Großteil der praktischen Scoring-Debugging-Fälle ab.

11. FAQ: Explain API für Scoring-Debugging