Search Synonyms and Spell Correction in Magento

1. Why synonyms and typo tolerance raise the success rate

Search synonyms solve a fundamental linguistic problem: customers often use different terms for the same product than the catalog description does. A search for "laptop" should also return hits when the catalog consistently writes "notebook". Without search synonyms and spell correction, a significant share of these queries lands on a zero result page even though the searched product exists in the assortment.

The second major source of errors is typos, especially on mobile devices with small keyboards. Without spell correction, a single swapped letter already produces a zero result. Both problems, missing synonyms and missing typo tolerance, need to be solved differently on a technical level, but they contribute to the same symptom: customers leave the page because the search appears to find nothing, even though the product exists.

The economic effect of good search synonyms is often underestimated. Analyzing zero result searches in most catalogs shows that a double digit percentage of all zero result queries could be fixed with a handful of targeted synonyms. This is one of those cases where little effort has a disproportionately large effect on the conversion rate of internal search.

2. Maintaining Search Synonym Groups in the admin correctly

Magento ships with Search Synonym Groups (Store > Search Synonyms in the backend), a built in tool for maintaining synonym groups that works without any additional development. A synonym group bundles several terms that should be treated as equivalent during search, for example laptop, notebook, ultrabook. Maintenance is scope dependent, so potentially different per website or store view, which matters for multilingual shops.

A common mistake when maintaining search synonyms is putting too many, too generic terms into a single group. A group like shoe, boot, sneaker, sandal treats technically different product categories as interchangeable, which dilutes search results instead of improving them. Clean synonym management means grouping only genuine naming variants for the same concept, not related but distinct product types.

3. Synonyms technically: OpenSearch token filter vs. Magento sync

Technically there are two layers for search synonyms in Magento: Magento's own synonym management, which writes a synonym token filter into the OpenSearch analyzer configuration on every reindex, and directly editing that token filter at the index level. The Magento route is the preferred one for all standard cases, because it enables scope dependent maintenance in the admin without needing a developer involved.

{
  "settings": {
    "analysis": {
      "filter": {
        "synonym_filter": {
          "type": "synonym",
          "synonyms": [
            "laptop, notebook, ultrabook",
            "headfones => headphones",
            "cellphone, smartphone, mobile phone"
          ]
        }
      },
      "analyzer": {
        "search_synonym_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "synonym_filter"]
        }
      }
    }
  }
}

Important for search synonyms at the OpenSearch level: the synonym filter should only be applied at search time (search_analyzer), not at indexing time, unless it is deliberately intended for every synonym to permanently exist in the index. Applying the filter on both sides needlessly multiplies the number of stored tokens and the index grows without added benefit.

4. Distinguishing ambiguous and one-directional synonyms

An often overlooked distinction with search synonyms is the direction of mapping. Comma notation (a, b, c) creates equivalent, bidirectional synonyms: a search for a also finds b and c, and vice versa. Arrow notation (a => b) creates a one directional replacement: a search for a gets replaced by b, but not the other way around.

This distinction is decisive for ambiguous terms. An example: mouse can refer both to the animal and to computer accessories. A bidirectional synonym group with mouse, computer mouse would surface computer mouse hits for every search for mouse, which is usually desired in an electronics shop. A one directional replacement would be the wrong choice here, since it obscures the original search intent instead of expanding it. For genuine typos or outdated spellings, for example headfones => headphones, one directional replacement is the correct form instead, because the canonical spelling is clearly established.

5. Spell correction: did-you-mean with fuzzy query

While search synonyms cover known term variants, unknown typos need a different technique: fuzzy matching and suggesters. OpenSearch offers the fuzziness option in the multi_match query as well as a dedicated phrase suggester that generates correction suggestions based on terms present in the index. For a classic "Did you mean...?" feature, both get combined: fuzzy matching directly returns results despite typos, the suggester supplies the correction suggestion to display.

{
  "suggest": {
    "did_you_mean": {
      "text": "notebok",
      "phrase": {
        "field": "name.trigram",
        "size": 1,
        "gram_size": 3,
        "direct_generator": [
          {
            "field": "name.trigram",
            "suggest_mode": "always",
            "min_word_length": 4
          }
        ],
        "highlight": {
          "pre_tag": "<em>",
          "post_tag": "</em>"
        }
      }
    }
  }
}

The phrase suggester needs its own trigram field (name.trigram in the example), built with a shingle filter, in order to meaningfully score multi word correction suggestions too. For spell correction in Magento, this setup is an extension that goes beyond the default search functionality, but it makes a noticeable difference in hit rate especially for mobile users.

6. Connecting custom synonym sources (CSV import)

