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

`from ustore import KeyRuns, UUID, Key, …`

## CollectionsView

A strided run of collections, `ustore_collections_view_t`.

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

## KeyRuns

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

```mojo
struct KeyRuns[origin: MutOrigin]
```

- `origin` (comptime): The arena the keys live in, which this result borrows.

- `Written` = `KeyRunsWritten`
- `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.

Conforms to: `Answer`, `Deinitable`, `Movable`, `Sized`

## __init__

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

## __len__

The runs, one per task.

```mojo
def __len__(self) -> Int
```

## offsets

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

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

## keys

Every run's keys end to end.

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

## run

The keys of task `index`.

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

## scores

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

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

## UUID

Sixteen bytes naming one thing everywhere, ordered as their bytes, `ustore_uuid_t`.

```mojo
struct UUID
```

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

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `Writable`

## __init__

The nil UUID.

```mojo
def __init__(out self)
```

```mojo
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__

Whether every byte matches.

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

## __ne__*__ne__

Whether any byte differs.

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

## write_to

Writes the canonical hyphenated lowercase hex spelling.

```mojo
def write_to(self, mut writer: T)
```

## Key

The identifier of a value within one collection, `ustore_key_t`.

```mojo
struct Key
```

- `uuid` `UUID`: The sixteen bytes.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `Writable`

## __init__

The nil key.

```mojo
def __init__(out self)
```

```mojo
def __init__(out self, value: UInt64)
```

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

## write_*_to

Writes the UUID spelling.

```mojo
def write__to(self, mut writer: T)
```

## CollectionID

The identifier of a collection, a UUIDv7 its create mints once, `ustore_collection_id_t`.

```mojo
struct CollectionID
```

- `Written` = `CollectionID`
- `uuid` `UUID`: The sixteen bytes; nil names no collection.

Conforms to: `Answer`, `Copyable`, `Defaultable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `Writable`

## __init__

The nil identifier, which names no collection.

```mojo
def __init__(out self)
```

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

Adopts the identifier a create wrote.

## DropMode

What dropping a collection removes, `ustore_drop_mode_t`.

```mojo
struct DropMode
```

- `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.
- `code` `c_int`: The raw `ustore_drop_mode_t` value the ABI exchanges.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## Modality

What a collection holds, `ustore_modality_t`; zero names none.

```mojo
struct Modality
```

- `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.
- `code` `c_int`: The raw `ustore_modality_t` value the ABI exchanges.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## Capabilities

Capabilities an engine reports, `ustore_capabilities_t`, as flags.

```mojo
struct Capabilities
```

- `TRANSACTIONS` = `Capabilities(Int32(1))`: The engine supports transactions.
- `SNAPSHOTS` = `Capabilities(Int32(4))`: The engine supports snapshots.
- `code` `c_int`: The raw flags.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## contains

Whether every flag `other` names is set.

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

## DatabaseDescription

What an open database reports about itself in one call, `ustore_database_description_t`.

```mojo
struct DatabaseDescription
```

- `Written` = `DatabaseDescription`
- `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.

Conforms to: `Answer`, `Copyable`, `Defaultable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __init__

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

```mojo
def __init__(out self)
```

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

Adopts the description a call wrote.

## CollectionList

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

```mojo
struct CollectionList[origin: MutOrigin]
```

- `origin` (comptime): The arena the listing lives in, which this result borrows.

- `Written` = `CollectionListWritten`
- `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.

Conforms to: `Answer`, `Deinitable`, `Movable`, `Sized`

## __init__

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

## __len__

The collections listed.

```mojo
def __len__(self) -> Int
```

## collections

The identifiers of the collections.

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

## modalities

What every collection holds.

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

## names

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

```mojo
def names(self) -> Tape[origin]
```

## CollectionsFound

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

```mojo
struct CollectionsFound[origin: MutOrigin]
```

- `origin` (comptime): The arena the answers live in, which this result borrows.

- `Written` = `CollectionFindWritten`
- `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.

Conforms to: `Answer`, `Deinitable`, `Movable`, `Sized`

## __init__

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

## __len__

The names resolved.

```mojo
def __len__(self) -> Int
```

## present

Whether a collection carries name `index`.

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

## collections

The identifier every name addresses, nil where none does.

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

## modalities

What every addressed collection holds, [`NONE`](https://www.unum.cloud/docs/ustore/mojo/transactions.md#NONE) where no collection is.

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

## ArenaDescription

Where an arena's outputs live, `ustore_arena_description_t`.

```mojo
struct ArenaDescription
```

- `residency` `Residency`: RAM for host pages, VRAM for one device's memory.
- `device` `Int32`: The ordinal of the device, as [`Library.gpu_devices`](https://www.unum.cloud/docs/ustore/mojo/platform-notes.md#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.

```mojo
def __init__(out self)
```