Retrieval and Streaming

get lands every vector stored under a key in the arena, one packed row per entry in insertion order, as the scalar you name; an absent key yields no rows.

const vectors = try index.get(key, .f32, &arena);
for (0..vectors.rows) |row| consume(try vectors.row(f32, row));

DenseVectors.stride is the byte pitch of each row and columns its dimensions, as the call reported them, which is how a sub-byte kind like .u1x8 is read without arithmetic on its packing. row refuses an element type other than the kind the rows were written as with Error.InvalidArgument, rather than reinterpreting them.

A cursor walks the index contents, reading each shard’s publication watermark as it enters that shard, so an entry once passed is never revisited. Without start keys it yields every entry as stored; with them, the starts’ own entries first, then the entries those link to breadth-first, each once. Each pull lands up to wanted keys in the arena, and the keys each links to when links is true; the vectors themselves come from get.

var cursor = try usearch.DenseCursor.init(index, &.{});
defer cursor.deinit();

while (true) {
    const batch = try index.on(executor).cursorNext(cursor, 1024, true, &arena);
    if (batch.written == 0) break; // exhausted
    consume(try batch.keys(), try batch.links(0));
}

A search stream is a resumable best-first traversal, so callers that post-filter aggressively pull until satisfied instead of guessing the “k” upfront. It keeps walk state rather than a thread, so any number may stay open on one executor, and every pull is an ordinary verb naming the index again, so it runs on whichever receiver pulls.

var stream = try usearch.DenseSearchStream.init(index, try .ofRow(f32, &query), .{});
defer stream.deinit();

while (true) {
    const found = try (try index.on(executor).searchStreamNext(stream, 16, &arena)).query(0);
    if (found.keys.len == 0) break; // drained
    for (found.keys, found.scores) |key, distance| std.debug.print("{f} at {d}\n", .{ key, distance });
}

A drained walk answers an empty query, as the C interface does, so a loop ends on the first pull that lands nothing.

§ Sampling

sample draws keys around focus, or across the whole index, each hanging from a shown or earlier draw and placed in three dimensions beside the shown keys already on screen, so a view grows one connected sample as it zooms. Equal seeds, shown keys and focus draw equally, and a larger wanted draws a superset.

const draws = try index.on(executor).sample(256, &arena, .{ .shown = shown, .shown_coordinates = places, .focus = near, .seed = 42 });
for (try draws.keys(), try draws.entryOrdinals(), 0..) |key, entry_ordinal, position| {
    const parent = try draws.parents.query(position); // empty for a root
    const point = try draws.coordinates.row(f32, position);
    _ = .{ key, entry_ordinal, parent, point };
}