Synonyms

Use synonyms in Optimizely Graph to expand search terms and return results that users might otherwise miss. Synonyms help avoid empty or sparse result sets, which can reduce search abandonment and improve conversions.

For example, a search for “H2O” can return results containing “water” when you store synonyms in Optimizely Graph and enable them per field in your query.

Store synonyms in Optimizely Graph

Synonyms are stored in a CSV file, where each line represents a single entry. Optimizely Graph supports two synonym files per language, called synonym slots ONE and TWO. Use multiple slots to separate stable synonyms from frequently updated or customer-specific synonyms.

🚧

Important

An entry in the synonym list cannot exceed 1,000 characters or bytes, and the file can contain up to 50,000 entries.

Synonyms are defined in two relationship types:

• Uni-directional (replacement) – Uni-directional synonyms use the => syntax. Words on the left are replaced with the words on the right. Multiple mappings for the same key are merged. So, in this example, the following entries snow => ice and snow => cold are merged to snow => ice, cold.

Example:

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

Merged result:

snow => ice, cold

• Bi-directional (equivalent) – Bi-directional synonyms use comma-separated values. All synonyms are treated as equivalent, and each line is handled independently without merging.

Example

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

Store synonyms with the REST API

Use the GraphQL Gateway REST endpoint to store synonyms. Authorization with your HMAC key and secret is required.

Request

PUT <GATEWAY_URL>/resources/synonyms

• Optional query string parameters:
  • 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 request body contains the CSV file with the synonym definitions. Send an empty body to clear synonyms.

Synonyms become available for search in near real time.

Retrieve synonyms with the REST API

Use the GET /synonyms endpoint to fetch all stored synonyms for a language and synonym slot. The endpoint returns synonyms as plain text, including the arrow-style and comma-separated notations used when storing synonyms.

You can filter the results by using query strings. The allowed query string structure is the same as the PUT /synonyms endpoint.

📘

Note

The GET /synonyms endpoint returns 404 when no synonyms exist.

Request

GET <GATEWAY_URL>/resources/synonyms

• Optional query parameters
  • synonym_slot – one or two (default: one)
  • language_routing – locale for the synonyms (default: no locale)

Response

The response contains the synonym definitions as plain text.

Query with synonyms

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

Optimizely Graph supports querying each synonym slot separately or together by using the synonyms operator, which accepts the enum values ONE, TWO, or a list of both.

When you do not specify synonyms, query expansion is not applied.

Search results that match synonyms automatically receive a higher ranking than results without synonym matches. Exact matches rank highest.

📘

Note

• Synonyms work only with string fields.
• Synonyms are queried case-insensitively when using contains.
• Synonyms are case-sensitive with eq and in (and their inverses). Add variants if you need case-sensitive matching.
• Synonyms support multi-word matching.
• Synonyms work with logical operators (_and, _or, _not) and boost.
• Synonyms are not applied for like, startsWith, endsWith, gt, gte, lt, lte, and exist.

Example queries

tore the 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 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
  }
}