Synonyms tell Search which words and phrases to consider as having the same meaning.

For example, you have "Healthcare Professional" entities in your Knowledge Graph, but people generally refer to these entities as "doctors". You can define a synonym from "doctors" = "healthcare professionals". A search for "doctors" returns "healthcare professionals."

Synonyms are set at the experience level since business rules vary from client to client. If you want to set synonyms at a vertical level, use vertical intents and review the Vertical Ranking doc.

Types of Synonyms

Search has three types of synonyms:

• One way synonym: If you want term A to find term B, but not the other way around.
• Normalization synonym: The inverse of one-way synonyms. If you want term B to find term A, but not the other way around. This is used to map a set of many terms to one term.
• Synonym sets: If you want all terms to find all other terms in the group.

One Way Synonyms

For a single query, the Search algorithm takes each word, and every combination of words, and checks if a synonym exists for that phrase. Using the synonyms defined in the backend configuration, the algorithm produces "expanded" versions of the query by replacing parts of the query with matching synonyms.

Example:

• Synonym set: "career" → "job"
• Original search query: "career information"
• Expanded search terms:
  • "career information"
  • "job information"

However, the query "job information" will only search for "job information" and not "career information".

Normalization Synonyms

Normalization synonyms are the exact inverse of a one-way synonym, where a set of many terms is mapped to one term. These are particularly useful when multiple search terms can be used to reference the same thing.

Example:

• Normalization synonyms: "physician", "nurse", "md" → "doctor"
• The following search queries would all be normalized and interpreted as "doctor near me":
  • "Physician near me"
  • "Nurse near me"
  • "MD near me"

This is the equivalent of setting multiple one way synonyms: "physician" → "doctor", "nurse" → "doctor", and "md" → "doctor". Searching for "physician near me" would give you the expanded search terms:

• "Physician near me"
• "Doctor near me"

Synonym Sets

Synonym sets work similarly to how one way synonyms work. The only difference is that synonym sets expand in both directions. We are essentially creating many one way synonyms for all permutations of the set.

Example:

• Synonym set: "config", "configuration"
• Some resources may use the term "Search config" and others may use "Search configuration". Any search queries with either will return results for the other.

Common Use Cases

Mapping a commonly searched industry phrase to the name of an entity type:

• "phone" = "products" for Telecom companies
• "location" = "healthcare facility" for healthcare clients
• "location" = "restaurant" for food clients
• "branch" = "location" for financial services clients
• "provider" = "doctor" = "healthcare professional" = "physician" for healthcare clients

Industry-specific terms or abbreviations to full term:

• "heloc" = "home equity line of credit"
• "IRA" = "individual retirement account"
• "fb" = "Facebook"

Common abbreviations or slang to full term:

• "carbs" = "carbohydrates"
• "document" = "documents" = "docs" = "doc"

Best Practices

1. Don't overuse synonyms to start. Build up synonyms gradually throughout QA and subsequently the post-launch period. You want to be sure you are making improvements based on real user data as much as possible.
2. Don't use filler words within synonyms. Don't use more than two to three words in a single phrase. Keep synonym definitions as basic as possible. The inclusion of more words can potentially cause undesired consequences. If you find yourself mapping "how do I see an allergist tomorrow" to "healthcare professional", there is probably a more concise way to accomplish the end goal that you could address in your configuration or Knowledge Graph.
3. Don't use keywords as synonyms. Synonyms are a great tool to manipulate results in Search. However, make sure the phrases/words in question actually mean the same thing. A common mistake is using synonyms to make keywords work. For example, if you are a financial services business with Visa cards and American Express cards as products, and you want "credit card" to return both:
   • Don't: Set up a synonym from "credit card" → "American Express" and "credit card" → "Visa". This isn't scalable and they actually aren't synonymous.
   • Do: Make sure you are indexing keywords within the vertical in question, and add "credit card" as a keyword for all applicable entities.
4. Don't set synonyms in multiple places. Use the correct synonym type so that you're not defining more rules than necessary. For example, don't define a two-way synonym relationship as two one way synonyms. Instead, use a synonym set.

Synonym Nuances

Chaining is Not Supported

If you have a synonym from "doctor" → "healthcare professional", and a separate synonym from "healthcare professional" → "physician", searching "doctor" matches "healthcare professionals", but not "physician". This applies to all types of synonyms. If you want chaining behavior, create a synonym set: "doctor" = "healthcare professional" = "physician".

Synonyms Must Match Exactly

Synonyms do not automatically apply plurals. For example, if you have a synonym set for "location" = "restaurant":

• "location" will return all restaurants
• "locations" does not return restaurants

To search for plurals, you must include them in your synonyms as well.

Multi-Word Synonym Matching

Queries must have multi-word synonyms exactly for them to be activated, meaning they must be in the correct order with nothing in between.

For example, take the synonym set "IRA" = "individual retirement account". The query "individual retirement account" will return results for "IRA" and "individual retirement account". The query "retirement account" will not activate the synonym at all.

Edit Synonyms

Edit via the Platform UI

To configure synonyms in the UI, navigate to the Synonyms screen. Input your choices into the respective One Way Synonyms, Synonym Sets, or Normalization Synonyms section. To add a new synonym for any of the types, click the + Add button in the top right of that section. Type in the synonyms and press enter to separate terms.

Edit via the JSON Editor

Check out the Search Config - Synonyms doc to learn more about the synonyms config properties.

The same synonyms shown in the screenshot above would look like the below in the configuration:

"synonyms": {
  "oneWay": [
    {
      "phrase": "order online",
      "synonyms": [
        "delivery"
      ]
    }
  ],
  "synonymSet": [
    [
      "location",
      "restaurant",
      "locations",
      "restaurants"
    ]
  ],
  "normalization": [
    {
      "from": [
        "rewards",
        "points",
        "membership"
      ],
      "to": "gift card"
    }
  ]
},

Troubleshooting Synonyms

Before troubleshooting synonyms specifically, follow the How to Start Debugging Backend Search Issues documentation for general troubleshooting steps.

General Troubleshooting Steps

1. Check the tokens the search is comprised of. The tokens of the query impact which synonyms are applied. Tokens are shown in the search factors box on the right side of the search log.
   • If the token is different from the synonym, the synonym will not be applied. Check the synonyms configured in step 2.
   • If there are words in the search query that are not identified as tokens, they are either a built-in stop word (e.g. "or", "of", or "in") or an additional stop word. To check and remove additional stop words:
     1. Navigate to Search > [Experience Name] > General Settings.
     2. Under Additional Stop Words, remove the term if needed.
2. Check synonyms configuration. Make sure synonyms are configured correctly as intended.
   1. Navigate to Search > [Experience Name] > Synonyms.
   2. Confirm the synonyms are configured correctly:
      • Check for the correct configuration between one-way synonyms, normalization synonyms, and synonym sets.
      • Check for typos and alternate forms of the word.