# Retrieval and Streaming

> USearch for JavaScript

`get` exports the vectors stored under one key into the arena, as `f32` unless `scalar` names another kind:

```javascript
const stored = index.get(42n, arena); // The vectors under a key, as f32 DenseVectors
using bitsArena = new usearch.Arena();
const packed = index.get(42n, bitsArena, { scalar: usearch.Scalar.U1x8 }); // Or as packed bits, in another arena
```

`get` shapes its rows from the width and stride the call reports: `stored.data` holds `stored.rows` rows of `stored.columns` values, `stored.stride` bytes apart, and no rows when the key is absent.

A cursor walks the index instead; each shard's watermark is read as the walk enters it, so an entry once passed is never revisited.
Without start keys it yields every entry in storage order; with them, the starts' own entries first, then the entries those link to breadth-first, each once.
It lands each batch of up to `wanted` keys in the arena, and beside them the keys each links to when `links` asks; the vectors themselves come from `get`:

```javascript
using cursor = index.on(executor).cursor();
for (let batch = cursor.next(1024, arena, { links: true }); batch.entries; batch = cursor.next(1024, arena, { links: true })) {
  writeOut(batch.keys, batch.links.get(0), batch.entries);
}
```

Cursors and streams keep their walk state rather than a thread: every pull is an ordinary call on the executor of the receiver that opened them, and each keeps its index alive until freed.
No residency implements the stream yet, so the engine answers `Status.Unsupported`, and a stream reports no telemetry, since the ABI gives a resumable walk none.

### 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.
The shown keys, their coordinates and the focus are read in place, so a deferred sample holds those arrays until it is final.

```javascript
const drawn = index.on(executor).sample(256, arena, { shown, shownCoordinates: places, focus: near, seed: 42 });
drawn.keys; // sixteen bytes per draw
drawn.entryOrdinals; // which of its key's entries each draw is
drawn.parents.get(0); // the shown or earlier draw it hangs from, empty for a root
drawn.coordinates.data; // three f32 values per draw
```

`import * as usearch from 'usearch';`

`import { DenseVectors } from 'usearch';`

`import { DenseCursorLinks } from 'usearch';`

`import { DenseDraws } from 'usearch';`

`import { DenseCursorBatch } from 'usearch';`

`import { DenseCursor } from 'usearch';`

`import { DenseSearchStream } from 'usearch';`

## DenseSampleConfig

Optional per-call settings of a sample; absent ones draw across the whole index with nothing shown.

```typescript
interface DenseSampleConfig
```

- `shown?` `KeysLike`: The keys already shown: never drawn again, and the paths reach toward them; read in place, never copied.
- `shownCoordinates?` `Float32Array`: Where each `shown` key sits, three values apiece, end to end; read in place.
- `focus?` `KeysLike`: The keys to look around; absent looks around the whole index.
- `seed?` `number | bigint`: Equal seeds, shown keys and focus over an unchanged index draw equally.
- `expansionFactor?` `number`: Breadth of the candidates of the walks behind the draws; absent lets the engine derive it.

## DenseGetConfig

Optional settings of a retrieval.

```typescript
interface DenseGetConfig
```

- `scalar?` `Scalar`: The scalar kind to export as, converted from storage; defaults to `f32`.

## DenseCursorNextConfig

Optional settings of one cursor pull.

```typescript
interface DenseCursorNextConfig
```

- `links?` `boolean`: Whether to export the keys each entry links to beside it; absent pulls the keys alone.

## DenseSearchStreamInitConfig

Optional settings of a resumable search stream.

```typescript
interface DenseSearchStreamInitConfig
```

- `expansionFactor?` `number`: Breadth of the candidates the walk explores; absent lets the engine derive it.

## DenseVectors

