Inputs and Outputs

Sub-byte types pack several dimensions per byte, as their xN suffixes spell.

An input's row count is the call's count, and the call checks columns against the frozen geometry. A zero stride repeats the first row. An output's rows are packed: the call writes one row's bytes as stride, and columns and scalar as it wrote them, so neither a repeat nor a geometry check applies.

rows and columns are counts and stride alone is in bytes. A zero stride repeats the first row.

Entry i spans elements offsets[i] up to offsets[i+1], so the last offset closes the final entry. What an element is belongs to the modality: a byte of a sequence, a point of a shape or of a geospatial set. As an output the call writes 32-bit offsets while its elements fit them, and 64-bit beyond.

Carries no query count of its own: the call already fixed it, and a second copy is a second thing to disagree. Query i holds counts[i] matches from keys[i · columns] and scores[i · columns] on, and the columns past them are unwritten.

What scores hold is each verb's own: a search writes distances nearest-first, whichever kind the index froze - the inner kind as 1 - dot - while the linear-algebra verbs write similarities, as their own docs state.

Query i spans offsets[i] up to offsets[i+1] in both arrays, so the last offset is the total. Scores follow the same per-verb meaning as in usearch_matches_view_t.

Passing NULL skips reporting.

Memory

Made by usearch_arena_init where its executor computes: host pages on its memory domains, or the memory of its GPU, and a GPU that runs out reports usearch_status_out_of_memory_k rather than falling back to the host. Each call given the arena rewinds it, which invalidates every output of the previous call, and refills it, growing only when the new outputs outsize everything it held, so a steady loop allocates once. To keep one call's outputs alive past the next call, pass the next call another arena.

• A NULL arena is refused with usearch_status_invalid_argument_k.
• A call whose inputs point into the arena it is about to rewind reports usearch_status_invalid_argument_k.
• An arena serves one call at a time; a second call naming it finishes usearch_status_contended_k, and a deferred one does so at submission.
• A call on another residency or device than the arena's, or a call naming a GPU arena with another executor than the one that made it, NULL included, reports usearch_status_device_k.
• A blocking call borrows the arena until it returns, and a deferred one holds it until final.
• A call that fails, is cancelled, or has nothing to report leaves its outputs NULL.

A null_count of -1 with a validity buffer may hold a null, and is refused as one.

The array pins arena until its release: meanwhile a call naming the arena is refused with usearch_status_contended_k, and usearch_arena_free leaves the arena to the last release. Arenas on host pages export as ARROW_DEVICE_CPU, and those of a VRAM executor as ARROW_DEVICE_CUDA, ARROW_DEVICE_ROCM or ARROW_DEVICE_METAL with the vendor's ordinal of their device and no sync_event, as the call that filled one drained its uploads. The schema's name is empty, for the caller to point at its own. Schema and array release apart, and a consumer may move their children out before either release.

A list length comes from the tape's last offset, which crosses from a device arena through its driver. Shape points asked for in u8 read as binary, whose offsets are bytes, so ask a shapes get for another scalar before exporting it.

Keys, scores and sizes stay in place. The view's offsets are written behind the call's outputs in arena under the arena's hold, so no other call or carving export runs on arena meanwhile, and a device arena's reach its device on the first stream of the executor that made the arena.

Overlaps safely with concurrent searches on the same handle. Concurrency & Thread Safety

An insertion is all-or-nothing per call, with or without a handler, and its entries become visible at once on RAM and VRAM handles alike, so a concurrent search sees every entry of the call or none of them. Every entry is claimed before the handler's first report, and a claimed entry cannot be withdrawn, so the handler reports progress but cannot cancel: a returned usearch_cancel_k is ignored.

On a RAM handle every fallible step runs before the first entry identity is claimed, so a failed call leaves the index untouched. A VRAM call that fails after its first launch publishes none of its entries and leaves the handle refusing every later mutation with that failure, while searches continue.

usearch_outcome_t outcome = {0};
usearch_dense_insert(&(usearch_dense_insert_t){
    .index = index, .executor = executor, .outcome = &outcome,
    .count = 256, .keys = {keys, sizeof(usearch_key_t)},
    .vectors = {rows_base, 128 * sizeof(float), 128, usearch_scalar_f32_k}});
if (outcome.status != usearch_status_success_k) report(outcome.message);

One query is a count of one. Never writes to the index, so any number may overlap with insertions. Concurrency & Thread Safety

A scan walks no graph. On RAM the queries split into blocks, each taken by one of the executor's threads: a block of many queries packs once into the operand layout of the CPU's matrix kernels and streams every stored vector against the pack where it lies, while a lone query takes the walk's own 4-way kernels. On NVMe the queries pack once and the threads split the value column instead, each run written beside its keys, so the column is read once and in order. Either way each query's matches merge into its output row as the pass advances. On NVIDIA VRAM the batch scans every shard's vectors on the device, where the shards' matches merge too. Every residency ranks by the distances its walk reports. A predicate is asked only about entries closer than the worst match the query already holds, which makes the scan the fallback for predicates too selective for a walk to cross.

A predicate narrows the matches to the entries it admits. Non-matching entries still route the traversal rather than terminating it, so recall does not collapse at low selectivity - the walk crosses rejected regions to reach admitted ones behind them. The cost is that the predicate judges far more keys than wanted, every scored candidate, asked about a quad of them at a time, so it belongs on the caller's fast path - and it is invoked concurrently from the executor's threads, so it must tolerate that.

