Managing Search Synonyms in Magento Cleanly

1. Why search synonyms directly affect revenue

Customers do not search using the product names stored in the catalog. Someone typing "sneakers" will find nothing without search synonyms if the PIM stores the same products as "trainers". Someone searching for "fridge freezer" comes up empty if the manufacturer consistently uses "refrigeration unit" in the title. Every failed search is a customer who leaves the site without buying. Conversion analyses regularly show that sessions with a zero-result search convert at a significantly lower rate than sessions without any search at all.

Magento ships a built-in feature for this that is often underestimated: synonym groups in the admin that can be maintained per store view. The mechanism itself is not complicated, but it has sharp edges where teams regularly stumble, because they assume a saved synonym group takes effect immediately and globally. In reality, search synonyms in Magento are tightly coupled to the store view and to the reindex cycle of the catalogsearch_fulltext indexer. Anyone unaware of this connection wastes time debugging when the real problem is simply a missing reindex run.

This article walks through the full lifecycle of search synonyms: from entry in the admin, through internal data storage, to translation into an Elasticsearch synonym filter, including test procedures and a process that lets even non-developers maintain synonyms safely.

2. Creating synonym groups in the Magento admin

Synonym groups live in the backend under Marketing > SEO & Search > Search Synonyms. A synonym group is a comma-separated list of terms that Magento should treat as mutually interchangeable. Every group is assigned a scope: either "All Store Views" or a specific store view. This scope binding matters a great deal, because search synonyms for the German store view should not automatically apply to the English store view, where "sneakers" is already the common term and needs no translation.

When saving, Magento checks server-side whether a term already appears in another group for the same store view and refuses to save on conflict. This prevents contradictory synonym chains where a word appears in two different groups with different meanings. For production use it is worth clustering synonym groups thematically, for example one group per product category, instead of maintaining a single giant list that nobody can oversee anymore.

Internally, every synonym group ends up in the search_synonyms table with the columns synonym_group_id, store_id and synonyms, where store_id = 0 represents the "All Store Views" scope. This simple structure makes it easy to inspect synonyms outside the admin UI as well, for example for audits or automated consistency checks before a release.

3. How Magento maps search synonyms to Elasticsearch

The actual mechanism behind search synonyms happens not at search time, but at index time. When the catalogsearch_fulltext indexer runs, Magento reads the active synonym groups for the relevant store from the search_synonyms table and dynamically builds an Elasticsearch synonym token filter from them, which becomes part of the index's analyzer chain. This means search synonyms are not a runtime feature of the search query, but a property of the index itself, and every store gets its own dedicated Elasticsearch index with its own analyzer settings.

This architectural decision has an important side effect: changing a synonym group only takes effect once the index for that store has been rebuilt. The analyzer is fixed when the index is created and cannot be changed afterward on an open index without closing and reopening it. Magento encapsulates this process during a full reindex, so developers normally do not have to handle it manually, but it explains why a plain partial reindex after a product change does not activate new search synonyms.

{
  "settings": {
    "analysis": {
      "filter": {
        "synonym_filter_store_1": {
          "type": "synonym_graph",
          "synonyms": [
            "sneakers, trainers, sports shoes",
            "fridge freezer, refrigeration unit",
            "notebook, laptop"
          ]
        }
      },
      "analyzer": {
        "catalog_search_analyzer_store_1": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "synonym_filter_store_1",
            "english_stemmer"
          ]
        }
      }
    }
  }
}

4. Unidirectional vs. bidirectional: choosing the right syntax

Elasticsearch distinguishes two forms of synonyms, and Magento's synonym groups only map directly to the bidirectional form. A comma-separated list like sneakers, trainers, sports shoes means every term can be replaced by any other term, in both directions. If a customer searches for "sneakers", they will also find products that only carry "trainers" in the title, and vice versa. That is correct for genuine synonym pairs, but it produces unwanted matches for terms that are not truly equivalent.

For unidirectional mappings, for example mapping brand names to category terms ("iphone" should return "smartphone" results, but not every smartphone search should favor iPhones), you need the => syntax of the Elasticsearch synonym filter. Magento's standard UI does not support this directly, so such cases are handled through a plugin on the SynonymReader or a custom indexer patch that extends the synonym list with => rules before it is handed to Elasticsearch. Without that extension, asymmetric term pairs are stuck with the symmetry of the bidirectional form.

5. Store view scope: the most common search synonym mistake

By far the most common support case around search synonyms is a group created in the wrong scope. An editor creates a synonym group on the default store view, tests it successfully there, but the actual production store runs on a different store view with its own store code. Because every store view in multi-site setups gets its own Elasticsearch index with its own analyzer, the synonym group has no effect on the production store, even though it looks visible and "active" in the admin.