Rows a call wrote into its arena: the entries [`get`](#get) exported, or the rows [`attend`](https://www.unum.cloud/docs/usearch/javascript/metrics.md#attend) attended.

```typescript
class DenseVectors extends ArenaView
```

[`data`](#data) is a `Float64Array`, `Float32Array`, `Float16Array` or `Int8Array` for the kinds
JavaScript spells, a `Uint16Array` for `bf16` and for `f16` on a runtime without `Float16Array`,
and the raw bytes in a `Uint8Array` for the rest.

## DenseVectors

Made by a verb, never directly.

```typescript
new DenseVectors(outputs: CompiledVectors, scalar: Scalar)
```

## rows

Rows written; zero when [`get`](#get) found no entry under the key.

```typescript
readonly rows: number
```

## columns

Values in each row, as the call reported them.

```typescript
readonly columns: number
```

## stride

Bytes between consecutive rows.

```typescript
readonly stride: number
```

## scalar

The scalar kind the rows were exported as.

```typescript
readonly scalar: Scalar
```

## data

Every row, laid [`stride`](#stride) bytes apart.

```typescript
readonly data: Vector
```

## DenseCursorLinks

The keys each entry of a cursor pull links to, as a ragged run with Apache Arrow offsets: entry `i` links to keys `offsets[i]` up to `offsets[i + 1]`.

```typescript
class DenseCursorLinks extends ArenaView
```

## DenseCursorLinks

Made by [`DenseCursor.next`](#next), never directly.

```typescript
new DenseCursorLinks(outputs: CompiledLinks, entries: number)
```

## get

Borrows the keys one entry links to, without copying.

```typescript
get(entry: number): Uint8Array
```

Binding-only.

- `entry`: Which pulled entry to read.

## entries

Entries the pull covers.

```typescript
readonly entries: number
```

## offsets

One more entry than there are pulled entries, non-decreasing.

```typescript
readonly offsets: BigUint64Array
```

## keys

Sixteen bytes per link, end to end.

```typescript
readonly keys: Uint8Array
```

## DenseDraws

The draws a sample wrote, viewed inside its arena: 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.

```typescript
class DenseDraws extends ArenaView
```

## DenseDraws

Made by [`sample`](https://www.unum.cloud/docs/usearch/javascript/metrics.md#sample), never directly.

```typescript
new DenseDraws(outputs: CompiledDraws)
```

## draws

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

```typescript
readonly draws: number
```

## parents

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

```typescript
readonly parents: Matches
```

## coordinates

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

```typescript
readonly coordinates: DenseVectors
```

## keys

Sixteen bytes per draw.

```typescript
readonly keys: Uint8Array
```

## entryOrdinals

Which of its key's entries each draw is, in the order [`get`](#get) writes them.

```typescript
readonly entryOrdinals: BigUint64Array
```

## DenseCursorBatch

One cursor pull, viewed inside its arena: the keys, and the keys they link to when those were asked for.

```typescript
class DenseCursorBatch extends ArenaView
```

## DenseCursorBatch

Made by [`DenseCursor.next`](#next), never directly.

```typescript
new DenseCursorBatch(outputs: CompiledBatch)
```

## entries

Entries pulled; zero once the walk is exhausted.

```typescript
readonly entries: number
```

## links

The keys each entry links to; absent when the pull asked for keys alone.

```typescript
readonly links: DenseCursorLinks | undefined
```

## keys

Sixteen bytes per entry pulled.

```typescript
readonly keys: Uint8Array
```

## DenseCursor

A walk over an index.

```typescript
class DenseCursor implements Disposable
```

Each shard's publication watermark is read as the walk enters it, so an entry once passed is never revisited.

Holds engine state until [`free`](#free) is called; a walk left to the garbage collector releases it
whenever the collector gets to it. It keeps its index alive, and pulls on the executor of the
receiver that opened it.

## DenseCursor

Made by [`cursor`](https://www.unum.cloud/docs/usearch/javascript/metrics.md#cursor), never directly.

```typescript
new DenseCursor(compiled: CompiledCursor)
```

## next

Pulls the next entries of the walk into `arena`; the vectors themselves come from [`get`](#get).

```typescript
next(
    wanted: number,
    arena: Arena,
    config: DenseCursorNextConfig = {},
): DenseCursorBatch
```

- `wanted`: The upper bound on entries this pull lands.
- `arena`: The memory the batch lands in, rewound by the pull.
- `config`: Whether to export each entry's links; absent pulls keys alone.

## free

Releases the scan; a second call does nothing.

```typescript
free(): void
```

## DenseSearchStream

A resumable nearest-neighbor walk over one query, pulled from the caller's own thread.

```typescript
class DenseSearchStream implements Disposable
```

This is the filtered path: pull matches, drop the ones a JavaScript predicate rejects, and
pull again until satisfied - rather than guessing a `k` wide enough to survive the filter.
The stream keeps walk state rather than a thread, and every pull is an ordinary call on the
executor of the receiver that opened it.

## DenseSearchStream

Made by [`searchStream`](https://www.unum.cloud/docs/usearch/javascript/metrics.md#searchStream), never directly.

```typescript
new DenseSearchStream(compiled: CompiledSearchStream)
```

## next

Pulls the next-nearest matches from the stream into `arena`.

```typescript
next(wanted: number, arena: Arena): Matches
```

- `wanted`: The upper bound on matches this pull lands.
- `arena`: The memory the matches land in, rewound by the pull.

## free

Releases the walk state; a second call does nothing.

```typescript
free(): void
```