Retrieval and Streaming

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.

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.

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.

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.

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])
}