Collections | UStore for Mojo

§ Keys

Every verb takes a batch, and its shortest packed input sets how many tasks it carries, so the library never reads past a view; a repeated element fits any batch. Fixed-width inputs are strided views, KeysView, CollectionsView, LengthsView and VertexRolesView, made from a span with .of(...) or from one element repeated for every task with .repeating(...). Ragged inputs are StringsView tapes of 32-bit or 64-bit offsets, the Apache Arrow layout a read writes, so a tape read back is written again as it is. Every view tracks the origin of what it borrows, so the data outlives the call that reads it.

API

Types

CollectionsViewA strided run of collections, ustore_collections_view_t.

comptime CollectionsView[origin: ImmOrigin = ImmUntrackedOrigin]: AnyStruct[StridedView[CollectionID, origin]] = StridedView[CollectionID, origin]

StructKeyRunsThe keys a scan or a sample listed into the arena it borrows, run after run, one run per task.6

struct KeyRuns[origin: MutOrigin]

Parameters

`originMutOrigin`	comptime	The arena the keys live in, which this result borrows.

Fields

`arena`	`Pointer[Arena, origin]`	The arena holding the keys.
`generation`	`Int`	The arena's call the keys came from.
`written`	`KeyRunsWritten`	The views the engine wrote.
`count`	`Int`	Runs, one per task.

Values

`Written`	`KeyRunsWritten`

Conforms to

Answer, Deinitable, Movable, Sized

__init__

def __init__(out self, arena: Int, generation: Int, written: KeyRunsWritten, count: Int)

__len__The runs, one per task.

def __len__(self) -> Int

offsetsThe runs' boundaries in keys, one more of them than runs.

def offsets(ref self) -> Span[UInt64, origin_of(self)]

keysEvery run's keys end to end.

def keys(ref self) -> Span[Key, origin_of(self)]

runThe keys of task index.

def run(ref self, index: Int) -> Span[Key, origin_of(self)]

scoresOne score per listed key, empty unless weighted patterns asked for them.

def scores(ref self) -> Span[Float32, origin_of(self)]

StructUUIDSixteen bytes naming one thing everywhere, ordered as their bytes, ustore_uuid_t.4

struct UUID

Fields

`bytes`	`StaticTuple[UInt8, Int(16)]`	The bytes, an integer spelled big-endian.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, Writable

__init__The nil UUID.

def __init__(out self)

def __init__(out self, value: UInt64)

The UUID spelling an integer as its 128-bit big-endian bytes, so such UUIDs order as integers.

__eq__*__eq__× 3Whether every byte matches.

def __eq____eq__(self, other: Self) -> Bool

__ne__*__ne__× 3Whether any byte differs.

def __ne____ne__(self, other: Self) -> Bool

write_toWrites the canonical hyphenated lowercase hex spelling.

def write_to(self, mut writer: T)

StructKeyThe identifier of a value within one collection, ustore_key_t.2

struct Key

Fields

`uuid`	`UUID`	The sixteen bytes.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, Writable

__init__The nil key.

def __init__(out self)

def __init__(out self, value: UInt64)

The key spelling an integer, so such keys order as integers.

write_*_to× 2Writes the UUID spelling.

def write__to(self, mut writer: T)

StructCollectionIDThe identifier of a collection, a UUIDv7 its create mints once, ustore_collection_id_t.1

struct CollectionID

Fields

`uuid`	`UUID`	The sixteen bytes; nil names no collection.

Values

`Written`	`CollectionID`

Conforms to

Answer, Copyable, Defaultable, Deinitable, Equatable, ImplicitlyCopyable, Movable, Writable

__init__The nil identifier, which names no collection.

def __init__(out self)

def __init__(out self, arena: Int, generation: Int, written: Self, count: Int)

Adopts the identifier a create wrote.

StructDropModeWhat dropping a collection removes, ustore_drop_mode_t.

struct DropMode

Fields

`code`	`c_int`	The raw `ustore_drop_mode_t` value the ABI exchanges.

Values

`COLLECTION`	`DropMode(Int32(0))`	The collection with its name and every pair.
`PAIRS`	`DropMode(Int32(1))`	Every key and value, keeping the collection.
`VALUES`	`DropMode(Int32(2))`	Every value, keeping the keys.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructModalityWhat a collection holds, ustore_modality_t; zero names none.

struct Modality

Fields

`code`	`c_int`	The raw `ustore_modality_t` value the ABI exchanges.

