Synonyms
How to enable and use synonyms
Synonyms are "one of two or more words or expressions of the same language that have the same or nearly the same meaning in some or all senses" – Merriam Webster
When writing queries, it can be very effective to use synonyms to expand the keywords in order to get relevant results that users otherwise would 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, when a user searched for "H2O", that user most likely also want to find results that contains "water". This is made possible by storing your synonyms in Optimizely Content Graph and enable them per field in your query. Otherwise, many relevant results would not have been retrieved.
Storing 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 for example 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
A entry in the synonym list cannot be greater than 1,000 characters/bytes and the maximum number of entries is 50,000.
The synonyms can be defined with 2 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 entriessnow => ice
andsnow => cold
will be merged tosnow => 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
We 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 valueone
ortwo
(defaultone
) .language_routing
to store the synonyms for a specificlocale
(default:standard
, i.e., no locale).
The body should consist of synonyms as described above or can be empty if you do not wish to configure any synonyms (default behavior).
When you store the synonyms in Content Graph, these will become available for search in near real-time.
Querying 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 will not be applied. Results also matching on synonyms will be automatically ranked higher by the Content Graph system than those that do not, and results that will have exact matches will be ranked higher than results matching with synonyms.
Import note about querying with synonyms
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. We correctly support matching on multi-word synonyms. It also works in combination with the logical connections (
_and
,_or
,_not
) andboost
. The synonyms are fully supported for all the operators, except forlike
,startsWith
,endsWith
,gt(e)
,lt(e)
,exist
, where synonyms will be ignored even when provided.
Example queries
In this example, we have stored the bi-directional synonyms above into synonym slot ONE
, which will also retrieve results that contains matches with computer
and pc
besides laptop
.
{
Content(locale: en, where: {MainBody: {contains: "laptop", synonyms: ONE}}) {
items {
MainBody
}
total
}
}
This request will not return any results either, because we need to match on exact literal values with the in
operator, because the configured synonyms will not be applied on the literal string value when using in
.
{
Content(locale: en, where: {Name: {IN: ["a laptop is not an iPhone"], synonyms: ONE}}) {
items {
Name
}
}
}
This is an example where both synonym slots are used, where we exactly want to match 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 only supports matching on exact values, including on exact synonym values. So this query will not match with above configured synonyms.
{
Content(locale: en, where: {MainBody: {eq: "this is a big apple", synonyms: ONE}}) {
items {
MainBody
}
total
}
}
But Optimizely supports in-sentence synonym matching only with contains
; that is, this query will be matching on above mentioned expanded synonyms.
{
Content(locale: en, where: {MainBody: {contains: "this is a big apple", synonyms: ONE}}) {
items {
MainBody
}
total
}
}
Updated about 2 months ago