Basic PlanPro PlanEnterprise Plan

What is a Synonym?

A synonym is a word that means the same as another word in the same language, for example, "small" and "little" are synonyms. With Doofinder you can use custom synonyms to make results match other terms that are not usually included in your data feed.

What Are Custom Synonyms?

Custom synonyms are sets of synonyms which are applied and stored in the Index at the time of indexing.

Type of replacements / synonyms

We use two methods to replace words:

  • Synonyms (shoe, sport shoe, sneaker, trainers).

  • Explicit Replacements (icebox => cooler, fridge, freezer).

Let's see the difference between them!


This will return all products that contain instances of synonyms defined in a synonym set. They are structured and added separated by commas, in the following way: Synonym1, Synonym2, Synonym3...

The application of a synonym set to a product occurs at the time of indexing, where any occurrence of a defined synonym results in it being mapped to all the associated synonyms in the set.

🗒 Note: Commas (,) are reserved as a term separator and cannot be used within the synonym chain.

Let's say you have two products in your store:

  • Small camping cooler
  • Camping icebox iron

and a customer searches for fridge. As none of them have the word fridge included in the product feed, the customer will get no results.

But, if you add the following synonyms:

icebox, cooler, fridge

Your products will appear in the search results.

  • Small camping cooler
  • Camping icebox iron

Whenever the user searches for fridge, cooler or icebox, products containing any of these words should match as a search result.

After indexing, they will look like:

small camping (icebox|cooler|fridge)
camping (icebox|cooler|fridge) iron

IMPORTANT: For the synonym set to be applied correctly, one of the configured words in the synonym chain must exist in the feed. For example, if you want to create a synonym for COOLER, the word must exist in your feed. Otherwise, it will not work.

🗒 Note: The use of a synonym does not guarantee that you will have the same search results applying one and the other. You may get different results or in different order of priority.

Explicit Replacements

Explicit replacement entails substituting the original word with one or more words within the string. Consequently, if a user searches for the original word, no results will be generated. Instead, results will only appear when employing one of the synonyms.

This stands in contrast to the standard synonym string, which supplements the original word with additional terms.

Let's see an example:

TermToReplace => Synonym1, Synonym2...
icebox => cooler, fridge

Doofinder will then replace all occurrences of icebox for both cooler and fridge.

If your products are:

  • small icebox for camping
  • car cooler

After indexing, they will look like:

small (cooler|fridge) for camping
car cooler
  • In this case, as car cooler does not include the term icebox, nothing is being replaced.

IMPORTANT: for the synonyms set to be applied correctly, the term to replace must exist in the feed.

Notice Two Things

Only the first product is affected, only instances of the icebox word are mapped, cooler or fridge are not replaced.

If the user searches for icebox he will get no results.

In general terms, any occurrence of any element which is at the left of the => operator, is replaced by what is at the right of the => operator.

How to create a set of synonyms?

Go to your Admin Panel > Search Engines > Business Rules > Synonyms.

Remember to choose one Search Engine from the list, if you have more than one.

Then click on Add synonyms and a pop-up window will appear. Select whether you want to add a synonym or an explicit replacement.

  • Example of Synonym: Type the words separated by commas and save.
  • Example of Explicit replacement: Add the term or terms to be replaced, separated by commas in the first box. Then type the term or terms that will replace the words entered above.

Always remember to hit the 'Save' button.

This is how the synonyms screen will look like once you have created them. To add a new set of synonyms, click on the "Add synonym" button and to remove one, select it by checking the box on the left and click on the trash can icon on the right.

🗒️ Note: Each search engine has a limit of 1000 synonyms.

Replacement While Indexing

Doofinder, once per day at least (and any time you request it at its Product Feed admin section), crawls through your product feed, extracts the product info from that feed and stores it in a special file called the index. This process is called indexing.

When a user searches for anything, Doofinder looks for it in that index, because it's built in a way that makes it really quick to find stuff.

When you specify synonyms, Doofinder, while indexing, replace any occurrence of the synonyms by the whole synonyms set, and stores it in the index.

Let's have a look at the previous three products we were talking about. When Doofinder indexes those three products, with the synonyms line we inserted before, this is how (roughly) these products will be stored in the index (this is a human-readable representation to make it clearer).

small camping (icebox|cooler|fridge)
camping (icebox|cooler|fridge) iron

In a nutshell, Doofinder replaces any occurrence of any defined synonym by all its synonyms.

Attention To A Special Case

According to how the index building works, there is a special case with hyphens (-): They are always replaced by white spaces. So, when adding synonyms, they will always be saved using spaces rather than hyphens. Let's see another example. If you try to save this synonyms:

i-phone, iphone, mobile phone

What will be saved instead will be:

i phone, iphone, mobile phone

Don't worry if, after clicking Save you see i pod instead of i-pod. The index will also have hyphens replaced this way.

All this means that if you search for i-pod, according to this synonyms, you will also get in your results list, this item:

Special Apple Iphone Gold

as it was indexed this way:

special apple (iphone|i phone|mobile phone) gold

🗒 Note: As well as hyphens are replaced by spaces, symbols are removed from tokenizers, so they can't be used generating synonyms.

Import/Export Synonyms

You can import and export a list of synonyms from your admin by clicking on the add synonym drop-down menu in the upper right corner.

The import option opens a modal where you can upload the file in .csv format. The first line of the csv is not processed, since it is the header line.

Please note that the file must have one line per record and the synonyms must be separated by commas and enclosed in quotation marks, e.g. "sneaker, trainer, shoe".

If you check the box to replace existing ones, this action will remove the synonyms already created and add the new ones that the file contains.

Otherwise, the synonyms will be added over the existing ones.

The export option, will download a .csv file.