# Retrieval and Streaming

> USearch for Mojo

`get` exports every entry stored under one key, one row per entry in insertion order, as `DenseVectors`, whose every row is exactly `columns()` values wide, as the engine reported them, however far apart the engine laid the rows.

```mojo
var stored = index.get[DType.float32](Key(integer=42), arena)  # empty when the key is absent
```

A cursor walks the contents, writing each batch in the arena; `next_keys` walks the key column alone, and `next_links` lands the keys each entry links to beside it, while the vectors come from `get`.
Without start keys it yields every entry as stored; `cursor(starts)` yields the starts' own entries first, then the entries those link to breadth-first, each once.

```mojo
var cursor = index.on(executor).cursor()
while True:
    var batch = cursor.next_links(1024, arena)  # empty once exhausted
    if len(batch) == 0:
        break
    print(batch.keys()[0], len(batch.links(0)))
```

A search stream is a resumable best-first traversal, so callers that post-filter aggressively pull until satisfied instead of guessing "k" upfront.
No residency of the engine implements the stream yet, so it answers `Status.UNSUPPORTED`.

```mojo
var stream = index.on(executor).search_stream(RowsView.of(query, 768))
while True:
    var pulled = stream.next(16, arena)  # one query of Matches, empty once drained
    if len(pulled.query_keys(0)) == 0:
        break
```

Cursors and streams open on the blocking receivers alone, the index and `index.on(executor)`, and every pull blocks.
Both borrow the index and the executor, so neither can be released while a cursor or a stream lives, and a drained one answers an empty view rather than raising.

### 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.

```mojo
var config = DenseSampleConfig(shown=shown, shown_coordinates=places, focus=near, seed=42)
var draws = index.on(executor).sample(256, arena, config)
var keys = draws.keys()
var entry_ordinals = draws.entry_ordinals()
var parents = draws.parents()
var coordinates = draws.coordinates()
```

`from usearch import DenseVectors, DenseBatch, DenseDraws, …`

## DenseVectors

