Match vs. Term Query: der Unterschied, der Ergebnisse veraendert

1. Zwei Queries, zwei grundverschiedene Welten

Die Match Query und die Term Query gehoeren zu den ersten beiden Queries, die jeder Elasticsearch-Einsteiger lernt, und genau deshalb entstehen bei ihnen die meisten Anfaengerfehler. Beide nehmen scheinbar dasselbe Grundmuster: ein Feldname und ein Suchwert. Doch was Elasticsearch mit diesem Suchwert intern macht, unterscheidet sich fundamental. Die Match Query schickt den Suchtext durch denselben Analyzer, der auch beim Indexieren verwendet wurde, die Term Query vergleicht den Suchwert exakt und byte-genau mit dem gespeicherten Wert, ohne jede Vorverarbeitung.

Dieser Unterschied ist keine akademische Feinheit, sondern die Ursache fuer eine der haeufigsten Support-Anfragen bei jeder Suchintegration: "Die Suche findet nichts, obwohl der Begriff eindeutig im Dokument steht." In fast allen Faellen liegt die Ursache darin, dass eine Term Query auf einem Text-Feld verwendet wurde, das beim Indexieren durch einen Analyzer in Kleinbuchstaben-Tokens zerlegt wurde, waehrend die Term Query den Originalwert unveraendert sucht.

Der vorliegende Artikel klaert genau diesen Unterschied auf: wie die Match Query analysiert, wie die Term Query exakt vergleicht, warum Keyword-Felder und Text-Felder unterschiedliche Anwendungsfaelle bedienen und wie Multi-Fields beide Welten gleichzeitig verfuegbar machen, ohne Kompromisse einzugehen.

2. Match Query: analysierte Suche verstehen

Die Match Query ist die Standard-Query fuer Volltextsuche in Elasticsearch. Wenn eine Match Query auf ein Text-Feld ausgefuehrt wird, laeuft der Suchbegriff durch denselben Analyzer, der bei der Indexierung dieses Feldes verwendet wurde. Ein Standard-Analyzer wandelt den Text in Kleinbuchstaben um, entfernt Satzzeichen und zerlegt ihn in einzelne Tokens. Sucht ein Nutzer nach "Laufschuhe Nike", wird daraus intern die Token-Liste ["laufschuhe", "nike"], die gegen die beim Indexieren erzeugten Tokens verglichen wird.

Diese Analyse macht die Match Query robust gegenueber Gross- und Kleinschreibung, unterschiedlicher Wortreihenfolge und, je nach Analyzer-Konfiguration, sogar gegenueber Wortformen durch Stemming. Standardmaessig verhaelt sich eine Match Query mit mehreren Tokens wie eine should-Verknuepfung: mindestens ein Token muss treffen, wobei mehr Treffer zu einem hoeheren Score fuehren. Ueber den Parameter operator laesst sich dieses Verhalten auf AND umstellen, sodass alle Tokens vorhanden sein muessen.

Ein wichtiger Aspekt der Match Query ist, dass sie ausschliesslich auf Feldern funktioniert, die tatsaechlich analysiert und tokenisiert gespeichert wurden, also auf Feldern vom Typ text. Auf einem keyword-Feld, das den Originalwert unveraendert als einen einzigen Token speichert, liefert die Match Query zwar technisch ein Ergebnis, verhaelt sich dabei aber praktisch wie eine exakte Suche, weil kein Tokenizing stattfindet.

GET /products/_search
{
  "query": {
    "match": {
      "title": {
        "query": "Laufschuhe NIKE",
        "operator": "and"
      }
    }
  }
}
// The search string is lowercased and tokenized before comparison
// Matches "nike laufschuhe", "Laufschuhe von Nike", etc.

3. Term Query: der exakte, ungefilterte Vergleich

