# Retrieval and Streaming

> USearch for Python

```python
index.get(42, arena)  # a (count, dimensions) `DenseVectors` of what is stored under it
cursor = index.on(pool).cursor()  # entry scan, pulled in batches; `cursor([42])` walks out from key 42
while batch := cursor.next(1024, arena, links=True):
    ...  # batch.keys, and batch.links as (offsets, keys) when asked; vectors come from `get`
with index.on(pool).search_stream(query) as stream:  # resumable best-first stream
    while pulled := stream.next(16, arena)[0]:  # one query of `Matches`, empty once drained
        if pulled[-1].distance > 0.3:
            break
```

`get` for an absent key answers an empty, falsy `DenseVectors`.
Every pull names its arena and rewinds it like any other call, so one arena serves a scan and any other verb in turn.
A drained cursor answers an empty, falsy `DenseBatch`, and a drained stream a query with no matches.
A cursor or a stream releases its walk on `close()` or at the end of a `with` block, so an `absorb` waiting on it need not wait for the collector, and a later pull raises `UninitializedError`.

### Sampling

```python
drawn = index.on(pool).sample(256, arena, shown=shown, shown_coordinates=xyz, focus=near, seed=42)
```

`sample` draws keys around `focus`, each hanging from a shown or earlier draw, and places them in three dimensions beside the `shown` keys.
The `Sample` it answers holds `keys`, `entry_ordinals`, `parents` and `coordinates` in the arena, and a larger `wanted` under the same seed draws a superset.

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

## DenseVectors

The rows [`get`](https://www.unum.cloud/docs/usearch/python/metrics.md#get) or [`attend`](https://www.unum.cloud/docs/usearch/python/metrics.md#attend) wrote into an [`Arena`](https://www.unum.cloud/docs/usearch/python/inputs-and-outputs.md#Arena): (count, dimensions), or (count, row_bytes) of 'B'.

```python
class DenseVectors
```

## __buffer__

Host memory only; device memory raises [`DeviceError`](https://www.unum.cloud/docs/usearch/python/errors.md#DeviceError), a rewound arena [`UninitializedError`](https://www.unum.cloud/docs/usearch/python/errors.md#UninitializedError).

```python
def __buffer__(flags: int, /) -> memoryview
```

Python-only.

## __len__

Rows, or bytes of a [`Monolith`](https://www.unum.cloud/docs/usearch/python/serialization.md#Monolith).

```python
def __len__() -> int
```

Python-only.

## __arrow_c_array__

Exports host rows as an Arrow schema and array capsule.

```python
def __arrow_c_array__(
    requested_schema: _Capsule | None = None,
) -> tuple[_Capsule, _Capsule]
```

## __arrow_c_device_array__

Exports rows wherever they live as an Arrow schema and device array capsule.

```python
def __arrow_c_device_array__(
    requested_schema: _Capsule | None = None,
) -> tuple[_Capsule, _Capsule]
```

## __arrow_c_stream__

Exports host rows as an Arrow stream of one chunk.

```python
def __arrow_c_stream__(
    requested_schema: _Capsule | None = None,
) -> _Capsule
```

## __cuda_array_interface__

Version 3 of the CUDA Array Interface, present only over device memory.

```python
__cuda_array_interface__: dict[str, Any]
```

Python-only.

## Sample

The draws one [`sample`](https://www.unum.cloud/docs/usearch/python/metrics.md#sample) call wrote into an [`Arena`](https://www.unum.cloud/docs/usearch/python/inputs-and-outputs.md#Arena), viewing it until it rewinds.

```python
class Sample(structseq[Any], tuple[_ArenaBuffer, _ArenaBuffer, Matches, _ArenaBuffer])
```

## keys

(written, 16) identities drawn, most significant byte first.

```python
keys: _ArenaBuffer
```

## entry_ordinals

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

```python
entry_ordinals: _ArenaBuffer
```

## parents

One column per draw: the shown or earlier draw it hangs from, and its distance.

```python
parents: Matches
```

## coordinates

(written, 3) float32 places of the draws, beside the shown keys.

```python
coordinates: _ArenaBuffer
```

## DenseBatch

The entries one cursor step wrote into an [`Arena`](https://www.unum.cloud/docs/usearch/python/inputs-and-outputs.md#Arena); empty, so falsy, once the scan is drained.

```python
class DenseBatch
```

## keys

(count, 16) identities, most significant byte first.

```python
keys: _ArenaBuffer
```

## links

(offsets, keys) of each entry's linked identities, entry `i` spanning `offsets[i]` to `offsets[i + 1]`, or None when the step asked for none.

```python
links: tuple[_ArenaBuffer, _ArenaBuffer] | None
```

## DenseCursor

A sequential scan over the entries an index holds, pulled in batches by [`next`](#next).

```python
class DenseCursor
```

## next

The next batch of at most `wanted` entries, in `arena`.

```python
def next(
    wanted: int,
    arena: Arena,
    /,
    *,
    links: bool = False,
) -> DenseBatch
```

## close

Releases the scan before the cursor is collected.

```python
def close() -> None
```

## DenseSearchStream

A resumable best-first stream of matches for one query, pulled by [`next`](#next).

```python
class DenseSearchStream
```

## next

The next at most `wanted` matches, as one query in `arena`.

```python
def next(wanted: int, arena: Arena, /) -> Matches
```

## close

Releases the walk before the stream is collected.

```python
def close() -> None
```