---
title: "Search with synonyms in C#"
url: https://recursiveai.org/oneindex/cookbook/search-with-synonyms/
description: "Use query-time synonyms in C# search. Match multiword phrases in both directions and update a synonym map without rebuilding indexed documents."
version: "0.4.0-preview.2"
---

# 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.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneIndex) · [GitHub](https://github.com/recursive-ai-oss/oneindex-csharp) · [Docs](https://recursiveai.org/oneindex/docs/) · [Download example (.zip)](https://recursiveai.org/oneindex/cookbook/search-with-synonyms/search-with-synonyms.zip)

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

```shell
dotnet add package RecursiveAI.OneIndex --prerelease
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/oneindex/cookbook/search-with-synonyms/search-with-synonyms.zip), 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.

```csharp
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`:

```csharp
var rules = new SynonymRules()
    .AddOneWay("sf", "san francisco");
```

The full output becomes:

```text
sf: abbr, sf
san francisco: sf
nyc: 
nyc: ny
```

## Related recipes

[Typo-tolerant search](https://recursiveai.org/oneindex/cookbook/typo-tolerant-search/) · [Query corrections](https://recursiveai.org/oneindex/cookbook/suggest-query-corrections/) · [Full-text search](https://recursiveai.org/oneindex/cookbook/full-text-search-csharp/)

---

## 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](https://recursiveai.org/oneindex/docs/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.
