Synonyms in C# SDK

7 min

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

Prerequisites

Synonym expansion requires a synonym dictionary configured on your Optimizely Graph instance. See SynonymsSynonyms for configuration details.

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

The Match filter expands the search term through the configured synonym dictionary.

Use multiple synonym slots

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

The In filter returns items where the field matches the specified values or their configured synonyms.

Combine synonyms with other conditions

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.