hints hand each query's walk landmarks the caller already trusts, such as the matches of the same queries over another index of the same keys. A query takes as many keys as a walk draws landmarks, the connectivity rounded up to a multiple of four, and ignores the rest; the entries stored under them take the landmark slots ahead of the random draws, in hint order, as many as fit. They are advisory, so a key no entry holds is skipped and counted in missing_hints. An NVMe view resolves them through its key table, confirming each entry with one key read.

A cancelled search reports usearch_status_cancelled_k and leaves matches NULL, since a query resolved before the stop is indistinguishable from one that never ran. A zero wanted, or an index holding no entries, succeeds without walking and writes only the counts, every one zero.

static void admits_tenant(usearch_key_t const* keys, usearch_admission_t* admissions, size_t count, void* state) {
    for (size_t i = 0; i != count; ++i)
        admissions[i] = keys[i].bytes[0] == *(uint8_t const*)state ? usearch_admit_k : usearch_reject_k;
}

uint8_t tenant = 7;
usearch_matches_view_t matches;
usearch_outcome_t outcome = {0};
usearch_dense_search(&(usearch_dense_search_t){
    .index = index, .executor = executor, .outcome = &outcome,
    .count = 32, .queries = {rows_base, 256 * sizeof(float), 256, usearch_scalar_f32_k},
    .matches = &matches, .arena = arena, .wanted = 10,
    .predicate = {admits_tenant, &tenant}});
// Query 3's nearest key, valid until the next call given arena.
usearch_key_t nearest = matches.keys[3 * matches.columns];

An observation without an altitude is placed on the handle's terrain when it has one, and on the ellipsoid otherwise.

An insertion is all-or-nothing per call. Every fallible step runs before the first entry identity is claimed, so a rejected call publishes nothing - a cancelled one included, which reports usearch_status_cancelled_k - and on a RAM handle the entries of an accepted one become visible at once, their keys right after.

A key already holding values_per_key entries rejects the whole call, since a smaller retry cannot help.

Scores are chord metres between the two positions, altitude included. The relation, the time window and the predicate narrow the walk's candidates, so a selective one wants a wider expansion_factor, and a query may hold fewer than wanted matches.

A predicate narrows the matches to the entries it admits. Non-matching entries still route the traversal, so recall does not collapse at low selectivity.

A cancelled search reports usearch_status_cancelled_k and leaves matches NULL.

Complete on the converged graph: the walk widens its candidates by the cone graph's spanner bound before trusting it, so every candidate inside the tolerance is enumerated, at about thirty times the cost of the ball it reports. Containment sizes its own candidates from that bound, so it takes no breadth a caller could make the report incomplete with. Only the walks learn how large the report is, so the keys, scores and Apache Arrow offsets are written in arena as one ragged output, as usearch_dense_multiply writes its pairs. A predicate narrows the report without stopping the walk from crossing the entries it rejects.

A cancelled call reports usearch_status_cancelled_k and leaves the outputs NULL.

An insertion is all-or-nothing per call. Every fallible step runs before the first entry identity is claimed, so a rejected call publishes nothing - a cancelled one included, which reports usearch_status_cancelled_k - and the entries of an accepted one become visible at once, their keys right after.

A key already holding values_per_key entries rejects the whole call, since a smaller retry cannot help.

The native batch operation, parallelized internally. Never writes to the graph, so any number may overlap with concurrent insertions. Concurrency & Thread Safety

A predicate narrows the matches to the entries it admits. Non-matching entries still route the traversal rather than terminating it, so recall does not collapse at low selectivity - the walk crosses rejected regions to reach admitted ones behind them. The cost is that the predicate judges far more keys than wanted, every scored candidate, asked about a batch of them at a time, so it belongs on the caller's fast path.

A cancelled search reports usearch_status_cancelled_k and leaves matches NULL.

Point counts may differ freely between entries. Overlaps safely with concurrent searches on the same handle. Concurrency & Thread Safety

An insertion is all-or-nothing per call. Every fallible step runs before the first entry identity is claimed, so a rejected call publishes nothing - a cancelled one included, which reports usearch_status_cancelled_k - and on a RAM handle the entries of an accepted one become visible at once.

A key already holding values_per_key entries rejects the whole call, since a smaller retry cannot help.

The native batch operation, parallelized internally. Query point counts are unconstrained and need not match any indexed entry. Never writes to the graph, so any number may overlap with concurrent insertions. Concurrency & Thread Safety

A predicate narrows the matches to the entries it admits. Non-matching entries still route the traversal, so recall does not collapse at low selectivity. hints hand each query's walk landmarks the caller already trusts, such as the matches of the same keys in a cheaper index.

A cancelled search reports usearch_status_cancelled_k and leaves matches NULL.

Nothing is allocated until a call writes into it. An arena of host pages may outlive the executor that made it, keeping its own memory until it is freed; a GPU arena keeps the rule usearch_arena_t notes.

Waits until every deferred call naming the handle is final, and leaves the arena to the last release of the Arrow exports still pinning it. Free a GPU arena once the caller's own device work on its outputs has finished, keeping the rule usearch_arena_t notes.