Magento 2 Search Synonyms and Relevance Tuning Guide

Site search visitors usually know what they want, which makes search results one of the most valuable pages in a store. Magento's default search is reasonable, but it does not know the store's vocabulary: the brand names customers misspell, the regional words for the same product, the codes buyers use. This article covers the tools Magento Open Source and Adobe Commerce 2.4.8 give you to improve relevance, and how to test changes instead of guessing.

Start from real search data

Before changing anything, look at what people search for. Marketing, SEO & Search, Search Terms lists every query with its number of uses and number of results. Two reports are worth checking every month:

• Queries with zero results. These are the clearest gaps: misspellings, words the catalog does not use, products you do not sell.
• Frequent queries. Search for the top fifty yourself and judge the first row of results. If the first products are not the ones you would expect, that query needs work.

If you track search in GA4, the site search report adds which searches led to purchases. The setup is in GA4 and GTM ecommerce tracking.

Synonym groups

Synonyms are managed under Marketing, SEO & Search, Search Synonyms. Each group is a comma separated list of words and phrases that Magento treats as equal when searching. A search for any word in the group also searches for the others.

sofa,couch,settee
tshirt,t-shirt,tee
phone case,phone cover,mobile case

Some things to know about how groups behave:

• Groups are two way. Every term expands to all the others. There is no core setting for one way synonyms, where a search for one word should include another but not the reverse. If you need that, keep the group small and think about what the reverse search will return.
• Scope. A group can apply to all store views, one website or one store view. Synonyms are language specific, so for multilingual stores create them per store view.
• Merging. When you save a group that shares a term with an existing group, Magento asks whether to merge them. Merging chains of loosely related words into one huge group makes results worse, because every word in the chain now matches everything else.
• No reindex needed. Synonyms are applied when the query is built, not when products are indexed. Changes are effective after the cache for search pages is cleared.

Groups are stored in the search_synonyms table with the scope columns, which makes them easy to export, review and deploy between environments with a data patch.

Synonyms are not a spelling fixer

It is tempting to add every misspelling as a synonym. For a handful of very common misspellings of a brand name, that is fine. For general typos, the search engine's fuzzy matching handles a lot already, and hundreds of typo groups become hard to maintain. Look at the zero results report and fix the top ten instead of trying to cover everything.

Search terms: redirects and suggestions

In Search Terms you can edit a query and set a Redirect URL. Customers who search for exactly that query are sent to the URL instead of the results page. This is useful for queries that are really navigation, such as a brand name that has its own landing page, or "returns" pointing to the returns policy.

The same screen has Display in Suggested Terms, which controls whether the query is offered as a suggestion. Remove queries with typos or no results from suggestions, so the autocomplete does not suggest searches that fail.

Attribute search weight

Each product attribute has Use in Search and Search Weight under Storefront Properties. Search Weight is a value from 1 to 10 that boosts matches on that attribute. By default, name and SKU are already weighted higher than description, which is why a word in a product name usually beats the same word in a long description.

Practical rules I follow:

• Only attributes that customers actually type should be searchable. Internal codes, colors already covered by the name, and technical fields add noise and make the index bigger. See product attribute best practices.
• Give brand and product line attributes a high weight if customers search by brand.
• Keep description weight low. Long descriptions mention many words, and a high weight brings in products that only mention the term in passing.
• Change one weight at a time and test the same set of queries before and after.

Changing Use in Search or Search Weight requires a reindex of catalogsearch_fulltext, since it changes what goes into each product document and how fields are boosted.

Stopwords

Stopwords are words removed from queries and from indexed text, such as "the" or "and". Magento ships stopword lists per locale as CSV files in the Magento_Elasticsearch module, mapped to locales in its configuration. The OpenSearch adapter reuses the same setup.

To change them, add your own file and mapping in a custom module instead of editing the core files. Then run a full reindex, because stopwords are part of the index analysis settings. Be careful with removing words that carry meaning in your catalog. A store whose brands or product names are made of common short words needs to check how those searches behave with the default list.

Minimal query length and other settings

Under Stores, Configuration, Catalog, Catalog, Catalog Search, Minimal Query Length avoids one and two letter searches, which match most of the catalog. Maximum Query Length protects against very long pasted text. Autocomplete Limit sets how many suggestions appear. Enable Search Suggestions shows "did you mean" suggestions when a search returns few results.

Test relevance against OpenSearch

When results look wrong, look at how the text is analyzed. The _analyze API shows the tokens OpenSearch produces for a field, which explains many surprises such as words split on hyphens or stemmed differently than expected:

curl -s -X POST 'http://opensearch:9200/magento2_product_1/_analyze?pretty' \
  -H 'Content-Type: application/json' \
  -d '{"field": "name", "text": "T-Shirts for runners"}'

Use the store ID of the store view you are testing, and your own index prefix. If the tokens in the query and the tokens in the product name do not overlap, no weight or synonym will make the product match. Setup of the cluster itself is covered in OpenSearch setup and tuning.

Keep a small list of important queries with the products you expect at the top. After every change to synonyms, weights or stopwords, run through the list on staging. It takes ten minutes and prevents fixing one query by breaking three others.

When the core is not enough

The core tools are enough for most small and medium catalogs. Stores with large catalogs, many languages or heavy merchandising needs often move to a dedicated search service. Adobe Commerce has Live Search, a SaaS search service with AI based ranking and merchandising rules, available only for Adobe Commerce. On either edition there are third party search services with their own Magento modules. These replace the search results page, so evaluate them on your own queries before switching.

FAQ

Do I need to reindex after adding search synonyms in Magento 2?

No. Synonyms are applied when the query is built. Clear the cache for search result pages and test. Changes to search weight, searchable attributes or stopwords do need a reindex.

Can Magento synonyms be one way?

Not with the core feature. Every term in a group matches all the others. For one way behavior you need custom query logic or a third party search service.

Why does a product not appear when searching its SKU?

Check that SKU is searchable, the product is visible in search and assigned to the website, and the index is current. Then use the _analyze API to see how the SKU and the query are tokenized.

What does Search Weight do on an attribute?

It boosts matches on that attribute relative to others, on a scale from 1 to 10. A higher weight on name or brand ranks products matching there above products matching only in the description.

I am available for freelance Magento and Adobe Commerce work, including search relevance and catalog tuning. If you need help with this, get in touch.