Such-Synonyme in Magento sauber verwalten

1. Warum Such-Synonyme direkt den Umsatz beeinflussen

Kunden suchen nicht mit den Produktbezeichnungen, die im Katalog hinterlegt sind. Wer "Turnschuhe" eingibt, findet ohne Such-Synonyme keine Produkte, die im PIM als "Sneaker" gepflegt sind. Wer nach "Kuehlschrank" sucht, geht leer aus, wenn der Hersteller im Titel konsequent "Kuehl-Gefrier-Kombination" verwendet. Jede fehlgeschlagene Suche ist ein Kunde, der die Seite verlaesst, ohne zu kaufen. In Conversion-Analysen zeigt sich regelmaessig, dass Sessions mit einer "Zero Result"-Suche eine deutlich niedrigere Konversionsrate haben als Sessions ohne Sucheingabe ueberhaupt.

Magento liefert dafuer ein eingebautes Feature, das oft unterschaetzt wird: Synonymgruppen im Admin, die store-view-spezifisch gepflegt werden koennen. Der Mechanismus ist nicht kompliziert, aber er hat Ecken, an denen Teams regelmaessig scheitern, weil sie annehmen, eine gespeicherte Synonymgruppe wirke sofort und global. Tatsaechlich sind Such-Synonyme in Magento eng an den Store View und an den Reindex-Zyklus des catalogsearch_fulltext-Indexers gekoppelt. Wer diesen Zusammenhang nicht kennt, verliert Zeit mit Debugging, waehrend das eigentliche Problem eine fehlende Reindex-Ausfuehrung ist.

Dieser Artikel geht den kompletten Lebenszyklus von Such-Synonymen durch: von der Eingabe im Admin ueber die interne Datenhaltung bis zur Uebersetzung in einen Elasticsearch synonym-Filter, inklusive Testverfahren und einem Prozess, mit dem auch Nicht-Entwickler Synonyme sicher pflegen koennen.

2. Synonymgruppen im Magento Admin anlegen

Synonymgruppen finden sich im Backend unter Marketing > SEO & Suche > Suchsynonyme. Eine Synonymgruppe ist eine kommagetrennte Liste von Begriffen, die Magento als gegenseitig austauschbar behandeln soll. Jede Gruppe wird einem Scope zugewiesen: entweder "All Store Views" oder ein konkreter Store View. Diese Scope-Bindung ist entscheidend, denn Such-Synonyme fuer den deutschen Store View sollten nicht automatisch im englischen Store View auftauchen, wo "Sneaker" bereits der gaengige Begriff ist und keine Uebersetzung braucht.

Beim Anlegen prueft Magento serverseitig, ob ein Begriff bereits in einer anderen Gruppe desselben Store Views vorkommt, und verweigert bei Konflikten das Speichern. Das verhindert widerspruechliche Synonymketten, in denen ein Wort in zwei unterschiedlichen Gruppen mit unterschiedlicher Bedeutung auftaucht. Fuer den produktiven Einsatz empfiehlt es sich, Synonymgruppen thematisch zu clustern, etwa eine Gruppe pro Produktkategorie, statt eine einzige riesige Liste zu pflegen, die niemand mehr ueberblickt.

Intern landet jede Synonymgruppe in der Tabelle search_synonyms mit den Spalten synonym_group_id, store_id und synonyms, wobei store_id = 0 fuer den Scope "All Store Views" steht. Diese einfache Struktur macht es leicht, Synonyme auch ausserhalb der Admin-UI zu inspizieren, etwa fuer Audits oder automatisierte Konsistenzpruefungen vor einem Release.

3. Wie Magento Such-Synonyme in Elasticsearch abbildet

Der eigentliche Mechanismus hinter Such-Synonymen passiert nicht zur Suchzeit, sondern zur Indexzeit. Wenn der catalogsearch_fulltext-Indexer laeuft, liest Magento die aktiven Synonymgruppen fuer den jeweiligen Store aus der Tabelle search_synonyms und baut daraus dynamisch einen Elasticsearch synonym-Token-Filter, der Teil der Analyzer-Kette des Index wird. Das bedeutet: Such-Synonyme sind kein Laufzeit-Feature der Suchanfrage, sondern eine Eigenschaft des Index selbst, die bei jedem Store einen eigenen, dedizierten Elasticsearch-Index mit eigenen Analyzer-Settings erzeugt.