Die Term Query vergleicht den angegebenen Suchwert exakt mit dem im invertierten Index gespeicherten Term, ohne jede Analyse. Das bedeutet: Gross- und Kleinschreibung muessen exakt uebereinstimmen, Sonderzeichen bleiben erhalten, es findet keine Tokenisierung statt. Eine Term Query mit dem Wert "Nike" findet ein Dokument mit dem gespeicherten Wert "nike" nicht, weil die beiden Strings byte-genau unterschiedlich sind.

Dieses Verhalten macht die Term Query zum richtigen Werkzeug fuer strukturierte Daten, bei denen Exaktheit gewuenscht ist: Status-Codes, IDs, SKUs, E-Mail-Adressen in Rohform oder Enum-artige Werte wie Farben oder Groessen, sofern diese als keyword-Feld indexiert wurden. Eine term-Query auf {"status": "active"} liefert nur Dokumente, deren Status-Feld exakt "active" enthaelt, kein "Active", kein "ACTIVE", kein Teiltreffer.

Ein haeufig uebersehener Aspekt der Term Query: sie laeuft typischerweise im Filter-Kontext, wenn sie innerhalb der filter-Klausel einer Bool Query verwendet wird, und ist dann sowohl guenstig zu berechnen als auch cachebar. Ausserhalb eines Filter-Kontexts liefert die Term Query trotzdem einen Score, aber dieser Score ist bei exakten Uebereinstimmungen meist wenig aussagekraeftig, da es keine graduelle Aehnlichkeit gibt, sondern nur Treffer oder kein Treffer.

GET /products/_search
{
  "query": {
    "term": {
      "status.keyword": "active"
    }
  }
}
// Exact, unanalyzed comparison
// "Active" or "ACTIVE" will NOT match this query

4. Was der Analyzer beim Indexieren wirklich tut

Um Match Query und Term Query wirklich zu verstehen, muss man wissen, was beim Indexieren eines text-Feldes passiert. Ein Analyzer besteht aus drei Stufen: einem Character-Filter, der den Rohtext vorverarbeitet, einem Tokenizer, der den Text in einzelne Tokens zerlegt, und einer Kette von Token-Filtern, die diese Tokens weiter transformieren, etwa durch Kleinschreibung oder Entfernung von Stopwoertern. Der Standard-Analyzer von Elasticsearch nutzt den standard-Tokenizer und die Filter lowercase und optional stop.

Das Ergebnis dieser Analyse landet im invertierten Index, nicht der Originaltext. Fuer ein Dokument mit dem Titel "Wasserdichte Laufschuhe" speichert Elasticsearch die Tokens ["wasserdichte", "laufschuhe"] im invertierten Index des text-Feldes. Genau diese Tokens sind es, gegen die eine Match Query nach der Analyse ihres eigenen Suchbegriffs vergleicht, und genau deshalb funktioniert die Match Query zuverlaessig, waehrend eine Term Query mit dem Originalwert "Wasserdichte Laufschuhe" ins Leere laeuft.

Mit der _analyze-API laesst sich exakt nachvollziehen, welche Tokens ein Analyzer fuer einen gegebenen Text produziert. Dieses Debugging-Werkzeug ist bei jeder Diskrepanz zwischen erwarteten und tatsaechlichen Suchergebnissen der erste Anlaufpunkt, weil es die Blackbox der Analyse sichtbar macht.

GET /products/_analyze
{
  "analyzer": "standard",
  "text": "Wasserdichte Laufschuhe, Groesse 42!"
}
// Response tokens: ["wasserdichte", "laufschuhe", "groesse", "42"]
// Punctuation removed, everything lowercased, split into tokens

5. Der klassische Fehler: keyword vs. text Feld

Der mit Abstand haeufigste Fehler im Zusammenspiel von Match Query und Term Query ist die Verwendung einer Term Query auf einem text-Feld. Weil ein text-Feld analysiert und in Kleinbuchstaben-Tokens zerlegt gespeichert wird, sucht eine Term Query mit dem Originalwert praktisch nie erfolgreich, ausser der Suchwert ist zufaellig bereits vollstaendig kleingeschrieben und besteht aus genau einem Token. Umgekehrt ist der zweite haeufige Fehler die Verwendung einer Match Query auf einem keyword-Feld in der Erwartung, dass eine Teilstring-Suche funktioniert, was sie nicht tut, weil ein Keyword-Feld nicht tokenisiert wird.

