Dev GuideAPI ReferenceUser Guide
HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

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 mat want to find results that contain "water". This happens when you store synonyms in Optimizely Content Graph and enable them per field in your query. Otherwise, many relevant results may not be retrieved.

## Store 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 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

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

The synonyms are defined with 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 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`.


  • _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. 

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` 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 want to configure any synonyms (default behavior).
When you store the synonyms in Content 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.
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 are not applied. Results _also_ matching on synonyms are automatically ranked higher by the Content Graph system than those that do not, and results that have exact matches are ranked higher than results matching with synonyms.
Important
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. Content 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 synonym slot `ONE`, which also retrieves results that contains matches with `computer` and `pc` besides `laptop`.

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

In the following example, both synonym slots are used, where you want to match exactly on`big 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`).

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 previous configured synonyms.

Optimizely supports in-sentence synonym matching only with `contains`; that is, this query matches on previous expanded synonyms.