Try our conversational search powered by Generative AI!

Area: Optimizely Search & Navigation
ARCHIVED This content is retired and no longer maintained. See the latest version here.

Recommended reading 


Synonyms can be used to improve search results by adding uni- or bi-directional relationships between phrases. This article explains how to manage synonyms programmatically. You can also create, edit, and delete synonyms in the Find administrative interface > Optimization screen. That functionlaity is documented in the EPiServer User Guide.

Using Synonyms

To enable search results to use synonyms, use the UsingSynonyms extension method for IQueriedSearch in EPiServer.Find namespace:

var results = client.UnifiedSearchFor("bike").UsingSynonyms().GetResult();

Managing Synonyms

A synonym has an id to use on update and removal. The id is defined by

  • the phrase (a)
  • the synonymous phrase (b)
  • whether relationship is bidirectional; meaning searches for b also returns results for a
  • tags for categorizing synonyms, for example, based on sites and languages

Client Extension

The synonyms client is made available through the extension method Synonyms on the Find client.

var synonymsClient = client.Synonyms();



var result = client.Synonyms().Add(new Synonym("bike", " bicycle ", true));
var synonymId = result.Id;

In this example, bike is the phrase, bicycle is the synonym, and true indicates that the relationship is bidirectional.


To get a synonym, pass its id to the Get method of the Synonyms client.

var result = client.Synonyms().Get(synonymId);


To delete a synonym, pass its id to the Get method of the Synonyms client.

var result = client.Synonyms().Delete(synonymId);


To retrieve synonyms, use the List method, which has size and from arguments to allow paging.

var size = 10;
var from = 120;
var result = client.Synonyms().List(size, from);

Size indicates the number of synonyms to return per page. From indicates the synonym at which to start the list.
The default size value is 10, and the default from value is 0. If you run client.Synonyms().List() with no parameters, it returns the first 10 synonyms.


  • client.Synonyms().List(5) returns the first 5 synonyms.
  • client.Synonyms().List(5, 5) returns the second page of the synonym list, 5 synonyms starting with sixth result (it skips the first 5).
  • client.Synonyms().List(5, 10) returns the third page of the synonym list: 5 synonyms starting from the eleventh result (it skips the first 10).

CommandActions argument

The Add, Get, Delete and List methods have overloads for passing a commandAction, which is run with the due command as an argument just before command execution.


var result = client.Synonyms().Delete(synonymId, command  => _log.Debug(command.Id));

Do you find this information helpful? Please log in to provide feedback.

Last updated: Feb 23, 2015

Recommended reading