Diese Verwirrung entsteht, weil beide Query-Typen syntaktisch aehnlich aussehen und Elasticsearch keinen Fehler wirft, wenn eine Term Query auf ein Text-Feld angewendet wird, sie liefert einfach leise leere Ergebnisse. Genau diese Stille macht den Fehler so tueckisch: es gibt keine Exception, keine Warnung, nur eine unerwartet leere Trefferliste, die Entwickler oft zuerst bei der Datenqualitaet oder beim Indexierungsprozess suchen lassen, statt beim Query-Typ selbst.

Die Faustregel lautet: fuer freie Texteingaben von Nutzern, bei denen Tippvarianten, Gross-Kleinschreibung und Wortreihenfolge toleriert werden sollen, ist die Match Query richtig. Fuer strukturierte, kontrollierte Werte wie IDs, Statuscodes, Kategorienamen aus einer festen Liste oder SKUs ist die Term Query auf einem Keyword-Feld richtig. Wer diese Regel konsequent anwendet, vermeidet den Grossteil der Verwirrung zwischen Match Query und Term Query.

6. Multi-Fields: beide Welten gleichzeitig nutzen

Elasticsearch loest den scheinbaren Konflikt zwischen Match Query und Term Query elegant ueber Multi-Fields: dasselbe Datenfeld wird gleichzeitig als text-Feld fuer die Match Query und als keyword-Unterfeld fuer die Term Query indexiert. Das Mapping legt dafuer ein fields-Objekt innerhalb der Feld-Definition an, typischerweise unter dem Namen keyword. Der Zugriff auf das Unterfeld erfolgt dann ueber die Punktnotation, etwa title.keyword.

Diese Struktur erlaubt, ein und dasselbe Produktfeld sowohl fuer die Volltextsuche mit Match Query als auch fuer exaktes Filtern, Sortieren und Aggregieren mit Term Query zu nutzen, ohne Daten doppelt zu speichern oder ein zweites Feld manuell zu pflegen. Sortierung nach einem text-Feld ist ohnehin nicht direkt moeglich, weil sortiert immer nach dem exakten, ungefilterten Wert werden muss, weshalb das keyword-Unterfeld auch fuer Sortierung essentiell ist.

In der Praxis ist die Multi-Field-Struktur der Standardfall fuer fast jedes textuelle Produktattribut in einer E-Commerce-Suche: der Produkttitel wird per Match Query durchsucht, dieselbe Information wird per Term Query auf title.keyword fuer exakte Duplikatpruefungen oder Aggregationen genutzt.

PUT /products
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword",
            "ignore_above": 256
          }
        }
      }
    }
  }
}
// title      -> full-text search with match query
// title.keyword -> exact match, sorting, aggregations with term query

7. Wann Match, wann Term: Entscheidungskriterien

Die Entscheidung zwischen Match Query und Term Query laesst sich anhand weniger Kriterien treffen. Erstens: kommt der Suchwert direkt von einer Nutzereingabe in einem Suchfeld, ist die Match Query fast immer richtig, weil sie Toleranz gegenueber Schreibvarianten bietet. Zweitens: kommt der Wert aus einer geschlossenen Auswahl, einem Dropdown, einem internen System oder einer ID, ist die Term Query richtig, weil hier Exaktheit gewuenscht ist und Toleranz sogar unerwuenscht waere.

Drittens: soll das Ergebnis fuer Relevanz-Sortierung genutzt werden, spricht das fuer Match Query im Scoring-Kontext. Soll das Ergebnis nur die Trefferliste einschraenken, spricht das fuer Term Query im Filter-Kontext, idealerweise innerhalb der filter-Klausel einer Bool Query fuer maximale Performance. Diese Kombination, Match Query fuer den Suchtext in must und Term Query fuer strukturierte Kriterien in filter, ist die in der Praxis am haeufigsten korrekte Struktur.

