# Retrieval and Streaming

> USearch for Swift

`get` lands every vector stored under a key in its arena, one row per entry sharing the key, converted to the scalar kind `as:` names.

```swift
let vectors = try index.get(key: 42, as: Float.self, arena: arena)
print(vectors.count, vectors.columns, vectors.stride, Array(vectors[0]))
```

`cursor()` opens a walk over the contents in batches, which is what export and migration want.
Each shard's publication watermark is read as the walk enters it, so an entry once passed is never revisited.
Without `starts:` it yields every entry as stored; with them, the starts' own entries first, then the entries those link to breadth-first, each once.
Every pull lands up to `wanted` keys in its arena, and `nextLinks` lands the keys each links to beside them; the vectors themselves come from `get`.

```swift
let cursor = try index.on(executor).cursor()
while true {
    let batch = try cursor.nextLinks(wanted: 1024, arena: arena)
    guard !batch.keys.isEmpty else { break }
    print(Array(batch.keys), batch.links[0])
}
```

`searchStream` opens a resumable nearest-neighbor stream over one query row, so a caller that post-filters aggressively pulls until satisfied rather than guessing a `wanted` count upfront.
The stream keeps walk state rather than a thread, every pull is an ordinary call on its receiver's executor, and a failed pull throws.
Ordering beyond the expansion horizon is best-effort nearest rather than globally exact.
The engine declares the stream before implementing it, so opening one reports `unsupported` for now.

```swift
let stream = try index.on(executor).searchStream(query)
while true {
    let pulled = try stream.next(wanted: 64, arena: arena)[0]              // nearest first, empty once drained
    let close = pulled.prefix { $0.distance < 0.25 }
    for match in close { print(match.key) }
    guard !close.isEmpty, close.count == pulled.count else { break }
}
```

Cursors and streams keep their index alive until they go.

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

```swift
let draws = try index.on(executor).sample(wanted: 256, arena: arena, config: DenseSampleConfig(
    shown: shown, shownCoordinates: places, focus: near, seed: 42))
for draw in 0 ..< draws.count {
    let (key, entryOrdinal, parent, point) = (draws.keys[draw], draws.entryOrdinal(draw), draws.parents[draw], draws.coordinates[draw])
}
```

`import USearch`

## DenseSampleConfig

