Die Terms-Enum-API für effiziente Autocomplete-Quellen in Elasticsearch

1. Das Grundproblem: leichtgewichtiges Autocomplete ohne Overhead

Autocomplete-Vorschläge für Marken- oder Kategorienamen brauchen selten ausgefeiltes Scoring, Fuzzy-Matching oder kontextabhängige Gewichtung, wie sie ein vollwertiger Completion-Suggester bietet. Meist genügt eine schnelle, alphabetisch sortierte Liste aller Werte, die mit der bisherigen Nutzereingabe beginnen, etwa alle Marken, die mit bos anfangen. Einen Completion-Suggester dafür aufzusetzen bedeutet zusätzlichen Mapping-Aufwand mit einem eigenen completion-Feld, das bei jeder Indexierung separat befüllt und synchron gehalten werden muss.

Die Terms-Enum-API verfolgt einen anderen Ansatz: Statt Dokumente zu durchsuchen, iteriert sie direkt über den bereits vorhandenen Termindex eines regulären keyword-Feldes und liefert die eindeutigen Werte zurück, die mit einem gegebenen Präfix beginnen. Da diese Werte ohnehin für die normale Suche und Aggregationen indexiert sind, entsteht dabei kein zusätzlicher Speicher- oder Pflegeaufwand.

2. Grundlagen: wie die Terms-Enum-API Präfix-Matches liefert

Ein Aufruf der _terms_enum-API erwartet mindestens das Zielfeld und einen Präfixstring, und liefert eine Liste eindeutiger Termwerte zurück, die mit diesem Präfix beginnen, standardmäßig auf die zehn häufigsten begrenzt über den Parameter size. Die Antwort enthält außerdem ein Feld complete, das angibt, ob wirklich alle passenden Terme in der Antwort enthalten sind oder ob aus Performance-Gründen ein Zeitlimit oder eine Shard-Grenze die Suche vorzeitig beendet hat.

Anders als eine normale Suchanfrage wertet die Terms-Enum-API keine Relevanz und kein Scoring aus, die zurückgegebene Reihenfolge orientiert sich stattdessen an der internen Sortierung des Termindex, meist alphabetisch innerhalb eines Segments. Für ein Autocomplete-Feld ist das in der Regel ausreichend, da hier ohnehin eine einfache alphabetische oder nach Häufigkeit sortierte Liste erwartet wird und keine inhaltliche Relevanzbewertung nötig ist.

POST /produkte/_terms_enum
{
  "field": "marke",
  "string": "bos",
  "size": 10
}

// Antwort:
{
  "terms": ["bosch", "boston_gear"],
  "complete": true
}

3. Groß-/Kleinschreibung, Zeitlimit und Fehlertoleranz

Über den Parameter case_insensitive lässt sich steuern, ob die Präfixsuche Groß- und Kleinschreibung berücksichtigt, was bei nutzergetippten Eingaben in einem Suchfeld praktisch immer sinnvoll ist, da Nutzer selten konsequent auf Groß- und Kleinschreibung achten. Zusätzlich unterstützt die API einen optionalen regulären Ausdruck über string hinaus für komplexere Musterabgleiche, was jedoch für ein einfaches Präfix-Autocomplete selten benötigt wird.

Der Parameter timeout begrenzt die maximale Ausführungszeit pro Shard und verhindert, dass eine Anfrage auf einem sehr großen, fragmentierten Termindex unkontrolliert lange läuft. Läuft das Zeitlimit ab, bevor alle Shards vollständig geantwortet haben, liefert die API die bis dahin gesammelten Ergebnisse zurück und markiert complete als false, was die Anwendung als Hinweis nutzen kann, dass die Vorschlagsliste möglicherweise unvollständig ist.

4. Abgrenzung zum Completion-Suggester

Der Completion-Suggester ist für Autocomplete konzipiert, das echtes Relevanz-Ranking, Gewichtung einzelner Vorschläge, Fuzzy-Matching bei Tippfehlern und kontextabhängige Filterung benötigt, etwa um Vorschläge nach Region oder Nutzerprofil zu priorisieren. Dafür braucht er ein eigenes completion-Feld im Mapping, das bei der Indexierung explizit mit den gewünschten Eingabetexten und optionalen Gewichten befüllt werden muss, was zusätzlichen Pflegeaufwand bedeutet, sobald sich Quelldaten ändern.

Die Terms-Enum-API benötigt dagegen kein separates Feld und keine zusätzliche Datenpflege, arbeitet direkt auf einem bereits vorhandenen keyword-Feld und eignet sich damit besonders für Felder mit überschaubarer Kardinalität, bei denen ohnehin schon feste, kontrollierte Werte vorliegen, wie Marken, Kategorien oder Hersteller. Für Freitext-Autocomplete mit sehr vielen unterschiedlichen möglichen Werten und dem Bedarf an echtem Relevanz-Ranking bleibt der Completion-Suggester die bessere Wahl.

5. Praxisbeispiel: Marken- und Kategorienamen-Autocomplete

Im praktischen Szenario tippt ein Nutzer im Filterfeld einer Suchoberfläche die ersten Buchstaben eines Markennamens, und die Anwendung ruft bei jedem Tastendruck die Terms-Enum-API mit dem aktuellen Präfix gegen das marke-Feld auf. Da das Feld ohnehin als keyword für Filterung und Facetten indexiert ist, entstehen keine zusätzlichen Indexierungskosten, die Vorschlagsliste nutzt exakt dieselben Werte, die auch für die eigentliche Produktfilterung verwendet werden.