Rows a call wrote into its arena - `usearch_rows_view_t` - read in place: the entries [`get`](https://www.unum.cloud/docs/usearch/mojo/executors.md#get) exports, or the rows [`attend`](https://www.unum.cloud/docs/usearch/mojo/executors.md#attend) attends.

```mojo
struct DenseVectors[dtype: DType, origin: MutOrigin]
```

Rows are `stride` bytes apart and [`columns`](#columns) values wide, both as the engine reported them, so a
padded row never reads as extra values.

- `dtype` (comptime): The element type each row is read as.
- `origin` (comptime): The arena the rows live in, which this result borrows.

- `arena` `Pointer[Arena, origin]`: The arena holding the rows.
- `generation` `Int`: The arena's call these rows came from, so a read after a later call is refused.
- `view` `RowsViewArguments`: The first row, the stride, the width and the kind, as the engine wrote them.
- `rows` `Int`: Rows written; zero when the key is absent.

Conforms to: `Deinitable`, `Movable`, `Sized`

## __getitem__

One row, borrowed from the arena this result reads. Binding-only.

```mojo
def __getitem__(ref self, row: Int) -> Span[Scalar[dtype], origin_of(self)]
```

- `row`: Which row, below `len(self)`.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`UNINITIALIZED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#UNINITIALIZED) once a later call rewound the arena, or [`DEVICE`](https://www.unum.cloud/docs/usearch/mojo/errors.md#DEVICE) over VRAM.

## __len__

The rows written.

```mojo
def __len__(self) -> Int
```

## columns

Values in each row, as the engine reported them.

```mojo
def columns(self) -> Int
```

## DenseBatch

One cursor pull, read in place from its arena: the keys, and the keys each links to when asked for.

```mojo
struct DenseBatch[origin: MutOrigin]
```

- `origin` (comptime): The arena the batch lives in, which this result borrows.

- `arena` `Pointer[Arena, origin]`: The arena holding the batch.
- `generation` `Int`: The arena's call this batch came from, so a read after a later call is refused.
- `keys_address` `Address`: The first key, inside the arena.
- `linked` `Bool`: Whether the pull exported links.
- `links_view` `KeysTapeViewArguments`: The keys each entry links to and their offsets, null for a pull of keys alone.
- `written` `Int`: Entries the pull wrote; zero when the walk is exhausted.

Conforms to: `Deinitable`, `Movable`, `Sized`

## __len__

The entries the pull wrote.

```mojo
def __len__(self) -> Int
```

## keys

Every entry's key, in walk order.

```mojo
def keys(ref self) -> Span[Key, origin_of(self)]
```

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`UNINITIALIZED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#UNINITIALIZED) once a later call rewound the arena, or [`DEVICE`](https://www.unum.cloud/docs/usearch/mojo/errors.md#DEVICE) over VRAM.

## links

The keys one entry links to, as the graph stored them when the pull ran. Binding-only.

```mojo
def links(ref self, entry: Int) -> Span[Key, origin_of(self)]
```

- `entry`: Which entry, below `len(self)`.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`INVALID_ARGUMENT`](https://www.unum.cloud/docs/usearch/mojo/errors.md#INVALID_ARGUMENT) for a pull of keys alone or an entry past the batch, with [`UNINITIALIZED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#UNINITIALIZED) once a later call rewound the arena, or [`DEVICE`](https://www.unum.cloud/docs/usearch/mojo/errors.md#DEVICE) over VRAM.

## DenseDraws

The draws [`sample`](https://www.unum.cloud/docs/usearch/mojo/executors.md#sample) wrote into its arena, read in place: each draw's key, which of that key's entries it is, the shown or earlier draw it hangs from, and where it is placed.

```mojo
struct DenseDraws[origin: MutOrigin]
```

- `origin` (comptime): The arena the draws live in, which this result borrows.

- `arena` `Pointer[Arena, origin]`: The arena holding the draws.
- `generation` `Int`: The arena's call these draws came from, so a read after a later call is refused.
- `outputs` `DenseSampleOutputs`: Where the engine wrote every output, inside the arena.

Conforms to: `Deinitable`, `Movable`, `Sized`

## __len__

The draws written.

```mojo
def __len__(self) -> Int
```

## keys

Every draw's key.

```mojo
def keys(ref self) -> Span[Key, origin_of(self)]
```

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`UNINITIALIZED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#UNINITIALIZED) once a later call rewound the arena, or [`DEVICE`](https://www.unum.cloud/docs/usearch/mojo/errors.md#DEVICE) over VRAM.

## entry_ordinals

Which of its key's entries each draw is, in the order [`get`](https://www.unum.cloud/docs/usearch/mojo/executors.md#get) writes them.

```mojo
def entry_ordinals(ref self) -> Span[UInt, origin_of(self)]
```

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`UNINITIALIZED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#UNINITIALIZED) once a later call rewound the arena, or [`DEVICE`](https://www.unum.cloud/docs/usearch/mojo/errors.md#DEVICE) over VRAM.

## parents

Each draw's parent and its distance, one column per draw, a root holding none.

```mojo
def parents(self) -> Matches[origin]
```

## coordinates

Where each draw is placed, one row of three values apiece.

```mojo
def coordinates(self) -> DenseVectors[.float32, origin]
```

## DenseSampleConfig

The knobs of `usearch_dense_sample_t`; left alone, it draws across the whole index with nothing shown.

```mojo
struct DenseSampleConfig[shown_origin: ImmOrigin = ImmUntrackedOrigin, coordinates_origin: ImmOrigin = ImmUntrackedOrigin, focus_origin: ImmOrigin = ImmUntrackedOrigin]
```

- `shown_origin` (comptime): The shown keys' origin, inferred where any are lent.
- `coordinates_origin` (comptime): Their coordinates' origin, inferred with them.
- `focus_origin` (comptime): The focus keys' origin, inferred where any are lent.

- `shown` `Span[Key, shown_origin]`: The keys already shown, never drawn again; empty shows nothing yet.
- `shown_coordinates` `Span[Float32, coordinates_origin]`: Where each `shown` key sits, three values apiece.
- `focus` `Span[Key, focus_origin]`: The keys to look around; empty looks around the whole index.
- `seed` `UInt64`: Equal seeds, shown keys and focus over an unchanged index draw equally.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __init__

Names only the knobs that differ from the defaults.

```mojo
def __init__(
    out self,
    *,
    shown: Span[Key, shown_origin] = Span(),
    shown_coordinates: Span[Float32, coordinates_origin] = Span(),
    focus: Span[Key, focus_origin] = Span(),
    seed: UInt64 = UInt64(0)
)
```

- `shown`: The keys already shown, never drawn again; empty shows nothing yet.
- `shown_coordinates`: Where each `shown` key sits, three values apiece.
- `focus`: The keys to look around; empty looks around the whole index.
- `seed`: Equal seeds, shown keys and focus over an unchanged index draw equally.

## DenseSearchStreamInitConfig

The knobs of `usearch_dense_search_stream_init_t`; zeroed ones derive what the C interface derives.

```mojo
struct DenseSearchStreamInitConfig
```

- `expansion_factor` `Int`: The breadth of the candidates the walk explores; zero derives.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __init__

Names only the knobs that differ from the derived ones.

```mojo
def __init__(out self, *, expansion_factor: Int = Int(0))
```

- `expansion_factor`: The breadth of the candidates the walk explores; zero derives.

## DenseCursor

A walk over the index contents - `usearch_dense_cursor_t`.

```mojo
struct DenseCursor[origin: ImmOrigin]
```

Export, migration, and visualization feed off it. It borrows the index and the executor its
pulls run on, so neither can be released while it lives.

- `origin` (comptime): The index and the executor, which the cursor borrows.

- `library` `Library`: The loaded engine, held so the release can still reach `usearch_dense_cursor_free`.
- `index` `Address`: The `usearch_dense_index_t` the cursor was opened on, which every pull names again.
- `executor` `Address`: The `usearch_executor_t` every pull runs on.
- `address` `Address`: The `usearch_dense_cursor_t` this struct owns.

Conforms to: `Deinitable`, `Movable`

## __init__

Opens a cursor over `index`. Calls `usearch_dense_cursor_init`.

```mojo
def __init__(out self, library: Library, index: Int, executor: Int, starts_count: Int, starts: Int)
```

- `library`: The loaded engine the cursor is opened through.
- `index`: The handle to scan.
- `executor`: The executor every pull runs on.
- `starts_count`: The start keys at `starts`; zero walks every entry as stored.
- `starts`: The first start key, or `NULL_ADDRESS` for none.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the residency has no cursor, as VRAM does not.

## __deinit__

Releases the cursor. Calls `usearch_dense_cursor_free`.

```mojo
def __deinit__(deinit self)
```

The loader reference is surrendered only after the call: reading the entry point is the
last use of `library`, so without the trailing move Mojo drops the last reference - and
`dlclose`s the engine - between the load and the branch to it.

## next_keys

Copies up to `wanted` next keys into a lent arena, skipping their links. Calls `usearch_dense_cursor_next`.

```mojo
def next_keys(self, wanted: Int, mut arena: Arena) -> DenseBatch[origin_of(arena)]
```

- `wanted`: The upper bound on keys this pull writes.
- `arena` (mut): The arena to rewind and refill, which the batch borrows; a failed call leaves it valid.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the engine refuses the copy.

## next_links

Copies up to `wanted` next keys into a lent arena, each with the keys it links to. Calls `usearch_dense_cursor_next`.

```mojo
def next_links(self, wanted: Int, mut arena: Arena) -> DenseBatch[origin_of(arena)]
```

- `wanted`: The upper bound on entries this pull writes.
- `arena` (mut): The arena to rewind and refill, which the batch borrows; a failed call leaves it valid.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the engine refuses the copy.

## DenseSearchStream

A resumable nearest-neighbor stream - `usearch_dense_search_stream_t`.

```mojo
struct DenseSearchStream[origin: ImmOrigin]
```

Best-first traversal is naturally pausable, so the stream keeps the walk's frontier and visited
set between pulls. Callers that post-filter aggressively pull until satisfied instead of
guessing "k" upfront. Ordering beyond the expansion horizon is best-effort nearest rather than
globally exact.

- `origin` (comptime): The index, the executor, and the query row, which the stream borrows.

- `library` `Library`: The loaded engine, held so the release can still reach `usearch_dense_search_stream_free`.
- `index` `Address`: The `usearch_dense_index_t` the stream was opened on, which every pull names again.
- `executor` `Address`: The `usearch_executor_t` every pull runs on.
- `address` `Address`: The `usearch_dense_search_stream_t` this struct owns.

Conforms to: `Deinitable`, `Movable`

## __init__

Opens a stream over `index` for one query row. Calls `usearch_dense_search_stream_init`.

```mojo
def __init__(
    out self,
    library: Library,
    index: Int,
    executor: Int,
    query: RowsViewArguments,
    expansion_factor: Int
)
```

- `library`: The loaded engine the stream is opened through.
- `index`: The handle to query.
- `executor`: The executor every pull runs on.
- `query`: The single query row.
- `expansion_factor`: The breadth of the candidates the walk explores; zero derives.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`UNSUPPORTED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#UNSUPPORTED) while no residency implements the stream.

## __deinit__

Releases the stream and the walk state it keeps. Calls `usearch_dense_search_stream_free`.

```mojo
def __deinit__(deinit self)
```

The loader reference is surrendered only after the call: reading the entry point is the
last use of `library`, so without the trailing move Mojo drops the last reference - and
`dlclose`s the engine - between the load and the branch to it.

## next

Pulls up to `wanted` next-nearest matches into a lent arena, as the one query of a search. Calls `usearch_dense_search_stream_next`.

```mojo
def next(self, wanted: Int, mut arena: Arena) -> Matches[origin_of(arena)]
```

- `wanted`: The upper bound on matches this pull writes.
- `arena` (mut): The arena to rewind and refill, which the pull borrows; a failed call leaves it valid.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the engine refuses to advance.