Synonyms in C# SDK

Synonym expansion lets a query match additional related terms beyond the exact value specified in a filter. When you configure synonyms, a filter for a term such as car can also match related terms like automobile or vehicle. This improves search coverage and helps return more relevant results when different terms refer to the same concept.

Prerequisite

Synonym expansion requires a synonym dictionary configured on your Optimizely Graph instance.

Create or update a synonym dictionary using the PUT /resources/synonyms endpoint. If no synonym dictionaries exist, synonym slots have no effect and queries run normally without expansion.

How synonym slots work

Optimizely Graph supports two independent synonym slots:

• SynonymSlot.One
• SynonymSlot.Two

Each slot maps to its own synonym dictionary. Apply a slot to a filter to enable synonym expansion for that query condition.

To use synonym expansion, create filters with the BuildFilter<T>() API instead of inline .Where() expressions.

var filter = client.BuildFilter<ArticlePage>()
    .And(x => x.Author.Contains("search_term", SynonymSlot.One));

var result = await client
    .QueryContent<ArticlePage>()
    .Where(filter)
    .GetAsContentAsync();

Use Contains with synonym expansion

Apply synonym expansion to a Contains filter.

var filter = client.BuildFilter<ArticlePage>()
    .And(x => x.Author.Contains("search_term", SynonymSlot.One));

The query matches the provided value and any configured synonyms.

Use Match with synonym expansion

Apply synonym expansion to a Match filter for full-text matching.

var filter = client.BuildFilter<ArticlePage>()
    .And(x => x.Author.Match("search_term", SynonymSlot.One));

This expands the search term using the configured synonym dictionary.

Use multiple synonym slots

You can apply more than one synonym slot to a filter. This expands the query using multiple synonym dictionaries.

var filter = client.BuildFilter<ArticlePage>()
    .And(x => x.Author.Contains("search_term", SynonymSlot.One, SynonymSlot.Two));

Optimizely Graph evaluates synonyms from both dictionaries when matching results.

Use In with synonym expansion

Apply synonym expansion to an In filter to match any value in a list or its synonyms.

string[] terms = ["term_one", "term_two"];

var filter = client.BuildFilter<ArticlePage>()
    .And(x => x.Author.In(terms, SynonymSlot.One));

This returns items where the field matches the specified values or their configured synonyms.

Combine synonyms with other conditions

You can combine synonym filters with additional query conditions

var filter = client.BuildFilter<ArticlePage>()
    .And(x => x.Author.Contains("search_term", SynonymSlot.One))
    .And(x => x.IsFeatured.Match(true));

var result = await client
    .QueryContent<ArticlePage>()
    .Where(filter)
    .GetAsContentAsync();

This query returns featured articles where the Author field matches the provided value or any configured synonym.