Für Kategorienamen funktioniert derselbe Ansatz identisch, mit dem zusätzlichen Vorteil, dass sich die Terms-Enum-Anfrage bei Bedarf mit einem index_filter kombinieren lässt, um nur Kategorien vorzuschlagen, die tatsächlich aktuell verfügbare Produkte enthalten, statt veraltete oder leere Kategorien mit anzuzeigen.

POST /produkte/_terms_enum
{
  "field": "kategorie",
  "string": "werk",
  "case_insensitive": true,
  "index_filter": {
    "range": { "lagerbestand": { "gt": 0 } }
  }
}

6. Performance-Charakteristik im Vergleich zur klassischen Suche

Weil die Terms-Enum-API keine Dokumente lädt, keine Relevanz berechnet und kein Highlighting durchführt, ist sie in der Regel deutlich schneller als eine äquivalente match_phrase_prefix-Suche oder eine Aggregation mit Präfix-Filterung auf demselben Feld. Der Zugriff erfolgt nahezu direkt auf die Datenstruktur des Termindex, wodurch sich die Antwortzeiten auch bei sehr häufigen Autocomplete-Anfragen pro Tastendruck gut im niedrigen Millisekundenbereich halten lassen.

Bei Feldern mit sehr hoher Kardinalität, etwa einer freien Texteingabe mit Millionen unterschiedlicher Werte, steigt dennoch der Aufwand für das Durchsuchen des Termindex spürbar an, insbesondere wenn viele Segmente mit jeweils eigenem Termindex durchlaufen werden müssen. Für Felder mit überschaubarer, kontrollierter Wertemenge wie Marken oder Kategorien bleibt die Performance jedoch praktisch konstant unabhängig von der Gesamtzahl der Dokumente im Index.

7. Grenzen: wofür die Terms-Enum-API nicht geeignet ist

Die Terms-Enum-API eignet sich nicht für Fuzzy-Matching bei Tippfehlern, da sie ausschließlich exakte Präfixe gegen den Termindex prüft und keine Editierdistanz oder ähnliche Toleranzmechanismen unterstützt. Ebenso fehlt jede Form von Gewichtung oder Priorisierung einzelner Vorschläge nach Popularität oder Geschäftslogik, jeder passende Term erscheint gleichwertig in der Antwort, sortiert nur nach interner Termindex-Reihenfolge.

Für mehrsprachige Autocomplete-Anforderungen mit unterschiedlichen Sprachvarianten desselben Begriffs oder für Freitext-Volltextsuche mit Tokenisierung ist die Terms-Enum-API ebenfalls ungeeignet, da sie direkt auf unanalysierten keyword-Werten arbeitet und keine Analyzer-Logik anwendet. In solchen Fällen bleibt entweder der Completion-Suggester oder eine klassische match_phrase_prefix-Query die passendere Lösung.

8. Kombination mit index_filter für kontextabhängige Vorschläge

Der optionale Parameter index_filter erlaubt es, die Terms-Enum-Anfrage auf eine Teilmenge der Dokumente zu beschränken, bevor der Termindex durchsucht wird, etwa nur Dokumente eines bestimmten Shops oder einer bestimmten Sprache. Damit lassen sich kontextabhängige Vorschlagslisten realisieren, ohne dass dafür separate Indizes je Kontext gepflegt werden müssen, was den Wartungsaufwand gegenüber mehreren dedizierten Completion-Suggester-Feldern erheblich reduziert.

Wichtig ist dabei, dass ein gesetzter index_filter zusätzlichen Auswertungsaufwand bedeutet, da Elasticsearch für jeden potenziellen Term prüfen muss, ob mindestens ein passendes Dokument den Filter erfüllt. Bei sehr restriktiven Filtern in Kombination mit sehr großen Termindizes lohnt sich deshalb ein Blick auf die tatsächliche Antwortzeit unter realistischer Last, bevor der Ansatz produktiv für hochfrequentierte Autocomplete-Felder eingesetzt wird.

9. Einsatzentscheidung: eine kurze Checkliste

Die Terms-Enum-API eignet sich, wenn das Zielfeld bereits als keyword indexiert ist, die Wertemenge überschaubar bleibt und kein echtes Relevanz-Ranking oder Fuzzy-Matching benötigt wird, typischerweise bei Marken, Kategorien, Herstellernamen oder ähnlichen kontrollierten Attributen. Sobald Tippfehlertoleranz, Gewichtung nach Popularität oder kontextabhängiges Scoring gefragt sind, führt an einem vollwertigen Completion-Suggester kein Weg vorbei.

In der Praxis lohnt sich häufig eine Kombination beider Ansätze im selben System: Terms-Enum für schnelle, leichtgewichtige Filtervorschläge auf strukturierten Attributfeldern, und Completion-Suggester dort, wo echte Volltext-Autocomplete-Qualität mit Relevanzbewertung gefragt ist, etwa bei der globalen Produktsuche über Freitext.

10. Zusammenfassung

11. FAQ: Terms-Enum-API: Das Wichtigste auf einen Blick