class DenseVectorsindex.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:
breakget 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
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.
API
ClassDenseVectorsThe rows get or attend wrote into an Arena: (count, dimensions), or (count, row_bytes) of 'B'.6
__buffer__Host memory only; device memory raises DeviceError, a rewound arena UninitializedError.
__len__Rows, or bytes of a Monolith.
__arrow_c_array__Exports host rows as an Arrow schema and array capsule.
Inherited from _ArrowOutput
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.
Inherited from _ArrowOutput
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.
Inherited from _ArrowOutput
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.
ClassSampleThe draws one sample call wrote into an Arena, viewing it until it rewinds.4
class Sample(structseq[Any], tuple[_ArenaBuffer, _ArenaBuffer, Matches, _ArenaBuffer])keys(written, 16) identities drawn, most significant byte first.
keys: _ArenaBufferentry_ordinals(written,) which of its key's entries each draw is, in the order get writes them.
entry_ordinals: _ArenaBufferparentsOne column per draw: the shown or earlier draw it hangs from, and its distance.
parents: Matchescoordinates(written, 3) float32 places of the draws, beside the shown keys.
coordinates: _ArenaBufferClassDenseBatchThe entries one cursor step wrote into an Arena; empty, so falsy, once the scan is drained.2
class DenseBatchkeys(count, 16) identities, most significant byte first.
keys: _ArenaBufferlinks(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.
links: tuple[_ArenaBuffer, _ArenaBuffer] | NoneClassDenseCursorA sequential scan over the entries an index holds, pulled in batches by next.2
class DenseCursornextThe next batch of at most wanted entries, in arena.
def next(
wanted: int,
arena: Arena,
/,
*,
links: bool = False,
) -> DenseBatchcloseReleases the scan before the cursor is collected.
def close() -> NoneClassDenseSearchStreamA resumable best-first stream of matches for one query, pulled by next.2
class DenseSearchStreamnextThe next at most wanted matches, as one query in arena.
def next(wanted: int, arena: Arena, /) -> MatchescloseReleases the walk before the stream is collected.
def close() -> None