Sperone.Client 0.1.37

Sperone.Client

The official .NET SDK for Sperone — the multi-modal data server. Scalar, geospatial, vector and full-text indexes in a single engine, behind one clean, strongly-typed, MongoDB-style client.

Why Sperone.Client?

• One database, every kind of search. Filter by scalar ranges, search by geolocation (radius, bounding box, nearest), rank by vector similarity (k-NN) and by full-text relevance (BM25, with optional hybrid semantic re-ranking) — all in the same collection, in the same query.
• The query is the plan. A fluent, MongoDB-style builder where the chain you write is exactly how the engine executes it — no hidden reordering, no surprises.
• Strongly typed, zero JSON by hand. Pass your own POCOs and a source-generated JsonTypeInfo<T>; the client serializes, indexes and deserializes for you.
• AOT- and trim-friendly. Serialization flows through your [JsonSerializable] context — no hidden reflection — so it plays nicely with Native AOT and trimming.
• Featherweight. A pure client: no dependency on the storage engine (no FASTER, no ONNX). Just mirrored DTOs and HttpClient.
• Built-in time travel & backups. Snapshot a collection (or just its indexes), roll back to any version, and export/import logical backups as portable .sperone files.
• Multi-database & permission-aware. Talk to many databases through one client, with per-collection Create/Read/Modify permissions.

Install

dotnet add package Sperone.Client

Connect

The fastest path is a connection string — base address, database and credentials in one line:

using Sperone.Client;

// scheme://host:port/database@username:password
var client = new SperoneClient("https://localhost:60885/geo@admin:hunter2");

ISperoneClient db = await client.ConnectAsync();   // logs in and points at database "geo"

Prefer to be explicit? Wire it up by hand:

var client = new SperoneClient(new Uri("https://localhost:60885"));
await client.LoginAsync("admin", "hunter2");
ISperoneClient db = client.Database("geo");

The model: Client → Database → Collection

A familiar three-level hierarchy. The client authenticates and manages databases; a database view manages collections; a collection view is where you work with documents, queries, indexes and versions.

ISperoneCollection places = db.Collection("places");

Store & read documents (typed)

Bring your own model and a source-generated JSON context — the typed overloads do the rest, pairing the payload with a fluent, lambda-based index spec:

record Place(string Name, double Rating, GeoPoint Position, string Description);

var places = db.Collection("places");

await places.InsertAsync("rome-01", new Place("Trattoria", 4.6, new GeoPoint(41.9028, 12.4964), "cozy rooftop terrace"),
    AppJson.Default.Place,                       // your JsonTypeInfo<Place>
    IndexSpec.For<Place>()
        .Scalar(x => x.Rating)
        .Geo(x => x.Position)
        .FullText(x => x.Description));

Place? back = await places.GetAsync("rome-01", AppJson.Default.Place);

Working with raw bytes instead? The core API speaks byte[], and the non-generic IndexSpec lets you name indexes explicitly (handy under Native AOT):

await places.InsertAsync("rome-01", payload,
    IndexSpec.Create()
        .Scalar("rating", 4.6)
        .Geo("position", 41.9028, 12.4964)
        .FullText("description", "cozy rooftop terrace"));

Query across every index

Compose one chain that mixes full-text relevance, scalar filters and geospatial conditions. The first step is the generator (it drives the result order); the later steps refine it in AND / AND NOT:

IReadOnlyList<string> ids = await places.QueryAsync(
    Query.On("places")
        .Where(Clause.FullText("description", "rooftop terrace"))      // rank by relevance
        .And(Clause.Scalar("rating").GreaterThanOrEqual(4))            // keep the good ones
        .And(Clause.GeoRadius("position", 41.9028, 12.4964, meters: 2000)) // within 2 km
        .Take(10));

Need a plain vector k-NN? There's a one-liner for that:

var similar = await places.SearchVectorAsync("embedding", queryVector, take: 5);

Configuration

For anything beyond a connection string — request timeout, a pre-obtained bearer token, or a self-signed certificate on a local dev server — use SperoneClientOptions:

var options = SperoneClientOptions.FromConnectionString("https://localhost:60885/geo@admin:hunter2");
options.Timeout = TimeSpan.FromSeconds(30);
options.AcceptAnyServerCertificate = true;   // local dev over https://localhost — never in production

ISperoneClient db = await new SperoneClient(options).ConnectAsync();

Versions & backups

var v = await places.TakeVersionAsync();          // snapshot the whole collection
await places.RestoreVersionAsync(v.Id);           // …and roll back to it later

byte[] backup = await places.ExportAsync();        // portable .sperone logical backup
await db.ImportCollectionAsync(backup);            // restore it here (or in another database)

A note on scope

The client's public surface is data only — collections, documents, queries, indexes, versions and backups. Server installation, environment and user administration live in the Sperone management tools, not in this SDK, keeping the client small and focused.

Errors

"Normal" outcomes are not exceptions: a missing item is null, a conflict is false. Only the unexpected ones (401, 423, 5xx, …) surface as SperoneApiException, carrying the HTTP status code.

License

The client SDK is free and open source under AGPL-3.0-or-later. The Sperone server (engine, API, UI) is proprietary and licensed separately — see LICENSING.md.