Diese Architekturentscheidung hat einen wichtigen Nebeneffekt: Aendert man eine Synonymgruppe, wirkt die Aenderung erst, nachdem der Index fuer diesen Store neu aufgebaut wurde. Der Analyzer wird beim Erstellen des Index festgelegt und laesst sich bei Elasticsearch nicht nachtraeglich auf einem offenen Index aendern, ohne den Index zu schliessen und neu zu oeffnen. Magento kapselt diesen Vorgang beim vollstaendigen Reindex, sodass Entwickler ihn normalerweise nicht manuell nachvollziehen muessen, aber es erklaert, warum ein reiner Partial-Reindex nach Produktaenderungen keine neuen Such-Synonyme aktiviert.

{
  "settings": {
    "analysis": {
      "filter": {
        "synonym_filter_store_1": {
          "type": "synonym_graph",
          "synonyms": [
            "turnschuhe, sneaker, sportschuhe",
            "kuehlschrank, kuehl-gefrier-kombination",
            "notebook, laptop"
          ]
        }
      },
      "analyzer": {
        "catalog_search_analyzer_store_1": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "synonym_filter_store_1",
            "german_stemmer"
          ]
        }
      }
    }
  }
}

4. Unidirektional vs. bidirektional: die richtige Syntax waehlen

Elasticsearch unterscheidet zwei Formen von Synonymen, und Magentos Synonymgruppen bilden nur die bidirektionale Form direkt ab. Eine kommagetrennte Liste wie turnschuhe, sneaker, sportschuhe bedeutet: jeder Begriff ist durch jeden anderen ersetzbar, in beide Richtungen. Sucht ein Kunde nach "sneaker", findet er auch Produkte, die nur "turnschuhe" im Titel tragen, und umgekehrt. Das ist fuer echte Synonympaare korrekt, fuehrt aber bei ungleichwertigen Begriffen zu unerwuenschten Treffern.

Fuer unidirektionale Zuordnungen, etwa Markennamen zu Kategoriebegriffen ("iphone" soll "smartphone"-Treffer liefern, aber nicht jede Smartphone-Suche soll iPhones bevorzugen), braucht es die =>-Syntax des Elasticsearch synonym-Filters. Magentos Standard-UI unterstuetzt das nicht direkt, weshalb solche Faelle ueber ein Plugin auf den SynonymReader oder einen eigenen Indexer-Patch geloest werden, der die Synonymliste vor der Uebergabe an Elasticsearch um =>-Regeln erweitert. Wer diese Erweiterung nicht vornimmt, muss bei asymmetrischen Begriffspaaren akzeptieren, dass die Symmetrie der bidirektionalen Form gilt.

5. Store-View-Scope: der haeufigste Fehler bei Such-Synonymen

Der mit Abstand haeufigste Supportfall rund um Such-Synonyme ist eine Gruppe, die im falschen Scope angelegt wurde. Ein Redakteur legt eine Synonymgruppe im Default Store View an, testet dort erfolgreich, aber der eigentliche Produktivshop laeuft ueber einen anderen Store View mit eigenem Store Code. Da jeder Store View in Multi-Site-Setups einen eigenen Elasticsearch-Index mit eigenem Analyzer bekommt, wirkt die Synonymgruppe im produktiven Store nicht, obwohl sie im Admin sichtbar und "aktiv" aussieht.

Bei internationalen Shops mit mehreren Sprachen kommt eine zweite Fallstricke hinzu: Synonyme sind sprachabhaengig, und eine Gruppe im Scope "All Store Views" wird fuer jeden Store View identisch angewendet, auch fuer Sprachen, in denen die Begriffe keinen Sinn ergeben oder sogar falsch sind. Die Empfehlung lautet deshalb, Such-Synonyme nur in Ausnahmefaellen global anzulegen und im Regelfall pro Store View oder pro Sprachgruppe zu pflegen, auch wenn das mehr Pflegeaufwand bedeutet, weil sich Begriffe zwischen Store Views mit derselben Sprache oft doppeln.