Values

`NONE`	`Modality(Int32(0))`	No modality, as a name no collection carries finds.
`BLOBS`	`Modality(Int32(1))`	Binary values.
`DOCS`	`Modality(Int32(2))`	JSON documents.
`GRAPH`	`Modality(Int32(3))`	Vertices and their edges.
`STRINGS`	`Modality(Int32(4))`	Keys found by strings.
`PAGES`	`Modality(Int32(5))`	Ordered documents of elements.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructCapabilitiesCapabilities an engine reports, ustore_capabilities_t, as flags.1

struct Capabilities

Fields

`code`	`c_int`	The raw flags.

Values

`TRANSACTIONS`	`Capabilities(Int32(1))`	The engine supports transactions.
`SNAPSHOTS`	`Capabilities(Int32(4))`	The engine supports snapshots.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

containsWhether every flag other names is set.

def contains(self, other: Self) -> Bool

StructDatabaseDescriptionWhat an open database reports about itself in one call, ustore_database_description_t.1

struct DatabaseDescription

Fields

`capabilities`	`Capabilities`	The capabilities of the engine.
`engine`	`Engine`	The engine serving the database.
`isolation`	`Isolation`	How transactions see each other.
`keys`	`c_size_t`	Keys across every collection, the engine's estimate.
`memory_bytes`	`c_size_t`	Bytes of memory the engine holds for the data.
`disk_bytes`	`c_size_t`	Bytes the files of the database take on disk.

Values

`Written`	`DatabaseDescription`

Conforms to

Answer, Copyable, Defaultable, Deinitable, ImplicitlyCopyable, Movable

__init__Zeroes every field, which is what a failed report leaves.

def __init__(out self)

def __init__(out self, arena: Int, generation: Int, written: Self, count: Int)

Adopts the description a call wrote.

StructCollectionListThe collections of a database, read in place from the arena a listing borrows.5

struct CollectionList[origin: MutOrigin]

Parameters

`originMutOrigin`	comptime	The arena the listing lives in, which this result borrows.

Fields

`arena`	`Pointer[Arena, origin]`	The arena holding the listing.
`generation`	`Int`	The arena's call the listing came from.
`written`	`CollectionListWritten`	The views the engine wrote.

Values

`Written`	`CollectionListWritten`

Conforms to

Answer, Deinitable, Movable, Sized

__init__

def __init__(out self, arena: Int, generation: Int, written: CollectionListWritten, count: Int)

__len__The collections listed.

def __len__(self) -> Int

collectionsThe identifiers of the collections.

def collections(ref self) -> Span[CollectionID, origin_of(self)]

modalitiesWhat every collection holds.

def modalities(ref self) -> Span[Modality, origin_of(self)]

namesThe names, in the order of the identifiers, empty for a collection without one.

def names(self) -> Tape[origin]

StructCollectionsFoundThe collections a batch of names address, read in place from the arena a find borrows.5

struct CollectionsFound[origin: MutOrigin]

Parameters

`originMutOrigin`	comptime	The arena the answers live in, which this result borrows.

Fields

`arena`	`Pointer[Arena, origin]`	The arena holding the answers.
`generation`	`Int`	The arena's call the answers came from.
`written`	`CollectionFindWritten`	The views the engine wrote.
`count`	`Int`	Names the call resolved.

Values

`Written`	`CollectionFindWritten`

Conforms to

Answer, Deinitable, Movable, Sized

__init__

def __init__(out self, arena: Int, generation: Int, written: CollectionFindWritten, count: Int)

__len__The names resolved.

def __len__(self) -> Int

presentWhether a collection carries name index.

def present(self, index: Int) -> Bool

collectionsThe identifier every name addresses, nil where none does.

def collections(ref self) -> Span[CollectionID, origin_of(self)]

modalitiesWhat every addressed collection holds, NONE where no collection is.

def modalities(ref self) -> Span[Modality, origin_of(self)]

StructArenaDescriptionWhere an arena's outputs live, ustore_arena_description_t.1

struct ArenaDescription

Fields

`residency`	`Residency`	RAM for host pages, VRAM for one device's memory.
`device`	`Int32`	The ordinal of the device, as `Library.gpu_devices` lists it, or -1 for host pages.

Conforms to

Copyable, Defaultable, Deinitable, ImplicitlyCopyable, Movable

__init__Zeroes both fields, which is what a failed report leaves.

def __init__(out self)