International shops with multiple languages face a second pitfall: synonyms are language-dependent, and a group scoped to "All Store Views" is applied identically to every store view, including languages where the terms make no sense or are outright wrong. The recommendation is therefore to create search synonyms globally only in exceptional cases and to maintain them per store view or per language group as the default, even though that means more maintenance effort because terms often duplicate across store views that share the same language.

# 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 behavior: when synonyms really become active

Because the synonym filter is part of the analyzer definition, the catalogsearch_fulltext indexer has to fully rebuild the affected Elasticsearch index for new search synonyms to take effect. In "Update on Save" mode this rebuild runs synchronously when the synonym group is saved, which noticeably blocks the admin request on large catalogs. In "Update by Schedule" mode (mview), Magento instead marks the indexer as invalid, and the cron job indexer_reindex_all_invalid takes over the rebuild in the background, which keeps the UI fast but introduces a visible delay before the synonyms actually take effect.

For teams that adjust synonyms frequently, an explicit manual trigger right after saving is worthwhile instead of waiting for the next cron cycle. That way, staging environments can immediately verify whether a new synonym group behaves as expected before it goes live.

# 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. Testing search synonyms with the Analyze API

Instead of blindly trying search terms in the storefront, the analyzer of a store index can be tested directly against Elasticsearch. The _analyze API takes a piece of text and the name of the analyzer and returns which tokens the text is broken into, including all alternative tokens added by the search synonym filter. This is the most reliable way to verify whether a synonym group has actually made it into the index, without the detour through the storefront and possible additional filters like visibility or stock status.

This method is also excellent for automated tests: a simple script can check after every deployment whether the expected synonym tokens appear in the analyzer output, and raise an alert if a change to the index configuration accidentally removed synonyms.

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

// Expected response fragment showing synonym expansion
{
  "tokens": [
    { "token": "sneaker", "start_offset": 0, "end_offset": 8, "type": "SYNONYM", "position": 0 },
    { "token": "trainer", "start_offset": 0, "end_offset": 8, "type": "SYNONYM", "position": 0 },
    { "token": "sports shoe", "start_offset": 0, "end_offset": 8, "type": "SYNONYM", "position": 0 }
  ]
}

8. Common pitfalls in day-to-day maintenance

The first common mistake is the order of stemming and the synonym filter in the analyzer chain. If stemming happens before synonym expansion, synonyms match word stems instead of full forms, which leads to unexpected non-matches. Magento's default configuration places the synonym filter correctly before the stemmer, but custom changes to the analyzer pipeline can accidentally swap this order and render search synonyms useless without any visible error.

The second pitfall is over-grouping: teams tend to keep piling more terms into a single giant synonym group, until words with completely different meanings end up in the same chain. A classic case: "bank" as a piece of furniture and "bank" as a financial institution end up incorrectly synonymized because both appeared in a generic "furniture" list. The third pitfall involves case sensitivity and accented characters: without consistent normalization before the synonym filter, "Fridge" and "fridge" can behave differently, which is easy to miss during manual maintenance.

9. A governance process for non-technical teams

So that search synonyms do not remain exclusively the responsibility of the development team, a lightweight governance process pays off. Marketing or content teams often know customer language better than developers and should be able to maintain synonyms directly in the admin, without filing a ticket for every change. That requires a documented workflow: create the new synonym group in staging, verify it with the Analyze API, then roll it into production via database export or deployment script.

For large synonym lists, a CSV-based import is preferable to manual editing in the grid. A simple script reads a CSV file containing synonym groups and writes them directly into the search_synonyms table, followed by an automatic reindex. This significantly reduces error sources for large volumes of search synonyms and makes changes version-controllable if the CSV file itself lives under version control.

# 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. Summary

Search synonyms in Magento are not a pure frontend feature, but a property of the Elasticsearch analyzer configuration, scoped per store view and per index. The admin interface under Marketing > SEO & Search > Search Synonyms stores synonym groups per store view in the search_synonyms table, and only a full reindex of the catalogsearch_fulltext indexer translates these groups into an active synonym_graph filter inside the index.

Anyone who wants to maintain search synonyms reliably needs three things: a clear mapping of synonym groups to store views, an explicit reindex trigger after every change instead of relying on the next cron cycle, and a test procedure via the Elasticsearch _analyze API that verifies independently of the storefront whether a synonym group has actually made it into the index. With these three building blocks, an often misunderstood feature becomes a reliable lever for better hit rates.

11. FAQ: Search Synonyms in Magento