---
title: Synonyms
slug: graph/docs/synonyms
docTags: 
createdAt: 2026-07-30T20:30:20.147Z
---

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.

:::hint{type="warning"}
**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`.

```text
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.

```text
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.

:::hint{type="warning"}
**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`.

```graphql
{
  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`.

```graphql
{
  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`).

```graphql
{
  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.

```graphql
{
  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.

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