Synonyms | Yext Hitchhikers Platform

What You’ll Learn

By the end of this unit, you will be able to:

• Define synonyms and the types of synonyms
• Describe best practices and use cases around synonyms

Overview

In the last module, we covered the Search configuration properties that are applied to verticals. In this module, we’ll cover Search configuration properties that are applied to the whole search, across all verticals.

We’ll begin with synonyms. Synonyms tell Search which words and phrases to consider as having the same meaning.

For example, you have “Healthcare Professional” entities in your Content, 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 review the Vertical Ranking unit.

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 that are defined in the backend configuration, the algorithm produces “expanded” versions of the query by replacing the parts of the query with matching synonyms.

Example:

• Let’s say you set a one way synonym: “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”
• Original search term: “doctor near me”
• 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 between 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” (in the case of the Search configuration on Hitchhikers search!)
• Some resources may use the term “Search config” and others may use “Search configuration”. However, any search queries with either should return results for the other as well.

Common Use Cases

Here are some common use cases for synonyms:

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

• “phone” = “products” for Telecom company
• “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

Consider the following best practices when implementing synonyms:

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. You should 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. It is likely something you could address in your configuration or Content.
3. Don’t use keywords as synonyms: Synonyms are a really great tool to manipulate results in Search. However, make sure you are not abusing synonyms and that the phrases/words in question actually mean the same thing. A common mistake is using synonyms to make keywords work.
   • For example, let’s say you are a financial services business and you have Visa cards and American Express cards as products. You want the query “credit card” to return both of these entities.
     • 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. This will help keep your configuration clean and easy to read. 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

This means 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, such as “doctor” = “healthcare professional” = “physician”.

Synonyms Must Match Exactly

We don’t do any stemming on terms before applying synonyms. Synonyms do not automatically apply plurals. For example, we have been using the entity type “Restaurant” with plural “Restaurants”. If you have a synonym set for “location” = “restaurant”, searching for:

• “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. Simply 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 reference doc to learn more about the synonyms config properties.

The same synonyms 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"
      }
    ]
  },