Merchandising and search relevance tuning in OpenSearch

Part 6 of the Catalog at Scale series — search is the storefront for catalogs too large to browse.

Nobody browses a 200,000-SKU catalog

Past a certain size, category navigation stops being the primary discovery path. Customers search, and the search box becomes the merchandiser. Relevance tuning is therefore not a cosmetic task: the ranking function decides which products get seen, and small scoring changes move revenue between categories. Magento delegates the heavy work to OpenSearch, but the defaults rank text similarity, not commercial intent. Closing that gap is the job.

How OpenSearch relevance actually scores

When Magento indexes products, searchable attributes (name, SKU, description, and configured attributes) are written into the OpenSearch index with per-field weights. A query is analyzed into tokens, matched against those fields, and each hit receives a score combining term frequency, inverse document frequency, and field boosts. The product name match outranks a description match because its boost is higher, and rare terms outrank common ones.

Two consequences follow. First, anything the analyzer drops or splits changes what can match: a SKU with dashes, a brand name with an apostrophe, or a compound word in another language may never produce the token the customer typed. Second, the score knows nothing about margin, stock, newness, or campaign priority. A perfect text match on an out-of-stock product beats a good match on the product the business wants to sell. Relevance tuning means fixing both layers.

Analyzers and synonyms first

Before touching boosts, make the matching correct:

• Language analyzers. Confirm the index uses the right analyzer for the store view language. A generic analyzer that stems English aggressively will mangle German compounds or Vietnamese diacritics. Test with the actual query log, not sample English queries.
• SKU and part-number handling. Customers paste exact codes. Keep a raw, unanalyzed sub-field for SKU and model numbers so an exact match scores decisively, instead of relying on tokenized fragments.
• Synonym sets. Build them from the search query log: the terms customers type that return nothing, and the terms that return results they do not click. Map colloquial names to catalog names (sofa to couch in furniture, local spellings, common misspellings) and keep the list versioned so additions are reviewable.
• Stop words and short tokens. Two-letter queries (sizes, model prefixes) are often dropped by default token filters. Decide explicitly which short tokens matter for the catalog and protect them.

Field weights and attribute strategy

Not every searchable attribute deserves equal influence. A practical starting order: name highest, then SKU and brand, then short description and configured merchandising attributes (color, material, category names), with long description lowest. Marking every attribute searchable flattens the scoring curve until everything matches weakly; restrict searchability to attributes customers actually query, using the query log as the removal list.

For dropdown and multiselect attributes, index the option labels, not the internal IDs, and keep labels consistent. Ten spelling variants of one color split the term statistics and dilute every match.

Merchandising rules on top of scoring

Once text relevance is sane, layer commercial rules through Magento search merchandising and query rules:

• Pin and boost campaigns. Seasonal pushes, new arrivals, and high-margin lines get explicit boosts or pinned positions for their target queries. Keep each rule scoped to named queries with an expiry date, and review expired rules instead of letting them accumulate.
• Demote, do not delete. Out-of-stock, end-of-life, and low-rated products should sink rather than vanish, so the result set still looks complete while sellable stock leads. Tie the demotion to the stock and visibility indexers so it lifts automatically on restock.
• Category-scoped rules. A boost that makes sense in one category (lightweight for luggage) is noise everywhere else. Scope rules to the categories they were written for.
• Null-result defense. For queries that still return nothing, define fallback behavior: relaxed matching, a curated suggestion list, or a redirect to the closest category. Log every null-result query; it is the cheapest source of synonym and assortment insight available.

Measuring relevance instead of guessing

Relevance work without metrics drifts into opinion. Track click-through rate per query, add-to-cart rate from search result pages, and the share of null-result queries week over week. When a tuning change ships, compare the same query set before and after rather than judging by a handful of manual searches. Keep a fixed evaluation set of the top hundred queries plus known edge cases, and re-run it after every synonym or weight change. A change that improves three showcase queries while degrading the head terms is a regression, not a tuning win.

Pitfalls

• Tuning boosts before fixing analyzers. No weight adjustment recovers tokens the analyzer destroyed.
• Permanent campaign rules. A boost without an expiry becomes invisible debt that fights next season's campaign.
• Synonym sprawl. Unreviewed synonym additions eventually connect unrelated terms and flatten ranking into mush.
• Ignoring the long tail. Head queries get attention; the thousands of rare queries collectively carry the conversion. Sample them.

Next in this series: magento2-bulk-import-async-api