8. terms Query und Varianten im Ueberblick

Neben der einfachen Term Query gibt es die terms-Query, den Plural, die gegen eine Liste von Werten prueft und ein Dokument matcht, sobald mindestens einer der Werte exakt zutrifft. Sie ist das Aequivalent zu einem SQL IN-Vergleich und deutlich effizienter als mehrere term-Queries in einer should-Klausel zu kombinieren, weil Elasticsearch die Liste intern optimiert auswerten kann. Fuer Facettenfilter, bei denen ein Nutzer mehrere Kategorien oder Marken gleichzeitig auswaehlt, ist die terms-Query das richtige Werkzeug.

Auf der Match-Seite existiert analog die multi_match-Query, die denselben analysierten Suchbegriff gleichzeitig gegen mehrere Text-Felder prueft, etwa Titel und Beschreibung, mit individueller Gewichtung je Feld. Beide Varianten, terms und multi_match, folgen demselben Grundprinzip wie ihre Basis-Queries, erweitern es aber jeweils um die Moeglichkeit, mehrere Werte beziehungsweise mehrere Felder in einem Aufruf zu pruefen.

GET /products/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "multi_match": {
            "query": "laufschuhe wasserdicht",
            "fields": ["title^2", "description"]
          }
        }
      ],
      "filter": [
        { "terms": { "brand.keyword": ["nike", "adidas", "puma"] } }
      ]
    }
  }
}
// multi_match runs the analyzed query against title and description
// terms checks brand.keyword against a list of exact values

9. Fehlersuche: warum eine Query keine Treffer liefert

Wenn eine Term Query oder eine Match Query unerwartet keine Treffer liefert, ist die _analyze-API der erste Debugging-Schritt, um zu pruefen, welche Tokens tatsaechlich im Index landen. Der zweite Schritt ist ein Blick auf das Mapping mit der _mapping-API, um zu bestaetigen, ob das verwendete Feld tatsaechlich vom erwarteten Typ ist, text oder keyword. Ein sehr haeufiges Muster: ein Feld heisst zwar "category", aber gemeint ist eigentlich das Multi-Field category.keyword, und die Query wurde versehentlich gegen das falsche Unterfeld formuliert.

Ein dritter Debugging-Schritt ist die explain-Option in der Search-API, die fuer jedes Dokument detailliert aufschluesselt, wie der Score zustande kam oder warum ein Dokument nicht in der Ergebnisliste erscheint. In Kombination mit der _analyze-API und einem Blick ins Mapping lassen sich fast alle Diskrepanzen zwischen Match Query und Term Query innerhalb weniger Minuten aufklaeren, statt stundenlang an der falschen Stelle nach dem Fehler zu suchen.

10. Zusammenfassung

Die Match Query analysiert Suchtext vor dem Vergleich und ist die richtige Wahl fuer freie Nutzereingaben auf text-Feldern. Die Term Query vergleicht exakt, ohne Analyse, und ist die richtige Wahl fuer strukturierte Werte auf keyword-Feldern. Der haeufigste Fehler entsteht, wenn eine Term Query auf einem analysierten Text-Feld verwendet wird und leise leere Ergebnisse liefert, statt einen Fehler zu werfen.

Multi-Fields loesen diesen Konflikt strukturell, indem dasselbe Datenfeld gleichzeitig als text und als keyword-Unterfeld indexiert wird. In der Praxis kombiniert eine gute Suchanfrage beide Query-Typen: Match Query fuer den Suchtext im Scoring-Kontext, Term Query fuer strukturierte Filterkriterien im Filter-Kontext einer Bool Query. Die _analyze-API bleibt das wichtigste Werkzeug, um bei unerwarteten Ergebnissen schnell zu verstehen, was der Analyzer tatsaechlich produziert hat.

11. FAQ: Match vs. Term Query