# List all store views with their locale to plan synonym scope correctly
bin/magento store:list

# Example output
# +----+---------+-------+
# | ID | Code    | Name  |
# +----+---------+-------+
# | 1  | default | DE    |
# | 2  | at      | AT    |
# | 3  | en      | EN    |
# +----+---------+-------+
# Store 1 and 2 share German, but AT often needs its own regional synonym set

6. Reindex-Verhalten: wann Synonyme wirklich aktiv werden

Weil der Synonym-Filter Teil der Analyzer-Definition ist, muss der catalogsearch_fulltext-Indexer den betroffenen Elasticsearch-Index vollstaendig neu aufbauen, damit neue Such-Synonyme greifen. Im "Update on Save"-Modus laeuft dieser Rebuild synchron beim Speichern der Synonymgruppe, was bei grossen Katalogen den Admin-Request spuerbar blockiert. Im "Update by Schedule"-Modus (mview) markiert Magento den Indexer stattdessen als invalid, und der Cron-Job indexer_reindex_all_invalid uebernimmt den Rebuild im Hintergrund, was die UI schneller macht, aber eine sichtbare Verzoegerung bis zur Wirkung der Synonyme mit sich bringt.

Fuer Teams, die Synonyme haeufig anpassen, empfiehlt sich ein expliziter manueller Trigger direkt nach dem Speichern, statt auf den naechsten Cron-Zyklus zu warten. So laesst sich in Staging-Umgebungen sofort verifizieren, ob eine neue Synonymgruppe wie erwartet wirkt, bevor sie live geschaltet wird.

# Force immediate reindex after editing search synonyms
bin/magento indexer:reindex catalogsearch_fulltext

# Check indexer status before and after
bin/magento indexer:status catalogsearch_fulltext

# Example output after a synonym change, before reindex
# Title: Catalog Search
# Status: Invalid
# Latest updated: 2026-07-24 09:12:03

# After running indexer:reindex
# Status: Ready

7. Such-Synonyme mit der Analyze API testen

Statt Suchbegriffe blind im Shop-Frontend durchzuprobieren, laesst sich der Analyzer eines Store-Index direkt gegen Elasticsearch testen. Die _analyze-API nimmt einen Text und den Namen des Analyzers entgegen und gibt zurueck, in welche Tokens der Text zerlegt wird, inklusive aller vom Such-Synonyme-Filter hinzugefuegten Alternativtokens. Das ist der zuverlaessigste Weg, um zu pruefen, ob eine Synonymgruppe tatsaechlich im Index angekommen ist, ohne den Umweg ueber das Frontend und moegliche weitere Filter wie Sichtbarkeit oder Lagerbestand.

Diese Methode eignet sich auch hervorragend fuer automatisierte Tests: Ein einfaches Skript kann nach jedem Deployment pruefen, ob die erwarteten Synonym-Tokens im Analyzer-Output auftauchen, und einen Alarm ausloesen, wenn eine Aenderung an der Indexkonfiguration versehentlich Synonyme entfernt hat.

POST /magento2_default_catalogsearch_fulltext_1/_analyze
{
  "analyzer": "catalog_search_analyzer_store_1",
  "text": "turnschuhe"
}

// Expected response fragment showing synonym expansion
{
  "tokens": [
    { "token": "turnschuh", "start_offset": 0, "end_offset": 10, "type": "SYNONYM", "position": 0 },
    { "token": "sneaker", "start_offset": 0, "end_offset": 10, "type": "SYNONYM", "position": 0 },
    { "token": "sportschuh", "start_offset": 0, "end_offset": 10, "type": "SYNONYM", "position": 0 }
  ]
}

8. Typische Fallstricke bei der Pflege