The knobs of [`sample`](https://www.unum.cloud/docs/usearch/swift/metrics.md#sample).

```swift
struct DenseSampleConfig
```

Left alone, it draws across the whole index with nothing shown.

## shown

The keys already shown: never drawn again, and the paths reach toward them.

```swift
var shown: [Key]
```

## shownCoordinates

Where each [`shown`](#shown) key sits, three values apiece, end to end.

```swift
var shownCoordinates: [Float]
```

## focus

The keys to look around; empty looks around the whole index.

```swift
var focus: [Key]
```

## seed

Equal seeds, shown keys and focus over an unchanged index draw equally.

```swift
var seed: UInt64
```

## expansionFactor

The breadth of the candidates of the walks behind the draws; zero derives.

```swift
var expansionFactor: Int
```

## progress

Called with draws made; a stop answers [`cancelled`](https://www.unum.cloud/docs/usearch/swift/errors.md#cancelled).

```swift
var progress: Progress?
```

## progressSteps

Reports the call makes at most, the last at completion; zero derives to ten.

```swift
var progressSteps: Int
```

## stats

The traversal telemetry to write.

```swift
var stats: DenseTraversalStats?
```

## init

```swift
init(shown: [Key] = [], shownCoordinates: [Float] = [], focus: [Key] = [], seed: UInt64 = 0, expansionFactor: Int = 0, progress: Progress? = nil, progressSteps: Int = 0, stats: DenseTraversalStats? = nil)
```

## DenseSearchStreamInitConfig

The knobs of [`searchStream`](https://www.unum.cloud/docs/usearch/swift/metrics.md#searchStream).

```swift
struct DenseSearchStreamInitConfig
```

## expansionFactor

The breadth of the candidates the walk explores; zero derives it from the geometry.

```swift
var expansionFactor: Int
```

## init

```swift
init(expansionFactor: Int = 0)
```

## DenseVectors

The rows [`get`](https://www.unum.cloud/docs/usearch/swift/metrics.md#get) or [`attend`](https://www.unum.cloud/docs/usearch/swift/metrics.md#attend) wrote into an arena, one per entry sharing the key or per query, read in place as `Value`.

```swift
struct DenseVectors<Value> where Value : ScalarValue
```

Conforms to: `RandomAccessCollection`, `BidirectionalCollection`, `Collection`, `Sequence`

## endIndex

One past the last row the call wrote.

```swift
let endIndex: Int
```

## startIndex

The first row's position, which a collection walk starts from.

```swift
var startIndex: Int { get }
```

## stride

The bytes between consecutive rows, as the library reported them.

```swift
var stride: Int { get }
```

## columns

The logical values in each row, as the library reported them.

```swift
var columns: Int { get }
```

## subscript

One row's stored values, packed at their natural width.

```swift
subscript(row: Int) -> Row { get }
```

## DenseVectors.Row

One row of the arena's values, read in place.

```swift
struct Row
```

Conforms to: `RandomAccessCollection`, `BidirectionalCollection`, `Collection`, `Sequence`

## endIndex

One past the last value in the row.

```swift
let endIndex: Int
```

## startIndex

The first value's position, which a collection walk starts from.

```swift
var startIndex: Int { get }
```

## subscript

The value at a position.

```swift
subscript(position: Int) -> Value { get }
```

## DenseKeys

The keys a cursor pull wrote into an arena, in walk order.

```swift
struct DenseKeys
```

Conforms to: `RandomAccessCollection`, `BidirectionalCollection`, `Collection`, `Sequence`

## endIndex

One past the last key the call wrote.

```swift
let endIndex: Int
```

## startIndex

The first key's position, which a collection walk starts from.

```swift
var startIndex: Int { get }
```

## subscript

The key at a position.

```swift
subscript(position: Int) -> Key { get }
```

## DenseDraws

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

```swift
struct DenseDraws
```

## keys

The drawn keys.

```swift
let keys: DenseKeys
```

## parents

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

```swift
let parents: Matches
```

## coordinates

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

```swift
let coordinates: DenseVectors<Float>
```

## count

The draws written; fewer than wanted only once the region is exhausted.

```swift
var count: Int { get }
```

## entryOrdinal

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

```swift
func entryOrdinal(_ draw: Int) -> Int
```

## DenseLinks

The keys each entry of a cursor pull links to, wrote into an arena as a ragged run and read in place.

```swift
struct DenseLinks
```

Conforms to: `RandomAccessCollection`, `BidirectionalCollection`, `Collection`, `Sequence`

## endIndex

One past the last entry the pull wrote.

```swift
let endIndex: Int
```

## startIndex

The first entry's position, which a collection walk starts from.

```swift
var startIndex: Int { get }
```

## subscript

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

```swift
subscript(entry: Int) -> [Key] { get }
```

## DenseCursor

A walk over an index's contents; see `DenseIndex.cursor()`.

```swift
final class DenseCursor
```

The walk is sequential, so it stays a batch operation - export, migration, and
visualization all move whole batches. Every pull blocks on the executor of the receiver that
opened it, and the cursor keeps its index alive.

## next

Copies up to [`wanted`](https://www.unum.cloud/docs/usearch/swift/linear-algebra.md#wanted) next keys into `arena`, walking the key column alone; an empty batch means the walk is exhausted.

```swift
func next(wanted: Int, arena: Arena) throws(USearchError) -> DenseKeys
```

## nextLinks

Copies up to [`wanted`](https://www.unum.cloud/docs/usearch/swift/linear-algebra.md#wanted) next keys into `arena`, each with the keys it links to; an empty batch means the walk is exhausted.

```swift
func nextLinks(
    wanted: Int,
    arena: Arena
) throws(USearchError) -> (keys: DenseKeys, links: DenseLinks)
```

The vectors themselves come from [`get`](https://www.unum.cloud/docs/usearch/swift/metrics.md#get).

## DenseSearchStream

A resumable nearest-neighbor stream over one query; see [`DenseIndex.searchStream`](https://www.unum.cloud/docs/usearch/swift/metrics.md#searchStream).

```swift
final class DenseSearchStream
```

Best-first traversal is naturally pausable, so the stream keeps a live frontier and visited set
and yields matches lazily. Ordering beyond the expansion horizon is best-effort nearest rather
than globally exact, so pulling far past that breadth degrades the ranking rather than ending
the stream. Every pull blocks on the executor of the receiver that opened it.

## next

Pulls up to [`wanted`](https://www.unum.cloud/docs/usearch/swift/linear-algebra.md#wanted) more matches into `arena`, as the one query of a search, nearest first; an empty query means the traversal is drained.

```swift
func next(wanted: Int, arena: Arena) throws(USearchError) -> Matches
```