Recursive AI

Search exact phrases and word proximity in C#

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

Slop is the number of extra words allowed between phrase words; their order must still match.

Terminal
dotnet add package RecursiveAI.OneIndex --prerelease

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

C#
using OneIndex;
using OneIndex.Search;
using var index =
    SearchIndex.InMemory<Note>();
index.Upsert(new Note {
    Body = "quick red brown" });
index.Commit();
var query = new PhraseQuery(
    "Body", ["quick", "brown"]) { Slop = 1 };
Console.WriteLine(index.SearchBy(query).Count());
public class Note
{
    [SearchId]
    public string Id { get; set; } = "a";
    [FullText]
    public string Body { get; set; } = "";
}
Text
1

The count is 1 because “quick red brown” has one extra word between “quick” and “brown,” within Slop = 1.

Unzip the example, then dotnet run.

The full program

All documents are created inline in an in-memory index.

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

C#
using OneIndex;
using OneIndex.Search;
using var index = SearchIndex.InMemory<Note>();
index.Upsert([
    new() { Id = "exact", Body = "quick brown" },
    new() { Id = "gap", Body = "quick red brown" },
    new() { Id = "reverse", Body = "brown quick" }
]);
index.Commit();
foreach (int slop in new[] { 0, 1, 100 })
{
    var query = new PhraseQuery("Body", ["quick", "brown"]) { Slop = slop };
    Console.WriteLine($"Slop {slop}: " + string.Join(", ",
        index.SearchBy(query).Select(h => h.Id).Order()));
}
public class Note
{
    [SearchId] public string Id { get; set; } = "";
    [FullText] public string Body { get; set; } = "";
}

dotnet run prints:

Text
Slop 0: exact
Slop 1: exact, gap
Slop 100: exact, gap

A phrase field without indexed positions throws QueryException rather than returning an empty result.

Variations

Reverse the query words. Insert this before the full program’s Note class:

C#
var reverse = new PhraseQuery("Body", ["brown", "quick"])
    { Slop = 100 };
Console.WriteLine("Reversed: " + string.Join(", ",
    index.SearchBy(reverse).Select(h => h.Id)));

The added output is:

Text
Reversed: reverse

Full-text search · Boolean queries · Query JSON · Sparse vectors


The short answer

Use PhraseQuery(field, terms) with Slop = 0 for an exact adjacent phrase. Increase Slop to allow gaps while retaining word order. The full program shows that “quick brown” matches the exact document at zero, adds “quick red brown” at one and still excludes “brown quick” at 100. Slop never enables transposition.

What does proximity search mean?

Proximity search selects words by their positions, not just whether both occur somewhere in a document. In OneIndex’s phrase query, the terms must appear in their listed order at strictly increasing positions. This makes the query appropriate for an ordered expression that may contain intervening words.

A Boolean AND asks a different question: it requires both terms but does not constrain their distance or order. An exact phrase is narrower still: it requires adjacency in the indexed positions. Decide whether the user means “both words,” “these words in this order nearby,” or “this exact sequence” before choosing the query.

The phrase semantics define the gap as the last position minus the first position minus the number of terms less one. For two query terms at positions zero and two, the gap is one. A match qualifies when that gap is at most Slop. For longer phrases, the gap measures the whole chain’s extra positions, not a separate allowance for every pair.

How do I do a proximity search in C#?

Index a full-text field with positions, commit, then send a PhraseQuery through SearchBy. The [FullText] field in this example supports the position lookup. If you use a custom schema, retain Positions or Offsets; a field indexed without positions causes QueryException, not a no-match result.

The query object takes already-analyzed terms. The example deliberately uses simple lowercase words that agree with the field’s analysis. For real text, choose an analyzer and ensure query terms use its vocabulary. Stemming and skipped positions can change what counts as a phrase; matching indexed tokens is not the same as comparing raw source substrings.

In the full program, every document and its content are inline. IDs are sorted for readable output, not to show score order. The first query tests adjacency. The second permits one gap. The third demonstrates that a large gap budget cannot change word order. The reverse-query variation proves the converse: searching for brown before quick selects only the reversed document.

What are examples of exact phrase and proximity searches?

Exact phrase search is the zero-gap case of this ordered phrase query. It does not mean a byte-for-byte comparison of the whole field: a longer field can contain the phrase, and the field analyzer determines the indexed terms. If you need equality on a complete literal value, a keyword field is a different choice.

Nonzero slop expands eligible chains but also affects their phrase frequency. Each qualifying chain contributes 1 / (1 + gap); the engine sums those contributions and scores the resulting phrase frequency. A permitted wider gap therefore does not contribute the same phrase frequency as adjacency. It is not a hard-coded score of one per matching document.

Repeated terms are allowed, but each must advance to a later position. Two tokens stacked at the same position cannot satisfy two successive query terms. A single-term phrase behaves as a term query; an empty terms list matches nothing. Keep these rules in mind when building phrases programmatically, especially when analysis can remove words or emit alternatives. The gap and ordering rules remain the same even when a larger Slop makes more documents eligible.

All oneindex recipes