---
title: "Publish a read-only static search index in C#"
url: https://recursiveai.org/oneindex/cookbook/publish-read-only-static-search-index/
description: "Build a read-only static search index in C# with OneIndex, export immutable chunks, and query a local publication without a search server."
version: "0.4.0-preview.2"
---

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

[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/publish-read-only-static-search-index/publish-read-only-static-search-index.zip)

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

```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 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](https://recursiveai.org/oneindex/cookbook/publish-read-only-static-search-index/publish-read-only-static-search-index.zip), then `dotnet run`.

## Variations

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

```csharp
var hits = await index.QueryAsync(
    i => i.Search("owl").Execute());
```

```text
owl: night owl
```

## Related recipes

- [Search multiple vectors per document in C#](https://recursiveai.org/oneindex/cookbook/search-with-multiple-vectors-per-document/)
- [Customize search ranking rules in C#](https://recursiveai.org/oneindex/cookbook/customize-search-ranking-rules/)

## 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](https://recursiveai.org/oneindex/docs/static-index/) 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](https://recursiveai.org/oneindex/docs/static-index/) explains how those candidates are selected.
