Synonyms

Synonyms are "one of two or more words or expressions of the same language that have the same or nearly the same meaning in some or all senses" – Merriam Webster

When writing queries, it can be very effective to use synonyms to expand the keywords in order to get relevant results that users otherwise would not have found. This reduces the problem of getting too few or no results, leading to fewer chances of conversions or even search abandonment. For example, when a user searched for "H2O", that user most likely also want to find results that contains "water". This is made possible by storing your synonyms in Optimizely Content Graph and enable them per field in your query. Otherwise, many relevant results would not have been retrieved.

Storing Synonyms in Content Graph

Synonyms are stored as a CSV file, where each line is an entry. Content Graph lets you store two synonym files per language, which are called synonym slots ONE and TWO. This option to customize can be useful to for example support multiple groups of customer-specified synonyms, but also to separately store synonyms which are stable, not frequently updated, and should be beyond editorial control.

🚧

Validation of synonyms

A entry in the synonym list cannot be greater than 1,000 characters/bytes and the maximum number of entries is 50,000.

The synonyms can be defined with 2 types of relationships:

1. Uni-directional (replacement): the synonyms are mapped to specific words in one direction using the => syntax and only those specific words are used in the query. This is indicated with the => arrow notation to indicate a synonym mapping. The values on the left will be replaced with the values on the right. Multiple unidirectional synonym mapping entries will be merged. So in this example, the following entries snow => ice and snow => cold will be merged to snow => ice, cold.

   H20 => water
   Siteseeker, Welcome, Episerver => Optimizely
   William Henry Gates III => Bill Gates
   big apple, big fruit
   snow => ice
   snow => cold
   

2. Bi-directional (equivalent): the synonyms are treated as equivalent and go in both directions and all the words are used in the query expansion by separating them with commas. With this notation, overlapping entries (lines) will not be merged, so each line is its own entry.

laptop, computer, pc
NYC, New York City, New York, Big Apple
i-phone, iPhone, i Phone

We can store synonyms using the REST endpoint configured in the GraphQL Gateway. It requires authorization using your HMAC key and secret.

• PUT <GATEWAY_URL>/resources/synonyms with the following optional query strings:
  • synonym_slot which takes as value one or two (default one) .
  • language_routing to store the synonyms for a specific locale (default: standard, i.e., no locale).

The body should consist of synonyms as described above or can be empty if you do not wish to configure any synonyms (default behavior).

When you store the synonyms in Content Graph, these will become available for search in near real-time.

Querying with Synonyms

Synonyms only work for the String fields. Synonyms are not enabled in the GQL schema for other field types.

Content Graph lets you query two synonym files for each language, which are called synonym slots with the optional synonyms operator option, which is of type enum list with values ONE and TWO. You can query for either ONE or TWO, or specify them both in a list. When you do not specify synonyms, then query expansion with synonyms will not be applied. Results also matching on synonyms will be automatically ranked higher by the Content Graph system than those that do not, and results that will have exact matches will be ranked higher than results matching with synonyms.

📘

Import note about querying with synonyms

The synonyms are queried case-insensitively and only work for the String fields. Synonyms are not enabled in the GQL schema for other field types. We correctly support matching on multi-word synonyms. It also works in combination with the logical connections (_and, _or, _not) and boost. The synonyms are fully supported for all the operators, except for like, startsWith, endsWith, gt(e), lt(e), exist, where synonyms will be ignored even when provided.

Example queries

In this example, we have stored the bi-directional synonyms above into synonym slot ONE, which will also retrieve results that contains matches with computer and pc besides laptop.

{
  Content(locale: en, where: {MainBody: {contains: "laptop", synonyms: ONE}}) {
    items {
      MainBody
    }
    total
  }
}

This request will not return any results either, because we need to match on exact literal values with the in operator, because the configured synonyms will not be applied on the literal string value when using in.

{
  Content(locale: en, where: {Name: {IN: ["a laptop is not an iPhone"], synonyms: ONE}}) {
    items {
      Name
    }
  }
}

This is an example where both synonym slots are used, where we exactly want to match onbig apple, it will also exactly match on expanded values NYC, New York City, New York (from synonym slot ONE), but also big fruit (from synonym slot TWO).

{
  Content(locale: en, where: {Name: {eq: "big apple", synonyms: [ONE, TWO]}}) {
    items {
      Name
    }
    total
  }
}

For the eq,notEq, in and notIn operators, Optimizely only supports matching on exact values, including on exact synonym values. So this query will not match with above configured synonyms.

{
  Content(locale: en, where: {MainBody: {eq: "this is a big apple", synonyms: ONE}}) {
    items {
      MainBody
    }
    total
  }
}

But Optimizely supports in-sentence synonym matching only with contains; that is, this query will be matching on above mentioned expanded synonyms.

{
  Content(locale: en, where: {MainBody: {contains: "this is a big apple", synonyms: ONE}}) {
    items {
      MainBody
    }
    total
  }
}