Recursive AI

Search with synonyms in C#

OneIndex is a free, open-source search library for .NET from Recursive AI. MIT or Apache-2.0, preview, runs in-process.

Expand search terms at query time with synonyms, without rebuilding indexed documents.

Terminal
dotnet add package RecursiveAI.OneIndex --prerelease

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneIndex;
using var index = SearchIndex.InMemory<Page>();
index.Upsert(new Page { Id = "1",
    Body = "san francisco travel" });
index.Commit();
foreach (var hit in index.Search("sf "))
    Console.WriteLine(hit.Document.Body);
 
[Synonyms("sf", "san francisco")]
public class Page
{
    [SearchId]
    public string Id { get; set; } = "";
    [FullText]
    public string Body { get; set; } = "";
}
Text
san francisco travel

Unzip the example, then dotnet run.

The full program

The snippet at the top uses a mutual synonym attribute. Its trailing space marks sf as a completed search word, not an unfinished prefix.

The full program uses an explicit query-time map instead, with the standard analyzer used by the Body field. It searches both directions of sf / san francisco, then adds nyc → new york and rebuilds only the map. There are no document writes or commits after that change. All three input documents are shown in the program.

This example uses 0.4.0-preview.2; APIs and file formats may change between previews.

C#
using OneIndex;
using OneIndex.Analysis;
using OneIndex.Search;
 
using var index = SearchIndex.InMemory<Page>();
index.Upsert([
    new() { Id = "sf", Body = "san francisco travel" },
    new() { Id = "abbr", Body = "sf travel" },
    new() { Id = "ny", Body = "new york travel" }
]);
index.Commit();
var analyzer = new StandardAnalyzer();
var rules = new SynonymRules().AddGroup("sf", "san francisco");
var map = rules.Build(analyzer);
Show("sf");
Show("san francisco");
Show("nyc");
rules.AddOneWay("nyc", "new york");
map = rules.Build(analyzer); // no document writes or commit
Show("nyc");
 
void Show(string text)
{
    var graph = TokenGraph.FromText(analyzer, text, map);
    var query = TokenGraphQueries.ToWords(graph, "Body");
    var ids = index.SearchBy(query).Execute().Select(h => h.Id).Order();
    Console.WriteLine($"{text}: {string.Join(", ", ids)}");
}
 
public class Page
{
    [SearchId] public string Id { get; set; } = "";
    [FullText] public string Body { get; set; } = "";
}

dotnet run prints:

Text
sf: abbr, sf
san francisco: abbr, sf
nyc: 
nyc: ny

A query that analyzes to no terms lowers to MatchAllQuery; reject blank or stop-word-only input before using it when “show everything” is not intended.

Variations

Replace the full program’s rules declaration with a directional rule. Searching sf still finds the phrase, but searching the phrase no longer expands to sf:

C#
var rules = new SynonymRules()
    .AddOneWay("sf", "san francisco");

The full output becomes:

Text
sf: abbr, sf
san francisco: sf
nyc: 
nyc: ny

Typo-tolerant search · Query corrections · Full-text search


The short answer

Use query-time expansion to add synonyms without rewriting indexed documents. OneIndex’s SynonymRules builds an analyzed SynonymMap; TokenGraph.FromText expands a query through that map, and TokenGraphQueries.ToWords creates a query for SearchBy. Rebuild the map when your vocabulary changes. The full program adds a rule and searches again against the same committed documents.

For fixed rules on a document type, the top snippet shows the [Synonyms] attribute. For rules that change independently of the schema, the explicit map makes the update boundary visible. The behavior is documented in Synonyms.

How to search for synonyms?

Decide whether the relationship is mutual or directional. AddGroup("sf", "san francisco") lets each form find the other. AddOneWay("nyc", "new york") expands only a query for nyc; it does not make a query for new york find every document that only contains nyc. The variation demonstrates the reverse direction disappearing when a group is replaced by a one-way rule.

Rules do not chain transitively. If one rule maps a term to a second and another maps the second to a third, the first query does not automatically expand to the third. Define the vocabulary relationships you actually want rather than relying on indirect paths through a thesaurus.

Multiword alternatives are phrases. A rule for san francisco is not a loose bag of two unrelated words anywhere in the document. The token graph preserves that phrase relationship when it lowers to the executable query. The sample sorts returned IDs only to make the displayed membership easy to read; it does not display or compare relevance scores.

Can I update search synonyms without reindexing?

Yes. Nothing is stored in the index for the synonym map. The example commits its documents once, builds the initial map, and then builds a replacement map after adding a rule. Show("nyc") changes from no hits to ny without another Upsert or Commit.

Use the field’s own analyzer for both rule building and query analysis. The example’s plain [FullText] field uses the standard analyzer, which performs Unicode word segmentation and case folding without stemming or stop-word removal. A field configured for another analyzer needs that same analyzer in the explicit expansion path. A map built for a different token vocabulary can produce terms that the field never indexed.

Configured stop words apply to the rules as well as the query. A rule whose phrase becomes empty is dropped; an alternative identical to its analyzed key is also dropped. Those outcomes do not require rewriting documents, but they do affect which vocabulary rules survive.

Why should you use synonyms when searching with keywords?

Use them for explicit terminology differences: an abbreviation, a regional term, or a phrase users type instead of the phrase in your content. They are not inferred spelling corrections and do not need an embedding model. Keep typo tolerance and “did you mean” suggestions as separate choices.

Expansion is bounded. The guide gives defaults of three query words per rule lookup, 50 synonyms per key, 100 words across a key’s synonyms, and 64 readings of a query. Later alternatives can be dropped, and DroppedSynonyms reports map drops. A token graph can also report IsTruncated when its path cap prevents expansion. Longer alternatives are allowed even though lookup keys are bounded.

Synonym-derived parts receive a default boost of 0.8 while original words carry 1. Do not equate a synonym with an exact textual occurrence in every scoring context. Inspect real queries from your content, and keep a group small enough that every association is useful.

All oneindex recipes