Collections

§ Keys

A key is a uuid.UUID, its text, sixteen raw bytes, or a non-negative integer read as uuid.UUID(int=n), so integer keys order as integers do. Keys, vertices and collection IDs come back as uuid.UUID, and a key batch passes without a copy as a contiguous array of 16-byte records, such as NumPy’s V16 or an (n, 16) uint8 array, which is also how np.asarray reads a Keys or Neighborhoods tape. A buffer of 64-bit integers converts into keys one by one, and any other sequence converts element by element.

§ Collections, Modes & Stamps

Every C enum a caller meets is an enum.IntEnum of ustore: Status, Mood, CPUClass, Watch, Durability, DropMode, ScanMode, ScanDirection, Modality, Isolation, Transport, Engine, Role, FieldType and Modification. The module builds each one at import through the C _name functions, valued as the enumerators and named by their canonical spellings in upper case, dashes as underscores, so “strict-serializable” is Isolation.STRICT_SERIALIZABLE and “read-only” is Status.READ_ONLY. A verb takes any int that is an enumerator, refusing a bool, which would read as zero or one, and text. Error.status and Deferred.status are Status members, measure() answers a Measurement struct sequence, database.capabilities a Capabilities one of transactions and snapshots, and Columns.types holds FieldType members.

describe() answers a Description struct sequence of the capabilities, the engine, the isolation, and the keys, memory_bytes and disk_bytes the engine estimates, zero where it keeps no estimate. Its pin_refused_bytes and crossing_requests report where the NVMe engine went unpinned: the arena bytes the locked-memory cap refused to pin, and the requests that crossed a gibibyte of a pinned arena. clear(mode) empties every collection at once, as collection_drop empties one, and compact() reclaims the space overwritten and removed data takes, one collection at a time. A snapshot’s save(path) writes it out as a new database of the same engine, holding exactly the collections and names the snapshot records:

database.describe().engine                              # ustore.Engine.ROCKSDB
database.clear(ustore.DropMode.PAIRS)                   # every pair goes, the collections and their names stay
database.compact(progress=report)
with database.snapshot() as snapshot:
    snapshot.save(directory)                            # RocksDB and LevelDB create it, RAM writes into it

Every other field of the C ABI’s argument structs that a caller chooses, such as collection, durability or role, is a keyword, while a verb whose only option is a mode, such as transaction(watch), commit(durability), drain(mood) or collection_drop(collection, mode), takes it by position too. No collection exists until collection_create(name, modality=...) makes it to hold one modality, and names starting with _ are reserved for the system collections, which no listing shows. Every verb names its collection as a uuid.UUID identifier or a name resolved on the calling thread, and database["movies"] answers a Collection whose blobs, docs, graph and table views create it on their first write.

database.set(key, value, collection="movies", durability=ustore.Durability.FLUSHED)
database.collection_drop("movies", ustore.DropMode.PAIRS)

Stamps are plain ints of two kinds. stage() answers the read stamp, the stamp a transaction reads at and its commit validates against. commit() answers the commit stamp, the commit’s position in commit order, which every snapshot whose read stamp is at or above it sees. Snapshot.read_stamp is the stamp a snapshot reads at, so before.read_stamp < commit_stamp <= after.read_stamp for snapshots taken around a commit. Staging reserves no position in commit order, so a read stamp is never greater than the commit stamp that follows it.

changes_cursor(since, *, collection) opens a feed of the changes committed to one collection after a commit stamp, oldest first, pinning that stamp as a snapshot does:

with database.changes_cursor(commit_stamp, collection="movies") as feed:
    while (changes := feed.next(1024, arena, values=True)).keys:  # an empty pull reached the newest commit
        for key, stamp, kind in zip(changes.keys, changes.stamps, changes.kinds):
            consume(key, stamp, kind)  # a ChangeKind: WRITE, REMOVAL or CHANGE

A Changes tuple carries the keys as a Page, their Values when asked, and tuples of commit stamps and ChangeKind members, where a range removal comes as the removal of every key it removed. A feed whose history is already gone raises WriteConflictError, and LevelDB, which keeps no stamps, raises UnsupportedError.