# Retrieval and Streaming

> USearch for Rust

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

```rust
let mut arena = Arena::new_in(&executor)?;
let vectors = index.on(&executor).get::<f32>(key, &mut arena)?;
println!("{:?}", vectors.view()?.shape());
let vectors = index.on(&executor).get::<f32>(key, &mut arena)?;    // rewinds it, so the vectors above are gone
```

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.
`next_keys` walks the key column alone, and `next_links` copies the keys each entry links to beside it, both into an arena; the vectors themselves come from `get`.

```rust
let mut arena = Arena::new_in(&executor)?;
let mut cursor = index.on(&executor).cursor(&[])?;
loop {
    let batch = cursor.next_links(1024, &mut arena)?;
    if batch.written() == 0 { break; }
    println!("{} keys, the first linking to {:?}", batch.keys()?.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.
It walks exactly one query row, and each pull lands up to `wanted` more matches in an arena as the one query of `Matches`, empty once the walk is drained.
No residency implements the stream yet, so the engine answers `Status::Unsupported`.

```rust
let mut arena = Arena::new_in(&executor)?;
let mut stream = index.on(&executor).search_stream(rows(&query, 768)?)?;
'pulls: loop {
    let pulled = stream.next(64, &mut arena)?;
    let found = pulled.query(0)?;
    if found.keys.is_empty() { break; }
    for (key, distance) in found.keys.iter().zip(found.distances) {
        if *distance > 0.3 { break 'pulls; }
        println!("{key} at {distance}");
}
}
```

### Sampling

`sample` draws keys around a focus, each hanging from a shown or earlier draw, and places them in three dimensions beside the keys already shown, so a view grows one connected sample as it zooms.

```rust
let drawn = index.on(&executor).sample(
    256,
    &mut arena,
    DenseSampleConfig { shown: &shown, shown_coordinates: &xyz, focus: &near, seed: 42, ..Default::default() },
)?;
let (keys, places) = (drawn.keys()?, drawn.coordinates()?);
```

`use usearch::DenseBatch;`

`use usearch::DenseCursor;`

`use usearch::DenseSampleConfig;`

`use usearch::DenseSearchStream;`

`use usearch::DenseSearchStreamInitConfig;`

`use usearch::DenseVectors;`

`use usearch::Sample;`

## DenseBatch

One cursor pull exported into the arena it borrows: the keys, and beside them the keys each entry links to when the pull asked; the vectors themselves come from [`DenseVerbs::get`](https://www.unum.cloud/docs/usearch/rust/metrics.md#get).

```rust
pub struct DenseBatch<'arena>
```

Rust-only.

## written

Entries the pull wrote; zero means the walk is exhausted.

```rust
pub fn written(&self) -> usize
```

## keys

The keys of the entries, refused with [`Status::Device`](https://www.unum.cloud/docs/usearch/rust/errors.md#Device) over device memory.

```rust
pub fn keys(&self) -> Result<&'arena [Key]>
```

## links

The keys entry `entry` links to, refused with [`Status::InvalidArgument`](https://www.unum.cloud/docs/usearch/rust/errors.md#InvalidArgument) when the pull did not ask for links or `entry` is not below [`DenseBatch::written`](#written), and with [`Status::Device`](https://www.unum.cloud/docs/usearch/rust/errors.md#Device) over device memory.

```rust
pub fn links(&self, entry: usize) -> Result<&'arena [Key]>
```

## DenseCursor

A walk over the index contents; see [`DenseVerbs::cursor`](https://www.unum.cloud/docs/usearch/rust/metrics.md#cursor).

```rust
pub struct DenseCursor<'index>
```

The walk is a sequential scan, so it stays a batch operation: export, migration, and
visualization all move whole slabs.

Dropping it waits for every deferred call naming the cursor, then releases it.

Implements: `Debug`, `Drop`

## next_keys

Copies up to `wanted` next keys into `arena`; an empty batch means the walk is exhausted.

```rust
pub fn next_keys<'arena>(
    &mut self,
    wanted: usize,
    arena: &'arena mut Arena,
) -> Result<DenseBatch<'arena>>
```

## next_links

Copies up to `wanted` next keys into `arena`, each with the keys it links to; an empty batch means the walk is exhausted.

```rust
pub fn next_links<'arena>(
    &mut self,
    wanted: usize,
    arena: &'arena mut Arena,
) -> Result<DenseBatch<'arena>>
```

## DenseSampleConfig

The view a sample grows and how it draws; see [`DenseVerbs::sample`](https://www.unum.cloud/docs/usearch/rust/metrics.md#sample).

```rust
pub struct DenseSampleConfig<'config>
```

- `shown` `&'config [Key]`: The keys already shown: never drawn again, and the paths reach toward them.
- `shown_coordinates` `&'config [[f32; 3]]`: Where each of `shown` sits, the points later draws are placed against.
- `focus` `&'config [Key]`: The keys to look around; empty looks around the whole index.
- `seed` `u64`: The draw: equal seeds, shown keys and focus over an unchanged index draw equally.
- `expansion_factor` `usize`: The breadth of the walks behind the draws; zero derives it from the geometry.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the draws written against `wanted` and stops wherever it says to.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `Option<&'config mut DenseTraversalStats>`: Where the traversal telemetry lands, overwritten by the call.

