Migrate Search & Navigation features to Graph

Migrate individual search features from Optimizely Search & Navigation to Optimizely Graph. Each feature compares the Search & Navigation implementation with the equivalent Graph approach to help you understand functional differences, required code changes, and new query patterns. Use this information to update existing features incrementally while validating behavior during parallel operation.

Basic search

Basic search retrieves content based on free-text input and field matching. While both Search & Navigation and Graph support text-based search, the APIs and query models differ.

Search & Navigation

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

Graph:

{
  Content(where: { Name: { contains: "laptop"} }) {
    items {
      Name
    }
  }
}

Key differences

• Search & Navigation uses a fluent C# API.
• Graph uses GraphQL with declarative filters.
• Graph queries explicitly define returned fields.

Synonyms

Synonyms expand search queries with equivalent or related terms to improve relevance and reduce zero-result searches. The configuration model and query usage differ significantly between Search & Navigation and Graph.

Search & Navigation

Configure synonyms

Configure synonyms using either the API or the Admin UI.

Option 1: Programmatic API:

var client = SearchClient.Instance;

// Add bidirectional synonym
client.Optimizations().Synonyms().Add(new Synonym("bike", " bicycle ", true));
client.Optimizations().Synonyms().Add(new Synonym("h2o", " water ", true), Language.English);

// Add one-way synonym
client.Optimizations().Synonyms().Add(new Synonym("annanas", "pineapple") { Bidirectional = false });

Option 2: Admin UI:

1. Go to to CMS Admin > Search & Navigation > Synonyms.
2. Enter synonym pairs.
3. Select language or All languages.
4. Click Save.

Use synonyms in queries

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

Graph

Graph manages synonyms through REST APIs and applies them at query time using GraphQL arguments.

REST API

For complete API documentation, see Store synonyms in Optimizely Graph.

Format rules

• Use comma-separated values for bidirectional synonyms.
• Use => for one-way synonyms.
• Each line defines a single synonym rule.
• Synonyms are defined per language and per slot.

Example request body

bike, bicycle, cycle
H2O, water
mib => men in black
laptop => notebook computer

📘

Note

The request body uses plain text. JSON is not supported for synonym definitions.

Use synonyms in GraphQL queries

{
  Content(where: { _fulltext: { contains: "bicycle", synonyms: [ONE] } }) {
    items {
      Name
    }
  }
}

Key differences

• Search & Navigation enables synonyms implicitly with .UsingSynonyms().
• Graph requires explicit synonym slots (ONE, TWO) in the query.
• Graph applies synonyms only to supported operators.

For detailed instructions on migration, see the Synonyms migration guide.