Synonyms are often introduced as an indexing feature, but WooCommerce agencies can usually add or change customer-facing synonyms without reindexing product documents. The key is to apply the synonym rules in a search-time analyzer rather than the index-time analyzer.
Why search-time synonyms avoid product reindexing
Elasticsearch stores the analyzed terms produced when a product is indexed. If synonyms are applied during indexing, changing the synonym list changes the terms that should have been stored, so existing products must be reindexed.
With search-time synonyms, the product index remains unchanged. Elasticsearch analyzes the shopper’s query, expands or replaces the query terms, and searches the existing terms. This is useful for catalog teams that regularly add vocabulary such as:
tvandtelevisionmobile phoneandsmartphonesneakersandtrainers- brand-specific terms such as
hoodieandpullover
Use a search analyzer with synonym_graph
For modern Elasticsearch versions, synonym_graph is the appropriate filter for search-time synonyms, especially when rules contain multiple words. The synonym filter should be placed in a search analyzer, not the analyzer used to index the product fields.
PUT products-v1
{
"settings": {
"analysis": {
"filter": {
"catalog_search_synonyms": {
"type": "synonym_graph",
"synonyms_set": "woocommerce-catalog",
"updateable": true
}
},
"analyzer": {
"catalog_search": {
"type": "custom",
"tokenizer": "standard",
"filter": [
"lowercase",
"catalog_search_synonyms"
]
}
}
}
},
"mappings": {
"properties": {
"name": {
"type": "text",
"analyzer": "standard",
"search_analyzer": "catalog_search"
}
}
}
}
The exact index settings depend on the Elasticsearch version and the agency’s index template. The important details are that the synonym filter is query-time only, the filter is updateable where supported, and the field’s search_analyzer points to the analyzer containing that filter.
Store and update the synonym set
On Elasticsearch versions that support managed synonym sets, a synonym set can be created independently of the product index:
PUT _synonyms/woocommerce-catalog
{
"synonyms": [
"tv, television",
"mobile phone, smartphone",
"sneakers, trainers"
]
}
Use equivalent rules when both terms should match one another. Use an explicit directional rule when the business requirement is one-way expansion:
PUT _synonyms/woocommerce-catalog
{
"synonyms": [
"tv, television",
"running shoes => running footwear"
]
}
After changing a managed synonym set, reload the search analyzers for the affected index when required by the Elasticsearch version and deployment configuration:
POST products-v1/_reload_search_analyzers
Some managed-synonym workflows trigger analyzer updates automatically, but an explicit reload is useful in deployment scripts and operational runbooks. Verify the behavior in the specific Elasticsearch version before relying on automatic propagation.
Test the analyzer before exposing the change
Use the _analyze API to confirm that a shopper’s query produces the intended tokens:
POST products-v1/_analyze
{
"analyzer": "catalog_search",
"text": "smartphone case"
}
For a multiword synonym, inspect the token graph rather than checking only whether a single token appears. A synonym that expands too broadly can reduce relevance, while a replacement rule can hide products that contain the original wording.
Then test the real search request against representative WooCommerce queries:
GET products-v1/_search
{
"query": {
"multi_match": {
"query": "tv wall mount",
"fields": ["name^4", "short_description", "description"]
}
}
}
Make sure the WooCommerce integration sends the query to fields using the configured search analyzer. Adding an analyzer to an index does not change requests that bypass that field or explicitly specify a different analyzer.
WooCommerce implementation considerations
Most WooCommerce search integrations build an Elasticsearch index from product titles, SKUs, attributes, categories, and descriptions. Synonyms do not need to be copied into those product documents when they are applied at search time. This means a synonym release can normally be deployed without running a product export or bulk reindex.
Keep the synonym set separate from product content and manage it as configuration. A practical workflow is:
- Collect failed searches and support-team vocabulary from the WooCommerce site.
- Propose a rule and identify whether it should be equivalent or directional.
- Test the rule against product names, attributes, SKUs, and category terms.
- Update the synonym set in a staging cluster.
- Reload analyzers if necessary and run representative search tests.
- Promote the change and monitor zero-result searches, click-through rate, and conversion rate.
Do not automatically create synonyms for product identifiers. A SKU, model number, or regulated product term may look similar to another value but represent a different product. Also be cautious with brand names, singular and plural forms, spelling corrections, and terms that have different meanings in different product categories.
Important limitations
Search-time synonyms only affect queries analyzed by the configured search analyzer. They do not change aggregations, stored product text, autocomplete data, sorting values, or fields that use a different analyzer. If a WooCommerce autocomplete feature uses a separate completion index, that index may require its own synonym strategy.
Synonym rules also have parsing requirements. The terms in a rule are analyzed when the synonym set is loaded, so filters placed before the synonym filter must be compatible with synonym parsing. Token filters that produce graphs or remove terms can make rules invalid or produce unexpected expansions. Keep the analysis chain simple before the synonym filter, commonly using lowercase and carefully selected character normalization.
If the business requires synonyms to influence aggregations, highlighting, stored terms, or every downstream query independently of analyzer configuration, search-time synonyms may not be sufficient. In those cases, an intentional reindex or a separate normalized field may be the safer design.
Operational checklist
- Use
synonym_graphfor search-time multiword synonyms. - Keep the synonym filter out of the index analyzer when avoiding reindexing.
- Use an updateable search analyzer and a managed synonym set where the Elasticsearch version supports them.
- Reload affected search analyzers after changes when required.
- Test token graphs and actual WooCommerce search requests.
- Monitor relevance and zero-result searches after each synonym release.
- Reindex only when the synonym behavior must be present in indexed terms or other derived data.