Table of contents :

Multi-Word Synonyms in Elasticsearch

100-days-of-elasticsearch-woocommerce-038

Table of contents :

WooCommerce shoppers rarely use the exact vocabulary stored in a product catalog. A customer may search for tee shirt when the product title contains t-shirt, or search for trainers when the catalog uses running shoes. Single-word synonym filters can handle simple substitutions, but multi-word alternatives require Elasticsearch’s token graph support.

For product search, the preferred approach is to apply a synonym_graph filter in the search analyzer. This preserves the relationships between multiple tokens and allows Elasticsearch to build correct phrase queries and relevance calculations.

Why Multi-Word Synonyms Need a Token Graph

A multi-word synonym changes the number and position of tokens in a query. For example, the query tee shirt contains two tokens, while the catalog term t-shirt may be represented as one token. A conventional synonym filter can flatten this relationship and produce inaccurate phrase behavior.

The synonym_graph filter represents alternatives as a graph. Elasticsearch can then understand that the two-token phrase tee shirt is an alternative to the one-token term t-shirt, rather than treating the words as unrelated independent substitutions.

This matters when a WooCommerce search uses phrase matching, proximity, highlighting, or a match query that automatically creates phrase alternatives for multi-word synonyms.

Defining Multi-Word Synonyms

Elasticsearch supports equivalent synonym rules and directional synonym rules. An equivalent rule treats every listed expression as interchangeable:

t-shirt, tee shirt, tshirt

A directional rule maps one expression to another:

trainers => running shoes

Equivalent rules are useful when customer vocabulary and catalog vocabulary should work in both directions. Directional rules are safer when one term is a broad marketing phrase, an internal category label, or a preferred canonical term.

For example, a WooCommerce store selling footwear might use:

trainers, sneakers<br>running shoes => running footwear

Use directional mappings carefully. Mapping shoes to trainers could make unrelated products match and reduce search precision.

Creating the Analyzer

The following index configuration defines a standard product analyzer and a search analyzer containing multi-word synonyms:

{<br>  "settings": {<br>    "analysis": {<br>      "filter": {<br>        "woocommerce_synonyms": {<br>          "type": "synonym_graph",<br>          "synonyms": [<br>            "t-shirt, tee shirt, tshirt",<br>            "trainers, sneakers",<br>            "hoodie, hooded sweatshirt",<br>            "usb c, usb-c, type c"<br>          ]<br>        }<br>      },<br>      "analyzer": {<br>        "woocommerce_index": {<br>          "type": "custom",<br>          "tokenizer": "standard",<br>          "filter": [ "lowercase", "asciifolding" ]<br>        },<br>        "woocommerce_search": {<br>          "type": "custom",<br>          "tokenizer": "standard",<br>          "filter": [<br>            "lowercase",<br>            "asciifolding",<br>            "woocommerce_synonyms"<br>          ]<br>        }<br>      }<br>    }<br>  },<br>  "mappings": {<br>    "properties": {<br>      "name": {<br>        "type": "text",<br>        "analyzer": "woocommerce_index",<br>        "search_analyzer": "woocommerce_search"<br>      },<br>      "description": {<br>        "type": "text",<br>        "analyzer": "woocommerce_index",<br>        "search_analyzer": "woocommerce_search"<br>      }<br>    }<br>  }<br>}

The catalog text is indexed without synonyms, while the customer’s query is expanded at search time. This avoids storing multiple synonym variants in the inverted index and makes synonym changes less disruptive.

Why Search-Time Expansion Is Usually Better

Applying synonyms during indexing can increase index size and makes changes expensive. Existing documents must generally be reindexed when the index-time analysis rules change. It can also create unexpected behavior when the same field is queried for exact values, sorting, or aggregations.

Search-time expansion keeps the original product content intact. A product named Men’s T-Shirt remains indexed according to the catalog text, but a search for tee shirt can still find it. This is particularly useful for WooCommerce stores where product data is synchronized from WordPress, an ERP, or a product information management system.

Do not use synonym_graph as an index-time filter unless you have a specific reason and understand the resulting token graph. If a graph must be flattened for indexing, Elasticsearch provides the flatten_graph filter, but search-time application is normally the more accurate design for multi-word alternatives.

Querying a Synonym-Aware Field

A standard match query can use the field’s configured search_analyzer:

{<br>  "query": {<br>    "multi_match": {<br>      "query": "waterproof trainers",<br>      "fields": [ "name^4", "description" ],<br>      "operator": "and"<br>    }<br>  }<br>}

With the synonym rule trainers, sneakers, the query can match products containing either term. With a rule such as hoodie, hooded sweatshirt, Elasticsearch preserves the multi-token alternative so phrase-oriented matching remains meaningful.

When using a match_phrase query, verify the behavior with the _analyze API and representative product names. Multi-word synonyms can produce more than one valid path through the token graph, and the selected slop, boosts, and minimum-should-match settings affect the final result.

Testing Token Graphs

Before deploying a synonym list, inspect how Elasticsearch analyzes both the product text and the customer query:

POST products/_analyze<br>{<br>  "analyzer": "woocommerce_search",<br>  "text": "blue tee shirt",<br>  "explain": true<br>}

Check that:

  • The expected terms are lowercased consistently.
  • Both sides of an equivalent rule are available when bidirectional matching is intended.
  • A multi-word alternative retains appropriate token positions.
  • Hyphenated terms such as usb-c are analyzed as expected by the tokenizer.
  • Stemming, stop-word removal, and accent folding do not conflict with the synonym rules.

The order of analysis filters matters. Filters that run before the synonym filter affect how synonym rules are parsed and matched. Keep the synonym vocabulary compatible with the preceding tokenizer and filters, and test terms containing punctuation, accents, and hyphens.

Managing Synonyms in Production

For a small, stable vocabulary, inline synonyms are straightforward. For a larger WooCommerce catalog or a team-managed search configuration, use Elasticsearch’s synonym set features where supported by the deployed Elasticsearch version. A synonym set can be updated centrally, while analyzers can be configured with a synonym set reference and an updateable search analyzer.

Synonym changes still require operational planning. Validate the new rules, reload or apply the analyzer configuration according to the Elasticsearch version, and monitor query behavior after deployment. If the analyzer is part of an index template, ensure that newly created indices receive the same configuration during rollover.

Keep synonym rules in version control alongside the WooCommerce search integration. Record the reason for each rule, its direction, affected product categories, and example queries. This prevents marketing requests from introducing broad mappings that create irrelevant results.

WooCommerce-Specific Design Practices

  • Apply synonyms to searchable text fields such as product names, short descriptions, and long descriptions, but keep SKU and barcode fields exact unless there is a clear business requirement.
  • Use field boosts so a synonym match in the product name can outrank a weaker match in the description.
  • Separate merchandising rules from linguistic synonyms. A synonym expresses equivalent language; a pinned product or category boost expresses a commercial ranking decision.
  • Measure zero-result searches and low-click searches to discover useful multi-word alternatives from real customer behavior.
  • Test variations across product types. The phrase running shoes may be equivalent to trainers in one catalog but not in a store that distinguishes running, lifestyle, and court footwear.

Multi-word synonym design is most effective when it combines accurate language modeling with controlled relevance testing. For WooCommerce agencies, the search analyzer should be treated as part of the client’s product data and release process, not as an isolated Elasticsearch setting.

Trending posts
You might also like