For catalogs with many languages or frequently changing search synonyms, manual maintenance in the admin is time consuming. A common extension is a CLI command or cron job that imports synonym groups from a centrally maintained CSV file and creates or updates them via the Magento API (Magento\Search\Api\SynonymGroupRepositoryInterface). This lets subject matter teams without Magento backend access maintain synonyms in a plain spreadsheet.

<?php

declare(strict_types=1);

namespace Mironsoft\SearchSynonyms\Console\Command;

use Magento\Search\Api\Data\SynonymGroupInterfaceFactory;
use Magento\Search\Api\SynonymGroupRepositoryInterface;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

/**
 * Imports search synonym groups from a CSV file maintained outside of the admin panel.
 */
final class ImportSynonymsCommand extends Command
{
    /**
     * @param SynonymGroupRepositoryInterface $synonymGroupRepository Repository for saving synonym groups
     * @param SynonymGroupInterfaceFactory $synonymGroupFactory Factory for new synonym group instances
     */
    public function __construct(
        private readonly SynonymGroupRepositoryInterface $synonymGroupRepository,
        private readonly SynonymGroupInterfaceFactory $synonymGroupFactory,
    ) {
        parent::__construct('mironsoft:synonyms:import');
    }

    /**
     * Configures the console command signature.
     *
     * @return void
     */
    protected function configure(): void
    {
        $this->setDescription('Imports synonym groups from a CSV file');
        $this->addArgument('file', InputArgument::REQUIRED, 'Path to the synonyms CSV file');
    }

    /**
     * Reads the CSV file and persists each row as a synonym group.
     *
     * @param InputInterface $input Console input containing the file argument
     * @param OutputInterface $output Console output for progress messages
     * @return int
     */
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $handle = fopen((string) $input->getArgument('file'), 'r');

        while (($row = fgetcsv($handle)) !== false) {
            $group = $this->synonymGroupFactory->create();
            $group->setSynonymGroup(implode(',', $row));
            $group->setStoreId(0);
            $this->synonymGroupRepository->save($group);
        }

        fclose($handle);
        $output->writeln('Synonym import completed');

        return Command::SUCCESS;
    }
}

7. Language specific challenges: compounds and umlauts

In German, search synonyms bring an additional difficulty: compound words. A customer might search for "Laufschuh" (running shoe, singular), while the catalog writes "Laufschuhe" (plural) or "Running Schuh". A plain word level synonym approach does not automatically capture every compound variant, which is why an additional decompound filter, splitting compound words into their parts, makes sense in many German language shops.

Umlauts are a second, often underestimated source of errors: customers on English keyboard layouts frequently type kopfhoerer instead of kopfhörer (headphones). An asciifolding filter or targeted one directional search synonyms reliably solve this problem, provided both spellings are consistently maintained in the synonym list. Without this treatment, umlaut related zero result searches remain one of the most common yet easiest to fix sources of error in German language e-commerce.

8. Analyzing zero result searches and adding synonyms based on data

The most effective method to continuously improve search synonyms and spell correction is a regular review of zero result searches, meaning every search query that returned zero results. Magento stores these queries in the search_query table along with the result count, which enables a simple SQL query for a weekly review.

-- Top no-result search terms from the last 30 days, ranked by frequency
SELECT
    query_text,
    num_results,
    popularity
FROM search_query
WHERE num_results = 0
  AND updated_at >= DATE_SUB(NOW(), INTERVAL 30 DAY)
ORDER BY popularity DESC
LIMIT 50;

This list is the foundation for data driven synonym management: every frequently occurring zero result term is manually reviewed to determine whether it is a typo, a missing naming variant, or a genuinely absent product. Only the first two cases require adjusting search synonyms, the third case is an assortment or SEO topic, not a search configuration issue.

9. Approaches compared

The following table compares techniques for reducing zero result searches through search synonyms and spell correction.

No single approach solves every zero result case. Only the combination of maintained search synonyms, automatic fuzzy matching and regular zero result analysis durably reduces the error rate.

10. Summary

Good search synonyms and reliable spell correction solve two different but related problems: different terms for the same concept, and unintentional typos. Magento's Search Synonym Groups cover the first case in the admin, fuzzy matching and phrase suggesters cover the second at the OpenSearch level. Both techniques need deliberate maintenance, bidirectional and one directional synonyms are not interchangeable concepts.

The most sustainable way to improve search synonyms is regularly reviewing zero result searches instead of a one time, exhaustive synonym list. Reviewing the most frequent zero result terms monthly and adding targeted synonyms or correction rules continuously lowers the search error rate, at comparatively low maintenance effort relative to the effect on conversion rate.

11. FAQ: Search Synonyms and Spell Correction in Magento