Migrate synonyms

16 min

Migrate synonym functionality from Optimizely Search & Navigation to Optimizely Graph. This article explains differences in configuration, language handling, query behavior, and operator support. It also provides migration approaches for both small and large synonym sets. Use the information to preserve synonym behavior while running Search & Navigation and Graph in parallel during migration.

Synonyms expand search queries with equivalent or related terms. They improve search relevance and reduce zero-result searches when users use different terminology.

Use synonyms when:

Users search for different terms for the same concept (for example, bike and bicycle).

Brand names have common alternatives (for example, mib and men in black).

Technical terms have widely used alternatives (for example, H2O and water).

Learn more about feature comparisonsfeature comparisons for synonyms.

Migration options

Choose to do a manual migration or a programmatic migration.

Manual migration – Recommended for small to medium-sized synonym lists. Uses Search & Navigation Admin UI export and manual conversion.

Programmatic migration – Recommended for large synonym lists or multiple languages. Automates the entire migration process using code.

Manual migration

Manual migration is recommended for small to medium-sized synonym lists. It uses the Search & Navigation Admin UI export and manual conversion.

Go to Menu > Search & Navigation.

Go to Optimize > Synonyms.

Click Export.

Save the CSV file.

Convert to Graph plain text format

The following conversion rules apply:

Bidirectional (Search & Navigation: bidirectional: true) – Use commas.

One-way (Search & Navigation: bidirectional: false) – Use the => arrow.

The following is an example conversion from Search & Navigation CSV export:

phrase,bidirectional,synonym
"bike",true,"bicycle"
"h2o",true,"water"
"mib",false,"men in black"

The following is an example conversion to Graph plain text:

bike, bicycle
h2o, water
mib => men in black

Upload to Graph via the API

Complete the following steps using Postman or Swagger UI:

Go to https://cg.optimizely.com/app/swagger.

Locate the PUT /resources/synonyms endpoint.

Set language_routing and synonym_slot parameters accordingly.

Set body (raw text):

bike, bicycle
h2o, water
mib => men in black

Click Execute.

🚧 Important For All languages synonyms from Search & Navigation, repeat steps 1 through 5 for each language your application supports. For example, language_routing=en, then language_routing=sv, then language_routing=fr, and so on.

Programmatic migration

Programmatic migration is recommended for large synonym lists or multiple languages. It automates the entire migration process using code.

For a specific language:

var languageCode = Language.English.FieldSuffix; // e.g., "en"
var client = SearchClient.Instance;
var allSynonyms = client.Optimizations().Synonyms().List(size: 100, from: 0, [$"language:{languageCode}"]);

For All languages synonyms:

// Note: Language.All.FieldSuffix returns a GUID, not a language code
var allLanguagesCode = Language.All.FieldSuffix;
var client = SearchClient.Instance;
var allLanguagesSynonyms = client.Optimizations().Synonyms().List(size: 100, from: 0, [$"language:{allLanguagesCode}"]);

🚧 Important If you have All languages synonyms in Optimizely Search & Navigation, you must upload them to each individual language in Graph.

Convert to Graph plain text format

var graphSynonyms = new StringBuilder();
foreach (var synonym in allSynonyms.Hits)
{
    var formattedSynonym = synonym.Bidirectional
        ? $"{synonym.Phrase}, {synonym.SynonymPhrase}"
        : $"{synonym.Phrase} => {synonym.SynonymPhrase}";
    graphSynonyms.AppendLine(formattedSynonym);
}
string plainTextContent = graphSynonyms.ToString().TrimEnd();

Upload to Graph with HTTP client

📘 Note This example uses basic authentication. For better security, use HMAC authenticationHMAC authentication instead.

// Configure Basic authentication credentials
var appKey = "YOUR-APP-KEY";
var secret = "YOUR-APP-SECRET";
var credentials = Convert.ToBase64String(
    Encoding.UTF8.GetBytes($"{appKey}:{secret}")
);

// Upload to Graph
var httpClient = new HttpClient();
var graphLanguageCode = "en";
var synonymSlot = "one";
var url = $"https://cg.optimizely.com/resources/synonyms?language_routing={graphLanguageCode}&synonym_slot={synonymSlot}";

var request = new HttpRequestMessage(HttpMethod.Put, url);
request.Headers.Add("Authorization", $"Basic {credentials}");
request.Content = new StringContent(plainTextContent, Encoding.UTF8, "text/plain");

var response = await httpClient.SendAsync(request);
response.EnsureSuccessStatusCode();

Update application queries after migration

After migrating synonyms to Graph, update your application code to use GraphQL queries with synonym support.

The following is an example of Search & Navigation before migration:

var results = await SearchClient.Instance
    .Search<IContent>(Language.English)
    .For("bicycle")
    .InField(x => x.Name)
    .UsingSynonyms()
    .Take(10)
    .GetContentResultAsync();

The following is an example of Graph after executing GraphQL queries in C#:

using Optimizely.ContentGraph.Core;

public class SearchService
{
    private readonly IClient _graphClient;

    public SearchService(IClient graphClient)
    {
        _graphClient = graphClient;
    }

    public async Task<SearchResult> SearchWithSynonymsAsync(string searchTerm)
    {
        var query = @"
            query SearchContent($searchTerm: String!) {
              Content(
                where: { Name: { contains: $searchTerm, synonyms: [ONE] } }
                locale: en
                limit: 10
              ) {
                total
                items {
                  Name
                  ContentType
                }
              }
            }";

        var variables = new { searchTerm };
        var result = await _graphClient.QueryAsync(query, variables);
        return result;
    }
}

Verify and test

After uploading synonyms, verify the upload was successful and test synonym functionality.

Verify upload with REST API

Confirm the upload succeeded using the Swagger UI.

Go to https://cg.optimizely.com/app/swagger.

Locate the GET /resources/synonyms endpoint.

Set language_routing and synonym_slot parameters accordingly.

Execute the request.

Verify the response contains your synonym list.

Test synonyms with Optimizely GraphQL

Test synonym expansion using GraphiQL: https://cg.optimizely.com/app/graphiql?auth=YOUR_SINGLE_KEY.

The following is an example of testing bidirectional synonyms:

# Searching for "bike" should find content with both "bike" and "bicycle"
{
  Content(where: { Name: { contains: "bike", synonyms: [ONE] } }) {
    total
    items {
      Name
    }
  }
}

The following is an example of testing one-way synonyms:

# Searching for "mib" should find "men in black"
{
  Content(where: { _fulltext: { contains: "mib", synonyms: [ONE] } }) {
    total
    items {
      Name
      _fulltext
    }
  }
}

The following example tests both synonym slots:

{
  Content(where: { Name: { contains: "laptop", synonyms: [ONE, TWO] } }) {
    total
    items {
      Name
    }
  }
}

For more query examples, see Query with synonymsQuery with synonyms.

Migrate synonyms

Migration options

Manual migration

Export synonyms from Search & Navigation Admin UI

Convert to Graph plain text format

Upload to Graph via the API

Programmatic migration

Fetch synonyms from Search & Navigation

Convert to Graph plain text format

Upload to Graph with HTTP client

Update application queries after migration

Verify and test

Verify upload with REST API

Test synonyms with Optimizely GraphQL