Using Synonyms in Optimizely Graph Queries

Use synonyms in Optimizely Graph to expand search keywords so that users find results they would otherwise miss, which reduces empty result sets and the loss of conversions or even search abandonment.

For example, when a user searches for "H2O", they may want to find results that contain "water". This works when you store synonyms in Optimizely Graph and enable them per field in your query. Otherwise, many relevant results are not retrieved.

Prerequisites

Before you configure synonyms, confirm the following:

An Optimizely Graph account with API access.
An HMAC key and secret with permission to call the PUT <GATEWAY_URL>/resources/synonyms REST endpoint.
Your synonyms prepared as a CSV file, with each line under 1,000 characters or bytes and a total under 50,000 entries.

Store synonyms in Optimizely Graph

Store your synonyms in Optimizely Graph as a CSV file so they are available to query expansion at runtime. Each line is an entry. Optimizely Graph lets you store two synonym files per language: synonym slots ONE and TWO. This customization option can support multiple groups of customer-specified synonyms, and 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. The arrow notation => indicates 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) are not 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
```

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 – Stores the synonyms for a specific locale (default standard, that is, no locale).

The body should consist of synonyms as previously described, 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

Apply synonyms at query time to expand matches for string fields, so a query for one term also retrieves results that contain its configured equivalents.

Optimizely Graph lets you query two synonym files for each language, called synonym slots with the optional synonyms operator option. The option is of type enum list with values ONE and TWO. Query for either ONE or TWO, or specify them both in a list.

When you do not specify synonyms, query expansion with synonyms is not applied. Results that also match synonyms are automatically ranked higher by Optimizely Graph 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

The following examples show how query expansion behaves with the contains, in, and eq operators, so you can choose the right operator for the kind of match you need.

In the following example, you store the previous bi-directional synonyms 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 the in operator matches only on exact literal values, and 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. To match exactly on big apple, the query also exactly matches on expanded values NYC, New York City, New York (from synonym slot ONE), and 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. These operators compare the entire field value to the input, so an in-sentence occurrence of a synonym does not produce a match. The following 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 because contains scans the field text token by token, which allows the synonym expansion to match an occurrence inside a longer string. The following query matches previously expanded synonyms.

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