Recursive AI

Filter search by nested JSON fields in C#

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

Use Path("customer.age") to filter JSON without declaring every key.

Terminal
dotnet add package RecursiveAI.OneIndex --prerelease

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

C#
using System.Text.Json;
using OneIndex;
using var index =
    SearchIndex.InMemory<Ticket>();
using var json = JsonDocument.Parse(
    """{"customer":{"age":24}}""");
index.Upsert(new Ticket
    { Data = json.RootElement });
index.Commit();
var found = index.Search().Where(ticket =>
    ticket.Data.Path("customer.age") >= 18);
foreach (var hit in found)
    Console.WriteLine(hit.Id);
 
public class Ticket
{
    [SearchId]
    public string Id { get; set; } = "adult";
    [Dynamic]
    public JsonElement Data { get; set; }
}

Unzip the example, then dotnet run.

Text
adult

The ticket matches because the nested age is the number 24. The NuGet package includes the source generator that maps Ticket from its attributes; no separate package or generated class is needed.

The full program

The download uses four tickets to show what happens when only the age matches, only the tag matches, or the age is missing.

C#
using System.Text.Json;
using OneIndex;
 
using var index = SearchIndex.InMemory<Ticket>();
Add("A", """{"customer":{"age":24},"tags":["blue","red"]}""");
Add("B", """{"customer":{"age":16},"tags":["red"]}""");
Add("C", """{"customer":{"age":30},"tags":["blue"]}""");
Add("D", """{"customer":{},"tags":["red"]}""");
index.Commit();
 
var matching = index.Search().Where(ticket =>
    ticket.Data.Path("customer.age") >= 18 &&
    ticket.Data.Path("tags") == "red");
Console.WriteLine("Adult and red: " +
    string.Join(", ", matching.Select(hit => hit.Id)));
 
void Add(string id, string text)
{
    using var json = JsonDocument.Parse(text);
    index.Upsert(new Ticket { Id = id, Data = json.RootElement.Clone() });
}
 
public class Ticket
{
    [SearchId] public string Id { get; set; } = "";
    [Dynamic] public JsonElement Data { get; set; }
}
Text
Adult and red: A

If you dispose the JsonDocument before the index writes it, Commit() can throw ObjectDisposedException; clone the root as the full program does when the parser is scoped to a helper.

Variations

Replace the matching assignment in the full program with either of these filters.

Find tickets with an age at all. Exists() checks for an indexed value, not whether the raw JSON contains a key with a null value. With the full program’s input, the filter matches A, B, and C.

C#
var matching = index.Search().Where(ticket =>
    ticket.Data.Path("customer.age").Exists());

Use a filter string. Include the property name (Data) before the JSON path. This matches A, just as the C# predicate does.

C#
var matching = index.Search().Where(
    "Data.customer.age >= 18 AND Data.tags = red");

The short answer

Mark a JsonElement property with [Dynamic], upsert the document, and call Commit(). In a search filter, call Path("customer.age") on that property and compare it to a number. The original JSON comes back with the hit, but OneIndex matches against indexed leaf values: the strings, numbers, and booleans at the ends of the paths. You don’t have to add a C# property each time a new metadata key appears.

How do you filter nested JSON fields by path in C#?

Start at the root of the JsonElement and join object keys with dots. For {"customer":{"age":24}}, the path inside Data.Path(...) is customer.age, not Data.customer.age or $.customer.age. A filter string uses the full name Data.customer.age because it has no C# member expression to identify Data. If a key contains a literal dot, escape it as \. in the path (in a regular C# string that’s \\.).

This is a search filter over committed documents, not a general JSONPath evaluator that returns matching nodes from one payload. Use a declared [FullText] property for words you want analyzed: a dynamic string such as "red jacket" is indexed as one keyword, not separate words. See the dynamic JSON field reference for the path and type rules.

How do filters work on nested JSON arrays?

Array positions don’t appear in a path. In {"tags":["blue","red"]}, tags has two values; equality to red succeeds because one of them matches. The same rule applies to arrays of objects: {"items":[{"sku":"x"},{"sku":"y"}]} gives items.sku the values x and y. You don’t put an array offset inside Path().

That also means two conditions on an array don’t require the same object to satisfy both. For items [{"sku":"x","qty":1},{"sku":"y","qty":5}], a filter for SKU x and quantity at least 5 can match the document: the conditions are satisfied by different items. If both must describe the same item, index each item as its own document with the parent ID as a separate field.

What if a nested JSON field is missing, null, or the wrong type?

The numeric range in the recipe doesn’t match a missing age, null, or the string "24". OneIndex treats those first two cases as having no age value and the third as having a string value rather than a number. A negative test is different: != is the complement of equality, so it can include documents without that path. Don’t use “not equal” by itself as a test for presence.

The stored JSON can also contain values that aren’t searchable. For example, a root scalar has no path, and a string longer than the default 1,024-byte keyword ceiling is left in the stored JSON but not added to the keyword index. Numbers are indexed as 64-bit floating-point values, so if large integer IDs must compare exactly, store them as JSON strings or use a declared field of the appropriate type.

All oneindex recipes