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.

Best bets and pinned results

Best bets in Search & Navigation and pinned results in Graph let you promote specific content to the top of search results for defined search phrases. Graph uses a collection-based REST API with GUID content references and explicit priority control, replacing the Admin UI and integer ID approach in Search & Navigation.

For detailed instructions on migration, see the Pinned results migration guide.

Autocomplete

Autocomplete (type-ahead) suggests possible completions as users type. Search & Navigation and Graph autocomplete use fundamentally different data sources — Search & Navigation suggests search phrases from manual entries and search history, while Graph suggests values from indexed content fields. This means autocomplete cannot be migrated directly and must be set up as a new feature in Graph.

For detailed instructions, see the Autocomplete migration guide.

Boosting

Boosting changes the relevance score of search results so that certain content appears higher or lower. Search & Navigation provides five boosting features (filter-based, time decay, hit popularity, unified weights, and attribute-based), while Graph supports filter-based boosting and time decay with different syntax, and offers a unique BOOST_ONLY ranking mode.

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