Der erste haeufige Fehler ist die Reihenfolge von Stemming und Synonym-Filter in der Analyzer-Kette. Wird zuerst gestemmt und dann synonymisiert, treffen Synonyme auf Wortstaemme statt auf die volle Form, was zu unerwarteten Nicht-Treffern fuehrt. Magentos Standardkonfiguration platziert den Synonym-Filter korrekt vor dem Stemmer, aber individuelle Anpassungen an der Analyzer-Pipeline koennen diese Reihenfolge versehentlich vertauschen und Such-Synonyme unbrauchbar machen, ohne dass ein Fehler sichtbar wird.

Der zweite Fallstrick ist Ueberdimensionierung: Teams neigen dazu, immer mehr Begriffe in eine einzige riesige Synonymgruppe zu packen, bis Woerter mit voellig unterschiedlicher Bedeutung in derselben Kette landen. Ein Klassiker: "bank" als Sitzmoebel und "bank" als Finanzinstitut werden faelschlich synonymisiert, weil beide in einer generischen "Moebel"-Liste auftauchten. Der dritte Fallstrick betrifft Gross- und Kleinschreibung sowie Umlaute: Ohne konsistente Normalisierung vor dem Synonym-Filter fuehren "Kuehlschrank" und "kuehlschrank" zu unterschiedlichem Verhalten, was bei manueller Pflege leicht uebersehen wird.

9. Governance-Prozess fuer Fachabteilungen

Damit Such-Synonyme nicht ausschliesslich in der Verantwortung der Entwicklung liegen, lohnt sich ein leichtgewichtiger Governance-Prozess. Marketing oder Content-Teams kennen die Kundensprache oft besser als Entwickler und sollten Synonyme direkt im Admin pflegen koennen, ohne bei jeder Aenderung ein Ticket zu erstellen. Voraussetzung dafuer ist ein dokumentierter Workflow: Neue Synonymgruppe im Staging-System anlegen, mit der Analyze API verifizieren, anschliessend per Datenbankexport oder Deployment-Skript in die Produktion uebernehmen.

Fuer grosse Synonymlisten empfiehlt sich ein CSV-basierter Import statt manueller Einzelpflege im Grid. Ein einfaches Skript liest eine CSV-Datei mit Synonymgruppen ein und schreibt sie direkt in die Tabelle search_synonyms, gefolgt von einem automatischen Reindex. Das reduziert Fehlerquellen bei grossen Mengen an Such-Synonymen erheblich und macht Aenderungen versionierbar, wenn die CSV-Datei selbst unter Versionskontrolle steht.

# CSV-based bulk import for search synonyms (custom maintenance script)
# synonyms.csv format: store_id;term1,term2,term3

while IFS=';' read -r store_id synonyms; do
  bin/mysql magento -e "
    INSERT INTO search_synonyms (store_id, synonyms)
    VALUES ($store_id, '$synonyms')
    ON DUPLICATE KEY UPDATE synonyms = '$synonyms';
  "
done < synonyms.csv

# Trigger reindex once, after all rows are imported
bin/magento indexer:reindex catalogsearch_fulltext

10. Zusammenfassung

Such-Synonyme in Magento sind kein reines Frontend-Feature, sondern eine Eigenschaft der Elasticsearch-Analyzer-Konfiguration, die pro Store View und pro Index gilt. Die Admin-Oberflaeche unter Marketing > SEO & Suche > Suchsynonyme speichert Synonymgruppen store-view-spezifisch in der Tabelle search_synonyme, und erst ein vollstaendiger Reindex des catalogsearch_fulltext-Indexers uebersetzt diese Gruppen in einen aktiven synonym_graph-Filter im Index.

Wer Such-Synonyme zuverlaessig pflegen will, braucht drei Dinge: eine klare Zuordnung von Synonymgruppen zu Store Views, einen expliziten Reindex-Trigger nach jeder Aenderung statt Verlass auf den naechsten Cron-Zyklus, und ein Testverfahren ueber die Elasticsearch _analyze-API, das unabhaengig vom Frontend verifiziert, ob eine Synonymgruppe tatsaechlich im Index angekommen ist. Mit diesen drei Bausteinen wird aus einem oft missverstandenen Feature ein verlaesslicher Hebel fuer bessere Trefferquoten.

11. FAQ: Such-Synonyme in Magento