Implements: `Default`

## DenseSearchStream

A resumable nearest-neighbor stream; see [`DenseVerbs::search_stream`](https://www.unum.cloud/docs/usearch/rust/metrics.md#search_stream).

```rust
pub struct DenseSearchStream<'index>
```

Ordering beyond the expansion horizon is best-effort nearest, not globally exact. Each pull
lands its matches in the arena it is given as one query of a search, so nothing allocates per
match. An empty pull means the walk is drained.

Dropping it waits for every deferred call naming the stream, then releases the walk state it
keeps.

Implements: `Debug`, `Drop`

## next

Pulls up to `wanted` more matches into `arena`, as the one query of [`Matches`](https://www.unum.cloud/docs/usearch/rust/inputs-and-outputs.md#Matches).

```rust
pub fn next<'arena>(&mut self, wanted: usize, arena: &'arena mut Arena) -> Result<Matches<'arena>>
```

## DenseSearchStreamInitConfig

The query a stream walks and the breadth of its walk; see [`DenseVerbs::search_stream`](https://www.unum.cloud/docs/usearch/rust/metrics.md#search_stream).

```rust
pub struct DenseSearchStreamInitConfig<Query>
```

- `query` `Query`: Exactly one query row.
- `expansion_factor` `usize`: The breadth of the candidates the walk explores; zero derives it from the geometry.

Implements: `From<Query>`

## DenseVectors

The rows [`DenseVerbs::get`](https://www.unum.cloud/docs/usearch/rust/metrics.md#get) or [`DenseVerbs::attend`](https://www.unum.cloud/docs/usearch/rust/metrics.md#attend) exported into the arena it borrows.

```rust
pub struct DenseVectors<'arena, Value>
```

Rust-only.

## view

One row per entry under the key in insertion order, or per query, at the pitch the library reported; refused with [`Status::Device`](https://www.unum.cloud/docs/usearch/rust/errors.md#Device) over device memory.

```rust
pub fn view(&self) -> Result<MatrixView<'arena, Value>>
```

## Sample

The draws [`DenseVerbs::sample`](https://www.unum.cloud/docs/usearch/rust/metrics.md#sample) exported into the arena it borrows.

```rust
pub struct Sample<'arena>
```

Rust-only.

## written

Draws the call wrote; fewer than wanted only once the region is exhausted.

```rust
pub fn written(&self) -> usize
```

## keys

The keys drawn, refused with [`Status::Device`](https://www.unum.cloud/docs/usearch/rust/errors.md#Device) over device memory.

```rust
pub fn keys(&self) -> Result<&'arena [Key]>
```

## entry_ordinals

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

```rust
pub fn entry_ordinals(&self) -> Result<&'arena [usize]>
```

## parents

The one shown or earlier draw each draw hangs from and its distance, one query per draw, a draw with none holding no match.

```rust
pub fn parents(&self) -> Matches<'arena>
```

## coordinates

Where each draw is placed, beside the shown keys.

```rust
pub fn coordinates(&self) -> Result<&'arena [[f32; 3]]>
```