Inputs and Outputs

§ Arenas

Every output whose length only the call knows, such as matches, rows, products, monoliths and cursor or stream batches, lands in an Arena you pass, and the verb answers a view over it without copying. Arena.init(executor) places it where that executor computes, decided once, and Arena.init(null) makes host pages for the calling thread. Each call rewinds its arena and grows it only past its high-water mark, so the previous call’s views die and a steady loop allocates once. To keep a result past the next call, or to read one while making the next, pass that call another arena. An arena serves one call at a time, so each deferred call needs its own. Views find their arena by address, so it must not move while they live, and a stale view answers Error.Uninitialized; slices an accessor already returned are not checked again. An arena from a VRAM executor holds device memory, which host accessors refuse with Error.Device. It grows and frees on that executor’s stream, so it serves only calls on that executor, any other answering Error.Device, and is freed before it; host pages may outlive theirs.

var arena = try usearch.Arena.init(executor); // `Arena.init(null)` is host pages for the calling thread
defer arena.deinit();
for (batches) |batch| {
    const matches = try index.on(executor).search(batch, 10, &arena, .{}); // rewinds: the last batch's matches are gone
    total += (try matches.query(0)).scores[0];
}

var found = try usearch.Arena.init(null); // two live results, two arenas
defer found.deinit();
var fetched = try usearch.Arena.init(null);
defer fetched.deinit();
const nearest = try index.search(query, 10, &found, .{});
for ((try nearest.query(0)).keys) |key| rerank(key, try index.get(key, .f32, &fetched));

var calls: [shards.len]usearch.Deferred(usearch.DenseSearch) = undefined;
for (&calls, shards, executors, &arenas) |*call, shard, pool, *own|
    try shard.deferred(pool, call).search(queries, 10, own, .{}); // one executor and one arena per submitted call
defer for (&calls) |*call| call.deinit();
for (&calls) |*call| consume(try call.wait());

A call that finds its arena serving another call finishes with Error.Contended and rewinds nothing, so the holder’s views stay readable. A call that fails for any other reason still rewinds it. Only fixed-size reports like DenseTraversalStats stay your fields.

§ Rows & Scalars

Every batch input is a run of rows given by a base pointer, a row count, a column count, and a byte stride, so a memory-mapped dataset feeds the index with no reshape and no copy. The scalar type of the input is independent of the stored quantization, so the f32 slab of the Quickstart lands in an i8 index and nothing needs converting before insertion. RowsView.of reads a packed slab; a dataset whose rows are padded to a wider pitch fills the struct directly, setting stride to the pitch; a zero stride repeats the first row for every one of them. The encodings Zig has no primitive for, usearch.Scalar.BF16, E5M2, E4M3, E3M2, E2M3, and the packed I4x2, U4x2 and U1x8, travel as their raw bits, and a packed kind counts columns in dimensions, so 128 dimensions of Scalar.U1x8 take sixteen values a row. Lengths that cannot be read as a whole number of rows are refused with Error.ShapeMismatch rather than asserted, so the check survives ReleaseFast. The column count travels with the rows, and the engine refuses one that differs from the frozen geometry with the same error.

Every metric derives from a single inner-product kernel with pre-computed magnitudes.

• .inner: inner product, and the only kind the linear-algebra verbs accept.
• .angular: cosine distance, over pre-computed magnitudes.
• .euclidean: L2 distance.
• .hamming: bit-level, over .u1x8 vectors alone.
• .jaccard: bit-level, over .u1x8 vectors alone.

Arbitrary metrics belong to the C++ baseline tier; the C interface, and so this module, takes the built-in kinds alone.

§ Search

Every verb has one entry point, its optional knobs riding one config struct named after its C argument structure, such as DenseSearchConfig, DenseInsertConfig or DenseMultiplyConfig.

var arena = try usearch.Arena.init(executor);
defer arena.deinit();
var stats: usearch.DenseTraversalStats = .{};

const matches = try index.on(executor).search(try .of(f32, queries, 768), 10, &arena, .{
    .expansion_factor = 128,
    .stats = &stats,
});
for (0..matches.queries) |query| consume(try matches.query(query));
std.debug.print("{d} distances computed\n", .{stats.computed_distances});

Matches.query answers one query’s keys and distances, nearest first, as many as the walk found up to the “k” asked for.

The breadth of the candidates rides the call rather than the handle, so a recall sweep is a loop over expansion factors against one immutable index, with no mutation and no synchronization between points. .traversal = .scan scores every entry instead of walking, on RAM and NVMe handles, which gives that sweep its exact ground truth; a VRAM handle answers it with Error.Unsupported.