Migrate Search & Navigation features to Graph

10 min

Migrate individual search features from Optimizely Search & Navigation to Optimizely Graph. Each feature compares the Search & Navigation implementation with the equivalent Graph approach so you can identify functional differences, required code changes, and query pattern updates. 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.

The following shows an example of basic search in Search & Navigation:

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

The following shows an example of basic search in 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 & NavigationSearch & Navigation and GraphGraph.

Configure synonyms using the 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 });

Configure synonyms using the Admin UI:

Go to CMS Admin > Search & Navigation > Synonyms.

Enter synonym pairs.

Select language or All languages.

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();

Synonyms in Graph

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

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

The following format rules apply:

Use comma-separated values for bidirectional synonyms.

Use => for one-way synonyms.

Define a single synonym rule on each line.

Define synonyms per language and per slot.

The following is an 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.

The following is an example of using synonyms in a GraphQL query:

{
  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 migrationSynonyms migration guide.

Best bets and pinned results

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

For detailed instructions on migration, see the Pinned results migrationPinned 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. You cannot migrate autocomplete directly and must configure it as a new feature in Graph.

For detailed instructions, see the Autocomplete migrationAutocomplete migration guide.

Boosting

Search & Navigation provides five boosting features: filter-based, time decay, hit popularity, unified weights, and attribute-based. Graph supports filter-based boosting and time decay with different syntax, and adds a BOOST_ONLY ranking mode that scores using only boost values

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

Migrate Search & Navigation features to Graph

Basic search

Key differences

Synonyms

Synonyms in Search & Navigation

Synonyms in Graph

Key differences

Best bets and pinned results

Autocomplete

Boosting