Sparse search scores shared token weights by dot product, here without a model.
For encoder-generated weights, see the sparse encoder docs for ISparseEncoder and [Sparse(From = ...)].
dotnet add package RecursiveAI.OneIndex --prereleaseRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
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; } }
2Unzip the example, 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.
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:
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:
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:
Green: b: 3.000Related recipes
Full-text search · Boolean queries · Query JSON · Phrase search
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 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.