---
title: "Search with sparse vectors in C#"
url: https://recursiveai.org/oneindex/cookbook/search-with-sparse-vectors/
description: "Indexes explicit token weights and prints scores you can calculate by hand."
version: "0.4.0-preview.2"
---

# Search with sparse vectors 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-sparse-vectors/search-with-sparse-vectors.zip)

Sparse search scores shared token weights by dot product, here without a model.

For encoder-generated weights, see the [sparse encoder docs](https://recursiveai.org/oneindex/docs/sparse/) for `ISparseEncoder` and `[Sparse(From = ...)]`.

```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.Index;
using OneIndex.Search;
using var index =
    SearchIndex.InMemory<Note>();
index.Upsert(new Note {
    Weights = new([new("apple", 2f)]) });
index.Commit();
var query = new SparseQuery("Weights",
    new SparseVector([new("apple", 1f)]));
var hit = index.SearchBy(query).First();
Console.WriteLine(hit.Score);
public class Note
{
    [SearchId]
    public string Id { get; set; } = "a";
    [Sparse]
    public SparseVector? Weights
        { get; set; }
}
```

```text
2
```

Unzip [the example](https://recursiveai.org/oneindex/cookbook/search-with-sparse-vectors/search-with-sparse-vectors.zip), then `dotnet run`.

## The full program

The program searches three documents with explicit apple, red, green and ocean weights. 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.

```csharp
using OneIndex;
using OneIndex.Index;
using OneIndex.Search;
using var index = SearchIndex.InMemory<Note>();
index.Upsert([
    new() { Id = "a", Weights = new([new("apple", 2f), new("red", 1f)]) },
    new() { Id = "b", Weights = new([new("apple", 1f), new("green", 3f)]) },
    new() { Id = "c", Weights = new([new("ocean", 4f)]) }
]);
index.Commit();
var query = new SparseQuery("Weights",
    new SparseVector([new("apple", 1f), new("red", 2f)]));
foreach (var hit in index.SearchBy(query))
    Console.WriteLine($"{hit.Id}: {hit.Score:0.000}");
public class Note
{
    [SearchId] public string Id { get; set; } = "";
    [Sparse] public SparseVector? Weights { get; set; }
}
```

`dotnet run` prints:

```text
a: 4.000
b: 1.000
```

`SparseVector` accepts finite, non-negative weights; invalid weights are rejected.

## Variations

Search the same field through query JSON. Insert this before the full program’s `Note` class:

```csharp
var jsonHits = index.Parse("""
    {"v":1,"query":{"type":"sparse","field":"Weights",
    "weights":{"green":1}}}
    """);
foreach (var hit in jsonHits)
    Console.WriteLine($"Green: {hit.Id}: {hit.Score:0.000}");
```

The added output is:

```text
Green: b: 3.000
```

## Related recipes

[Full-text search](https://recursiveai.org/oneindex/cookbook/full-text-search-csharp/) · [Boolean queries](https://recursiveai.org/oneindex/cookbook/parse-boolean-search-query/) · [Query JSON](https://recursiveai.org/oneindex/cookbook/run-search-query-from-json/) · [Phrase search](https://recursiveai.org/oneindex/cookbook/search-exact-phrases-with-slop/)

---

## The short answer

Store a `SparseVector` on a `[Sparse]` property, then use `SparseQuery` with the same field and a query vector. OneIndex scores the shared tokens using a dot product over quantized document weights. The example uses explicit, hand-written weights; it does not run a learned encoder or download model files.

## What does sparse vector mean?

A sparse vector records only the tokens with nonzero weights instead of storing an entry for every possible feature. In this API the dimensions are token strings. “apple” in one document aligns with “apple” in the query; a different token contributes nothing to that overlap.

`SparseVector` keeps unique tokens in ordinal order, drops zero weights and requires finite, non-negative weights. If a token occurs more than once in its input, the larger weight is retained rather than added. The [sparse reference](https://recursiveai.org/oneindex/docs/sparse/) caps a vector at 65,536 entries. The field is single-valued, and its vector is stored with the document.

Pick token identities and weighting rules that mean the same thing at index time and query time. The API does not turn these arbitrary hand-written strings into semantic features. A token named “apple” will not automatically match another named “fruit.” An encoder can produce expanded features, but the example intentionally separates the mechanics of sparse search from that encoding choice.

## How do I search sparse vectors in C#?

The full program inserts three documents and commits before searching. Document a has apple weight 2 and red weight 1. Document b has apple weight 1 and green weight 3. Document c only has ocean weight 4. The query has apple weight 1 and red weight 2.

For a, the shared-token sum is `2 × 1 + 1 × 2 = 4`. For b, only apple overlaps, giving `1 × 1 = 1`. Document c shares no token, so it is not a hit. The printed scores match these calculations. The integer weights were chosen so the document-side quantization does not alter this example’s arithmetic.

In general, document weights are stored as rounded multiples of `1 / 128`. Tokens whose quantized weight is zero are not indexed. Query scoring sums `frequency × queryWeight × boost / 128` over shared tokens. Do not assume an arbitrary decimal input produces a bit-for-bit unquantized dot product. This distinction matters if you compare a score with a separate calculation over the original floats.

## Can I send a sparse vector search as JSON?

Yes. The variation uses a versioned request with a `sparse` query node, a field name and a `weights` object. It searches green alone and returns b with score 3. The JSON and direct query-object paths address the same indexed sparse field; neither requires text embedding.

Use a direct `SparseQuery` when your C# application already owns the weights. Use query JSON when another component supplies the query as data and you want schema-aware parsing. A field name still has to refer to an appropriate searchable field.

For automatic encoding, the library separately documents `ISparseEncoder` and `[Sparse(From = ...)]`, as well as text search with `.Sparse()`. Those need a configured sparse encoder. Plain `Search(text)` does not silently add the sparse arm. Combining text and sparse result lists is hybrid search with fusion rules, not this page’s direct weighted-token dot product. Keep the direct path when you need to inspect exactly which supplied tokens contribute to the score.
