Recursive AI

Publish a read-only static search index in C#

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

Export immutable search files for a static host, then query them locally.

Terminal
dotnet add package RecursiveAI.OneIndex --prerelease

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

C#
using OneIndex;
using OneIndex.StaticIndexes;
 
using (var writer =
    SearchIndex.Open<Page>("source-index"))
{
    writer.Upsert([
        new() { Id = "fox",
            Text = "red fox" },
        new() { Id = "owl",
            Text = "night owl" }
    ]);
    writer.Commit();
}
StaticIndexBuilder.Build<Page>(
    "source-index", "published-search");
var index =
    await StaticIndex.OpenAsync<Page>(
    new DirectoryStaticSource(
        "published-search"));
var hits = await index.QueryAsync(
    i => i.Search("fox").Execute());
foreach (var hit in hits)
    Console.WriteLine(
        $"{hit.Id}: {hit.Document.Text}");
 
public class Page
{
    [SearchId]
    public string Id { get; set; } = "";
    [FullText]
    public string Text { get; set; } = "";
}
Text
fox: red fox

Before rerunning, delete the published-search output folder. The build refuses to overwrite an existing static publication with IOException.

The download pins OneIndex to 0.4.0-preview.2; the package’s source generator builds the mapping from the attributed class.

The build destination must be empty: an existing static publication raises IOException; a fetched chunk with the wrong checksum raises CorruptIndexException.

Writes published-search/static.json and its search chunks.

Unzip the example, then dotnet run.

Variations

Query a different word in the exported snapshot. Replace the var hits statement in the snippet at the top:

C#
var hits = await index.QueryAsync(
    i => i.Search("owl").Execute());
Text
owl: night owl

The short answer

Commit an ordinary OneIndex directory, then call StaticIndexBuilder.Build<T> to write its newest commit as immutable chunks plus static.json. Open the published directory with StaticIndex.OpenAsync<T> and run searches through QueryAsync. The sample uses a local directory source, so it needs neither a web server nor an internet connection.

How do you build a static site search index in C#?

Start with the content you want searchable. The full program uses two original strings, “red fox” and “night owl”, rather than crawling a website. [FullText] identifies the searchable text; [SearchId] supplies a stable document identifier. The NuGet package’s source generator creates the mapping at build time from these attributes.

The source directory and the publication directory have different jobs. source-index is the writable index. published-search is the artifact you distribute. The static builder uses the newest committed state, not pending writes. Commit before building, and build from a freshly committed or merged index as the static-index docs recommend: unreferenced segment files from an unmerged index can otherwise come along.

The output directory contains a manifest and the index files, split into chunks where needed. Publish the whole directory together. Copying only static.json, or only the largest data file, does not produce a usable index. The builder refuses to overwrite an existing static publication. To rerun the sample, use a fresh working directory or change published-search to a new empty destination in both calls.

How do you search a static index without a search server?

The sample opens DirectoryStaticSource and searches the exported files, not the writable source index. Its single hit demonstrates that the exported snapshot can answer a text query. For an HTTP deployment, OneIndex provides HttpStaticSource, which accepts an HttpClient and the directory’s base URI. Chunks use whole-object GETs; the host does not need byte-range support or application code to evaluate queries.

A static index is not a complete website search interface. A browser application still needs to run the search client and display the returned documents. Keep the data model and search client compatible with the bundle you publish. This recipe covers building and reading the artifact in .NET, not wiring a browser input field.

QueryAsync may run its delegate again while fetching missing chunks. Materialize the results inside the delegate with Execute or ToList, and keep the delegate repeatable. Do not put unrelated writes, notifications or counters in it. The final query sees the required cached chunks and returns the materialized results.

Can a read-only static search index be updated?

Update the writable source, commit it, and build a new publication. The static reader is not a writer and cannot apply Upsert to the published snapshot. Treat each publication as a unit rather than editing a chunk in place. A versioned publication directory lets you keep the old files intact while distributing the new bundle.

The manifest records chunk checksums. Every fetched chunk is checked against its CRC-32C before use; a mismatch raises CorruptIndexException. Invalid manifests and unavailable or short files also fail rather than becoming partial search results. These checks detect corruption relative to the manifest; they are not a signature that authenticates its publisher. Distribute the manifest and chunks through the same trusted publication path.

For ordinary text queries, the docs say results equal the same query on the source index, including identifiers and scores. Do not extend that statement to every search mode: static hybrid search selects its candidate documents differently from the source index, so its results are not promised to be identical. The static-index documentation explains how those candidates are selected.

All oneindex recipes