Synonyms

When you write a query, you can use synonyms to expand the keywords to get results that users otherwise may 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, if you search for "H2O", you may want to find results that contain "water". This happens when you store synonyms in Optimizely Graph and enable them per field in your query. Otherwise, many relevant results may not be retrieved.

Store synonyms in Optimizely Graph

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

🚧

Important

An entry in the synonym list cannot be greater than 1,000 characters or bytes. The maximum number of entries is 50,000.

The synonyms are defined by two types of relationships:

• 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 are replaced with the values on the right. Multiple unidirectional synonym mapping entries are merged. So, in this example, the following entries snow => ice and snow => cold are 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
  

• 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,
  BiographyPage, PeoplePage, peoplePage
  

You 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 – Takes as value one or two (default one).
  • language_routing – To store the synonyms for a specific locale (default: standard, that is, no locale).

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

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

Query with synonyms

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

Optimizely 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 is not applied. Results also match synonyms are automatically ranked higher by the Optimizely Graph system than those that do not, and results that have exact matches are ranked higher than results matching with synonyms.

🚧

Important

The synonyms only work for the string fields. Synonyms are not enabled in the GQL schema for other field types. Synonyms are queried case-insensitively with the contains operator with searchable string fields, but they are case-sensitive with the eq and in (including their inverse) operators. You must add case-sensitive variants as synonyms if you want to cover case sensitivity for eq and in (including their inverse) operators.

Optimizely Graph supports 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 are ignored even when provided.

Example queries

In the following example, you store the bi-directional synonyms above into the synonym slot ONE, which also retrieves results that contain matches with computer and pc besides laptop.

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

In the following example, no results are returned because you need to match exact literal values with the in operator because the configured synonyms are not applied to the literal string value when using in.

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

In the following example, both synonym slots are used. Where you want to match exactly 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 supports only matching on exact values, including on exact synonym values. So, this query does not match with previously configured synonyms.

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

Optimizely supports in-sentence synonym matching only with contains. That is, this query matches previously expanded synonyms.

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