Batches and Arenas | UStore for Python

§ Receivers & Deferred Calls

A receiver carries what every argument struct of the C ABI puts before its inputs: the view, the executor and the completion. A Database, Transaction or Snapshot runs its calls on the calling thread, on(executor) answers a ustore.On whose calls block on that executor, and deferred(executor) answers a ustore.DeferredOn whose calls submit there and answer a ustore.Deferred. The receiver’s type alone chooses the completion, so all three offer the same verbs with the same arguments, and receivers never change after they are made, so threads share them freely. Constructors address no database yet, so no receiver offers them: open_ram, open_rocksdb, view_rocksdb and open_leveldb take an executor= keyword and block on it, as they block on the calling thread without one. In a coroutine, await a deferred call; anywhere else, wait() blocks the thread with its state detached:

import asyncio


async def main(directory, keys, key, payloads):
    with ustore.Executor.for_ram(8) as executor:
        database = ustore.Database.open_rocksdb(directory, executor=executor)  # blocks on the executor
        arena = ustore.Arena(executor)                       # placed where the executor computes
        values = database.on(executor).read(keys, arena, collection="movies")  # blocking, on the calling thread
        poster = database.on(executor)["movies"].blobs[key]  # shorthand, copied out of a one-off arena

        later = database.deferred(executor)
        reading = later.read(keys, arena, collection="movies")  # ustore.Deferred, submitted now, holding the arena
        reading.status                                       # ustore.Status.DEFERRED until final
        values = await reading                               # or: reading.wait()
        poster = await later["movies"].blobs[key]            # one call at a time; a missing key raises KeyError

        transaction = database.transaction(ustore.Watch.KEYS)
        await transaction.deferred(executor).write(keys, payloads, collection="movies")
        peek = transaction.unwatched().read(keys, arena, collection="movies")  # recorded for no conflict
        read_stamp = transaction.stage()
        commit_stamp = await transaction.deferred(executor).commit(ustore.Durability.FLUSHED)
        transaction.close()

        with database.snapshot() as snapshot:
            old = snapshot.read(keys, arena, collection="movies")
            old_poster = snapshot["movies"].blobs[key]
            snapshot.read_stamp                              # sees every commit stamp at or below it
        executor.drain(ustore.Mood.SPINNING)
        database.close()

await hands wait() to loop.run_in_executor, so the thread it blocks belongs to asyncio, and status polls through ustore_outcome_status without waiting. Arguments the binding refuses raise at the call, while the engine’s refusals raise at await or wait(), as many times as they are asked. A collection name resolves on the calling thread when the call is made, and a mapping view creates a missing collection there too, so a deferred call never waits behind earlier ones to learn its collection. Python’s in must answer a bool, an assignment and del discard what they answer, and the table view and most graph methods chain several calls, so through a deferred view they raise TypeError naming the verb to call instead, such as contains for in.

async def fan_out(database, executors, keys, key, sources, targets):
    first, second, third = (database.deferred(executor) for executor in executors)  # one call per executor at once
    types = [ustore.FieldType.STRING, ustore.FieldType.I64]
    gathering = first.docs_gather(keys, ["name", "tweets"], types, ustore.Arena(executors[0]), collection="people")
    linking = second.graph_write_edges(sources, targets, collection="follows")
    present = third.contains(key, collection="movies")       # Deferred[bool], since `key in ...` must answer a bool
    gathered, linked, found = await gathering, await linking, await present
    document = await first["people"].docs[key]               # the parsed document
    edges = await second["follows"].graph.read_edges(keys)   # Neighborhoods over a one-off arena
    return gathered, linked, found, document, edges

A Deferred keeps the outcome, the inputs the library borrows, the output slots and its arena, since submission copies the argument struct and lets it go. It holds its arena as a blocking call does, until it is waited on or dropped, and dropping an unfinished one waits for its call. The collector frees a cycle through a finished one, and leaves a cycle through an unfinished one for a later collection, never clearing what the library still reads. An executor, a transaction and an arena each serve one call at a time, so a second call while a deferred one runs raises ContendedError once awaited. Closing a database, transaction or snapshot, or dropping an arena, waits in C for the deferred calls naming it.

§ Executors

An executor owns host threads, and a database owns its data, so one executor serves any number of databases. Executor.for_ram(threads=0, *, memory_domains=None) spawns the threads of the RAM, RocksDB and LevelDB engines near the NUMA nodes memory_domains names, every node the process may allocate on for None. It keeps the scratch of each thread on that thread’s node and every arena it makes on the first node named, and refuses a node no machine carries with InvalidArgumentError. Zero threads take 7/8 of the cores those nodes carry, leaving the rest to blocking calls, which run on their callers’ threads, and to the engines’ own background flushes and compactions:

executor = ustore.Executor.for_ram(8, memory_domains=[0])
executor.drain(ustore.Mood.SPINNING)                    # waits, then keeps idle threads hot
arena = ustore.Arena(executor)                          # outputs of calls on this executor land here

Executor.on_pool(pool, /, *, memory_domains=None) borrows a ForkUnion fu_pool_t another library already runs, given as the integer address ctypes or cffi hands over, so one process keeps one set of threads; the pool must outlive the executor. Executor.for_nvme(threads=0, *, transport=Transport.AUTOMATIC, **sizes) makes the I/O rings of the NVMe engine, and tells every database open_nvme opens on it how to move bytes: the transport, the channels and their buffers, each size keyword naming a field of ustore_nvme_options_t. Executor.for_vram(device, *, scratch_limit=0, gds=Gds.AUTOMATIC) drives one CUDA device through one stream every call queues on, whose merges Database.open_nvme(..., compactions=...) takes, and raises UnsupportedError in a build without CUDA.

An executor serves one call at a time: a call submitted while another holds it finishes with Status.CONTENDED and raises ContendedError once awaited. A deferred call runs on the executor’s first thread in the caller’s place, so polling status alone finishes it, and progress callbacks run on the executor’s threads, taking the GIL as they enter Python. Used as a context manager, an executor waits for its calls and closes on exit, after which a receiver naming it raises UninitializedError. Calling ustore.Executor() raises a TypeError naming the factories, since what an executor spawns cannot be derived from nothing.

The extension declares Py_MOD_GIL_NOT_USED, so free-threaded builds run without the interpreter lock. Critical sections fence the few fields the binding mutates: an arena’s exports and generation, a closed executor’s handle, a cursor’s handle while a pull holds it, a deferred call’s answer, and the identifier a collection resolved. A ragged input that is not already a tape is borrowed into views the call holds before it is submitted, so the accessor the executor’s threads call reads those views alone, never a Python container the caller may change meanwhile.

§ Progress & Cancellation

scan, scan_batch, a cursor’s next, compact and a snapshot’s save take progress=, a callable of the units the call finished and the units it finishes in all. The units are the verb’s own: scans for a scan, one pull for a cursor, bytes of keys and values for a save, and bytes or collections for a compaction, as the engine measures them. The library calls it from whichever thread runs the call, never two at once and never after the call is final, so a deferred call reports from the executor’s threads, and the binding attaches the interpreter there itself, taking the GIL where there is one. An answer of None or a truthy one carries on, and any other falsy answer cancels: the call unwinds, publishes nothing and raises CancelledError. A cancelled save removes what it wrote, a cancelled pull leaves its cursor where it was, and a cancelled compaction stops between collections, keeping what it compacted. An exception inside the callable cancels the call the same way, and re-raises from it in place of CancelledError, or from wait() and await for a deferred call.

stop = threading.Event()


def report(finished: int, total: int) -> bool:
    print(f"{finished} of {total}")
    return not stop.is_set()


database.compact(progress=report)
with database.snapshot() as snapshot:
    snapshot.save(directory, progress=report)           # reports on the calling thread
    snapshot.deferred(executor).save(elsewhere, progress=report).wait()  # and here from the executor's

§ Arenas

Every output whose length only the call knows, such as values, keys, columns, edges, degrees, bounds and names, lands in a ustore.Arena you pass, and the verb answers a view over it without copying. ustore.Arena(executor) places it where that executor computes, decided once, and ustore.Arena() makes host pages for calls on the calling thread. Each call rewinds its arena, so the previous call’s views go stale and a steady loop allocates once. To keep a result past the next call, or to read one while making the next, pass that call another arena. An arena serves one call at a time, so each deferred call needs its own. A NumPy array or memoryview over an output pins its arena as a memoryview pins a bytearray, so the next call naming that arena raises ContendedError until the export is released. A stale result raises UninitializedError when indexed, exported or asked for its lengths, counts or degrees. Values, Keys, Page and Neighborhoods export DLPack too, so numpy.from_dlpack(keys) and torch.from_dlpack(keys) read the arena in place, and __dlpack_device__ reports where the library placed it. Python reads every answer on the host, so a verb handed an arena in device memory raises DeviceError before it runs. A batch of keys is taken from __dlpack__ before the buffer protocol: packed 16-byte keys pass as they are from host, CUDA, ROCm or managed memory, and 64-bit integers convert where the host reads them.

arena = ustore.Arena()
for batch in batches:
    values = database.read(batch, arena, collection="movies")  # rewinds: the last batch's values are gone
    total += sum(length or 0 for length in values.lengths)
held = database.read(keys, arena, collection="movies")[0]  # a memoryview, pinning the arena
database.read(keys, ustore.Arena(), collection="movies")  # another arena serves the next call meanwhile
held.release()                                          # and this one serves calls again

read and docs_read answer ustore.Values, scan, scan_batch, sample and sample_batch answer ustore.Keys, a cursor’s next answers a ustore.Page, docs_gather answers ustore.Columns, and graph_read_edges answers ustore.Neighborhoods. measure, docs_gist, graph_degrees, collection_find, collection_list and collection_names take an arena too, and copy their small answers out of it.

Shorthand has no place for an arena, so it makes a one-off arena through ustore_arena_init for every call, copies what it read into Python objects and frees the arena with the call. That covers get, contains, key in view[name].blobs, view[name].blobs[key], .docs[key] and .docs_json[key], Collection.sample, and the NetworkX and Pandas views. Each such call pays for an arena and a copy, so a loop reaches for the verbs with an arena of its own instead.

API

Types

MoodWhat an executor's threads do once it next goes idle, valued as ustore_mood_t.

__init__.py:108 ↗

class Mood(IntEnum)

Values

`PARKED`	`0`
`SPINNING`	`1`

CPUClassThe CPU generation a database confines its waits, atomics and string kernels to, valued as ustore_cpu_class_t.

__init__.py:160 ↗

class CPUClass(IntEnum)

Values

`AUTOMATIC`	`0`
`SERIAL`	`1`
`INTEL_HASWELL`	`2`
`INTEL_SIERRA`	`3`
`INTEL_SKYLAKE`	`4`
`INTEL_ICELAKE`	`5`
`AWS_G2`	`6`
`APPLE_M2`	`7`
`AWS_G5`	`8`
`ALIBABA_C930`	`9`
`MONOVERSIONED`	`10`

TransportHow the NVMe engine moves bytes between its files and memory, valued as ustore_transport_t.

__init__.py:176 ↗

class Transport(IntEnum)

Values

`AUTOMATIC`	`0`
`BLOCKING`	`1`
`LINUX_URING`	`2`
`LINUX_AIO`	`3`
`LINUX_SPDK`	`4`

GdsHow an executor of Executor.for_vram moves bytes between the drives and its device, valued as ustore_gds_t.

__init__.py:205 ↗

class Gds(IntEnum)

Values

`AUTOMATIC`	`0`
`DIRECT`	`1`
`COMPATIBILITY`	`2`

GPUVendorThe vendor whose runtime drives a GPU, valued as ustore_gpu_vendor_t.

__init__.py:213 ↗

class GPUVendor(IntEnum)

Values

`NVIDIA`	`1`
`AMD`	`2`

GPUClassThe generation of a GPU, valued as ustore_gpu_class_t.

__init__.py:219 ↗

class GPUClass(IntEnum)

Values

`NVIDIA_AMPERE`	`1`
`NVIDIA_ADA`	`2`
`NVIDIA_HOPPER`	`3`
`NVIDIA_BLACKWELL`	`4`
`NVIDIA_BLACKWELLRTX`	`5`
`AMD_CDNA3`	`6`
`AMD_CDNA4`	`7`
`AMD_CDNA5`	`8`

ArenaThe memory every output whose length scales with a call lands in, rewound by the next call handed it.

__init__.py:364 ↗

class Arena

Every verb whose outputs scale with the call takes one as its last positional argument and answers results viewing it. A buffer exported over its outputs pins it, so the next call naming it raises ContendedError until the buffer is released, and a result read after a later call rewound it raises UninitializedError. A deferred call holds it until it is waited on or dropped.

ProgressCalled with the units a call finished and the units it finishes in all, from whichever thread runs it but never two at once; None or a truthy answer carries on, any other falsy one cancels, and a raise cancels and re-raises.

__init__.py:63 ↗

type Progress = Callable[[int, int], bool | None]

ClassExecutorThe threads that run calls, shared by any number of databases.6

lib.pyi:607 ↗

class Executor

for_ramHost threads for the RAM, RocksDB and LevelDB engines near memory_domains, every NUMA node for None, where zero threads take 7/8 of the cores those nodes carry.

lib.pyi:611 ↗

@classmethod
def for_ram(
    threads: int = 0,
    *,
    memory_domains: Sequence[int] | None = None,
    deferred_limit: int = 0,
) -> Self

Calls ustore_executor_for_ram.

on_poolThe threads of a ForkUnion fu_pool_t at address pool, which another library runs and which must outlive the executor.

lib.pyi:616 ↗

@classmethod
def on_pool(
    pool: int,
    /,
    *,
    memory_domains: Sequence[int] | None = None,
    deferred_limit: int = 0,
) -> Self

Calls ustore_executor_on_pool.

for_nvmeThreads each driving an I/O ring for the NVMe engine, telling every database Database.open_nvme opens on it how to move bytes, where every zero size keeps the engine's default.

lib.pyi:621 ↗

@classmethod
def for_nvme(
    threads: int = 0,
    *,
    transport: Transport = Transport.AUTOMATIC,
    deferred_limit: int = 0,
    shared_io_channels: int = 0,
    queue_depth: int = 0,
    request_buffer_bytes: int = 0,
    request_buffers_count: int = 0,
    stream_buffer_bytes: int = 0,
    stream_buffers_count: int = 0,
) -> Self

Calls ustore_executor_for_nvme.

for_vramOne stream on device, a GPUDevice.ordinal of either vendor, every call queues on, fed by one host thread, which Database.open_nvme takes as its compactions on an NVIDIA device, refused with DeviceError for an ordinal no device carries; zero scratch_limit lets scratch grow as calls ask.

lib.pyi:638 ↗

@classmethod
def for_vram(
    device: int,
    *,
    scratch_limit: int = 0,
    gds: Gds = Gds.AUTOMATIC,
    deferred_limit: int = 0,
) -> Self

Calls ustore_executor_for_vram.

drainWaits for every call submitted before the drain began, setting what the threads do once idle.

lib.pyi:652 ↗

def drain(mood: Mood = Mood.PARKED) -> None

closeWaits for every submitted call, then frees the threads.

lib.pyi:655 ↗

def close() -> None

ClassDeferredA call a deferred view submitted, which answers once it finishes, holding its arena until then.4

lib.pyi:665 ↗

class Deferred[T]

__class_getitem__Names what wait() answers, as Deferred[Values].

lib.pyi:669 ↗

def __class_getitem__(item: Any, /) -> GenericAlias

waitBlocks the thread until the call finishes, answering or raising what the blocking verb would.

lib.pyi:676 ↗

def wait() -> T

__await__Runs wait() on the running event loop's default executor, suspending the task meanwhile.

lib.pyi:679 ↗

def __await__() -> Generator[Any, None, T]

statusThe status of the call, Status.DEFERRED until it finishes, polled through ustore_outcome_status.

lib.pyi:673 ↗

status: Status

ClassGPUDeviceOne GPU this process can drive, as gpu_devices() lists it.7

lib.pyi:748 ↗

class GPUDevice(structseq[Any], tuple[int, GPUVendor, int, GPUClass, int, int, str])

ordinalThe ordinal Executor.for_vram names the device by, its position in gpu_devices().

lib.pyi:753 ↗

ordinal: int

vendorThe vendor whose runtime drives the device.

lib.pyi:757 ↗

vendor: GPUVendor

vendor_ordinalThe device's ordinal in its vendor's runtime, as nvidia-smi or rocm-smi list it.

lib.pyi:761 ↗

vendor_ordinal: int

gpu_classThe class of the device.

lib.pyi:765 ↗

gpu_class: GPUClass

compute_unitsStreaming multiprocessors or compute units.

lib.pyi:769 ↗

compute_units: int

memory_bytesDevice memory in bytes.

lib.pyi:773 ↗

memory_bytes: int

nameThe vendor's own name for the device.

lib.pyi:777 ↗

name: str

ClassOnWhat a database, transaction or snapshot addresses, with the executor its calls block on.68

lib.pyi:1755 ↗

class On

watchedA view of the same transaction whose calls record the keys they touch for conflicts.

lib.pyi:1762 ↗

def watched() -> On

unwatchedA view of the same transaction whose calls record nothing.

lib.pyi:1765 ↗

def unwatched() -> On

ingest_arrowLands every batch of an Arrow stream as one commit of its own at the head, answering the rows landed; a view of a transaction raises TypeError.

lib.pyi:1768 ↗

def ingest_arrow(
    source: ArrowSource,
    *,
    collection: CollectionLike,
    order: IngestOrder = 'sorted',
    durability: Durability | None = None,
) -> int

commitCommits the transaction on the executor, answering the commit stamp.

lib.pyi:1778 ↗

def commit(durability: Durability = Durability.BUFFERED) -> int

stageStages the transaction on the executor, answering the read stamp.

lib.pyi:1781 ↗

def stage() -> int

saveSaves the snapshot on the executor, refusing a view of anything else.

lib.pyi:1784 ↗

def save(
    path: PathLikeOrStr,
    /,
    *,
    progress: Progress | None = None,
) -> None

clearClears the database on the executor, refusing a view of a transaction or a snapshot.

lib.pyi:1787 ↗

def clear(mode: DropMode, /) -> None

compactCompacts the database on the executor, refusing a view of a transaction or a snapshot.

lib.pyi:1790 ↗

def compact(*, progress: Progress | None = None) -> None

flushFlushes the database on the executor, refusing a view of a transaction or a snapshot.

lib.pyi:1793 ↗

def flush() -> None

describeDescribes the database on the executor, refusing a view of a transaction or a snapshot.

lib.pyi:1796 ↗

def describe() -> Description

collection_findThe collection ID the name addresses, at the snapshot of a snapshot and at the head otherwise.

lib.pyi:1799 ↗

def collection_find(name: str, arena: Arena, /) -> UUID

collection_listThe IDs of every collection, at the snapshot of a snapshot and at the head otherwise.

lib.pyi:1802 ↗

def collection_list(arena: Arena, /) -> tuple[UUID, ...]

database

lib.pyi:1758 ↗

database: Database

executorThe executor the view's calls run on, where an arena for them belongs, or None for the calling thread.

lib.pyi:1759 ↗

executor: Executor | None

writeUpserts a batch of binary values in one call.

lib.pyi:1286 ↗

Inherited from _Writes

def write(
    keys: KeysLike,
    values: Sequence[ValueLike] | ValueLike | TapeLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

Every value is borrowed for the length of the call rather than copied, so a memory-mapped buffer reaches the engine untouched.

Raises: TypeError: A value is None or exports no buffer. Error: Whatever the engine reported.

Parameters

`keysKeysLike`		The keys to write.
`valuesSequence[ValueLike] \| ValueLike \| TapeLike`		One value per key, a tape of them, or a single bytes-like object broadcast to every key. A tape is an Arrow `binary`, `large_binary`, `string` or `large_string` array, such as `Values`, or a `(data, offsets)` tuple of buffers with unsigned 32-bit or 64-bit offsets, and passes without a copy. None is refused, since `remove` removes keys.
`collectionCollectionLike`		The collection, by identifier or by name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

setUpserts one binary value.

lib.pyi:1312 ↗

Inherited from _Writes

def set(
    key: KeyLike,
    value: ValueLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

Raises: TypeError: The value is None or exports no buffer.

Parameters

`keyKeyLike`		The key to write.
`valueValueLike`		The bytes to store, borrowed rather than copied.
`collectionCollectionLike`		The collection, by identifier or by name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

removeRemoves keys with their values, or every key of a range up to its key in ends.

lib.pyi:1331 ↗

Inherited from _Writes

def remove(
    keys: KeyLike | KeysLike,
    *,
    collection: CollectionLike,
    ends: KeyLike | KeysLike | None = None,
    durability: Durability = Durability.BUFFERED,
) -> None

docs_writeWrites a batch of JSON documents, or one field inside each of them.

lib.pyi:1340 ↗

Inherited from _Writes

def docs_write(
    keys: KeysLike | None,
    documents: Sequence[DocumentLike] | DocumentLike | TapeLike,
    *,
    collection: CollectionLike,
    field: str | None = None,
    modification: Modification = Modification.UPSERT,
    type: FieldType = FieldType.JSON,
    id_field: str | None = None,
    durability: Durability = Durability.BUFFERED,
) -> None

Every document is borrowed for the length of the call rather than copied.

Raises: TypeError: A document is None. MalformedError: A document does not parse, or its id_field holds no integer. NotFoundError: A field is written inside a document that does not exist. AlreadyExistsError: An insert names a document that already exists.

Parameters

`keysKeysLike \| None`		The keys to write; None reads every key from `id_field` of its document.
`documentsSequence[DocumentLike] \| DocumentLike \| TapeLike`		One document per key, a tape of them, or one document broadcast to every key. Text, bytes and a tape, as `write` takes one, are JSON already, while a dict, a list or a number inside a sequence is serialized. None is refused: `remove` removes whole documents, and a merge with a JSON null removes a field. Under a fixed-width `type`, a contiguous buffer of one scalar per key is a column, which reaches the store without being printed as JSON and parsed back.
`collectionCollectionLike`		The collection, by identifier or by name.
`fieldstr \| None`		A top-level key or a JSON Pointer such as '/user/name' to write inside every document; None writes whole documents.
`modificationModification`		An upsert, update or insert, an RFC 6902 `Modification.PATCH` or an RFC 7386 `Modification.MERGE`.
`typeFieldType`		How every document is spelled: `FieldType.JSON`, `FieldType.STRING` for a plain string, `FieldType.NULL`, or the raw bytes of `FieldType.BOOL`, `FieldType.F64`, `FieldType.F32`, `FieldType.I64` through `FieldType.U8`.
`id_fieldstr \| None`		The field holding every key when `keys` is None.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

docs_removeRemoves whole documents, or every document of a range up to its key in ends.

lib.pyi:1383 ↗

Inherited from _Writes

def docs_remove(
    keys: KeyLike | KeysLike,
    *,
    collection: CollectionLike,
    ends: KeyLike | KeysLike | None = None,
    durability: Durability = Durability.BUFFERED,
) -> None

strings_*_write× 2Upserts strings and the keys they map onto, one key per string.

lib.pyi:1392 ↗

Inherited from _Writes

def strings__write(
    strings: TextsLike,
    keys: KeyLike | KeysLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

strings_*_remove× 2Removes strings with their keys.

lib.pyi:1401 ↗

Inherited from _Writes

def strings__remove(
    strings: TextsLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

pages_*_import× 2Replaces whole pages with parsed markup, minting a key for every element.

lib.pyi:1405 ↗

Inherited from _Writes

def pages__import(
    keys: KeyLike | KeysLike,
    markup: TextsLike,
    *,
    collection: CollectionLike,
    encoding: PageEncoding = PageEncoding.XML,
    durability: Durability = Durability.BUFFERED,
    progress: Progress | None = None,
) -> None

import_arrowWrites every batch of an Arrow stream through the writes of the collection's modality, answering the rows written.

lib.pyi:1416 ↗

Inherited from _Writes

def import_arrow(
    source: ArrowSource,
    *,
    collection: CollectionLike,
    durability: Durability | None = None,
) -> int

pages_*_insert× 2Parses fragments into elements under parents after anchors, the root and the front where None, answering the key every element ended up with, given in elements or minted.

lib.pyi:1421 ↗

Inherited from _Writes

def pages__insert(
    keys: KeyLike | KeysLike,
    fragments: TextsLike,
    *,
    collection: CollectionLike,
    elements: KeyLike | KeysLike | None = None,
    parents: KeyLike | KeysLike | None = None,
    anchors: KeyLike | KeysLike | None = None,
    encoding: PageEncoding = PageEncoding.XML,
    durability: Durability = Durability.BUFFERED,
) -> tuple[UUID, ...]

pages_*_remove× 2Removes elements with their subtrees, where the page key or no elements removes the whole page, and every page of a range up to its key in ends.

lib.pyi:1435 ↗

Inherited from _Writes

def pages__remove(
    keys: KeyLike | KeysLike,
    elements: KeyLike | KeysLike | None = None,
    *,
    collection: CollectionLike,
    ends: KeyLike | KeysLike | None = None,
    durability: Durability = Durability.BUFFERED,
) -> None

pages_*_move× 2Moves elements with their subtrees under parents after anchors, keeping their keys.

lib.pyi:1446 ↗

Inherited from _Writes

def pages__move(
    keys: KeyLike | KeysLike,
    elements: KeyLike | KeysLike,
    *,
    collection: CollectionLike,
    parents: KeyLike | KeysLike | None = None,
    anchors: KeyLike | KeysLike | None = None,
    durability: Durability = Durability.BUFFERED,
) -> None

pages_*_splice× 2Replaces lengths bytes of the text of every element from starts on with texts.

lib.pyi:1457 ↗

Inherited from _Writes

def pages__splice(
    keys: KeyLike | KeysLike,
    elements: KeyLike | KeysLike,
    starts: LengthsLike,
    lengths: LengthsLike,
    texts: TextsLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

pages_set_*_set_attributes× 2Sets one attribute of an element per task, adding the ones it lacks.

lib.pyi:1469 ↗

Inherited from _Writes

def pages_set__set_attributes(
    keys: KeyLike | KeysLike,
    elements: KeyLike | KeysLike,
    fields: TextsLike,
    values: TextsLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

pages_remove_*_remove_attributes× 2Removes one attribute of an element per task.

lib.pyi:1480 ↗

Inherited from _Writes

def pages_remove__remove_attributes(
    keys: KeyLike | KeysLike,
    elements: KeyLike | KeysLike,
    fields: TextsLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

graph_write_edgesInserts a batch of edges, creating the vertices they connect.

lib.pyi:1490 ↗

Inherited from _Writes

def graph_write_edges(
    sources: KeysLike,
    targets: KeysLike,
    *,
    edges: KeysLike | None = None,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

An edge already present is kept, so writing the same batch twice changes nothing.

Parameters

`sourcesKeysLike`		The vertex every edge leaves.
`targetsKeysLike`		The vertex every edge enters.
`edgesKeysLike \| None`		The identifier of every edge, which tells apart several edges between one pair; None gives every edge `edge_id_default`.
`collectionCollectionLike`		The graph collection, by identifier or by name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

graph_remove_edgesRemoves a batch of edges and keeps the vertices they connected, even once isolated.

lib.pyi:1511 ↗

Inherited from _Writes

def graph_remove_edges(
    sources: KeysLike,
    targets: KeysLike,
    *,
    edges: KeysLike | None = None,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

Parameters

`sourcesKeysLike`		The vertex every edge leaves.
`targetsKeysLike`		The vertex every edge enters.
`edgesKeysLike \| None`		The identifier of every edge; None removes the edges that were given `edge_id_default`.
`collectionCollectionLike`		The graph collection, by identifier or by name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

graph_write_verticesInserts a batch of vertices without edges, keeping those already present.

lib.pyi:1531 ↗

Inherited from _Writes

def graph_write_vertices(
    vertices: KeysLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> None

Parameters

`verticesKeysLike`		The vertices to insert.
`collectionCollectionLike`		The graph collection, by identifier or name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

graph_remove_verticesRemoves a batch of vertices together with every edge they take part in.

lib.pyi:1542 ↗

Inherited from _Writes

def graph_remove_vertices(
    vertices: KeysLike,
    *,
    role: Role = Role.ANY,
    collection: CollectionLike,
    ends: KeysLike | None = None,
    durability: Durability = Durability.BUFFERED,
) -> None

With ends, every vertex starts a range removed up to its end, as remove takes them.

Parameters

`verticesKeysLike`		The vertices to remove, or the first vertex of every range.
`roleRole`		The role every vertex plays, which only a joining graph between two collections needs; `Role.ANY` otherwise.
`collectionCollectionLike`		The graph collection, by identifier or by name.
`endsKeysLike \| None`		The vertex every range stops before, one per vertex.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

__getitem__The collection name addresses.

lib.pyi:812 ↗

Inherited from _Reads

def __getitem__(name: str) -> Collection

readReads a batch of binary values in one call, which no sequence of single reads matches for throughput.

lib.pyi:815 ↗

Inherited from _Reads

def read(
    keys: KeysLike,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    offset: int = 0,
    limit: int | None = None,
) -> Values

Nothing is copied: the tape sits in the arena, and indexing the answer gives a memoryview over the stored bytes, or None for an absent key.

Returns: Values: One entry per key, in the order they were asked for. Raises: ContendedError: The arena serves another call or exports a buffer. Error: Whatever the engine reported.

Parameters

`keysKeysLike`		The keys to read, as a sequence, a contiguous buffer of 16-byte keys, which is read in place, or one of 64-bit integers.
`arenaArena`		Where the tape lands, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.
`offsetint`		Byte of every value the read starts at, where an offset past the end reads empty.
`limitint \| None`		Most bytes of every value to read from the offset, or None for the rest of it.

getCopies one value out of a one-off arena, which read with an arena of yours avoids.

lib.pyi:844 ↗

Inherited from _Reads

def get(
    key: KeyLike,
    *,
    collection: CollectionLike,
) -> bytes | None

containsReads one presence into a one-off arena.

lib.pyi:847 ↗

Inherited from _Reads

def contains(
    key: KeyLike,
    *,
    collection: CollectionLike,
) -> bool

cursorA walk over the keys of one collection from start, reading nothing until its first pull, whose every pull blocks as this receiver's calls do.

lib.pyi:850 ↗

Inherited from _Reads

def cursor(
    start: KeyLike | None = None,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    patterns: Sequence[str | bytes] | None = None,
    pattern_kind: PatternKind = PatternKind.REGEX,
    sensitivity: CaseSensitivity = CaseSensitivity.CASED,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Cursor

Calls ustore_blobs_cursor_init.

docs_cursorA walk over documents, keeping those filter matches.

lib.pyi:867 ↗

Inherited from _Reads

def docs_cursor(
    start: KeyLike | None = None,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    filter: str | bytes | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Cursor

Calls ustore_docs_cursor_init.

pages_cursorA walk over pages, keeping those holding a node of the XPath filter, whose pulls render whole pages into outputs_encoding when asked.

lib.pyi:881 ↗

Inherited from _Reads

def pages_cursor(
    start: KeyLike | None = None,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    filter: str | bytes | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
    outputs_encoding: PageEncoding = PageEncoding.XML,
) -> Cursor

Calls ustore_pages_cursor_init.

graph_vertices_cursorA walk over the vertices of one graph collection.

lib.pyi:897 ↗

Inherited from _Reads

def graph_vertices_cursor(
    start: KeyLike | None = None,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Cursor

Calls ustore_graph_vertices_cursor_init.

scanLists up to wanted keys from start towards end.

lib.pyi:910 ↗

Inherited from _Reads

def scan(
    start: KeyLike | None,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    progress: Progress | None = None,
    patterns: Sequence[str | bytes] | None = None,
    pattern_kind: PatternKind = PatternKind.REGEX,
    sensitivity: CaseSensitivity = CaseSensitivity.CASED,
    weights: Sequence[float] | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Keys

Values are not exported, so a read follows the scan, or a cursor() walks a collection with its values instead.

Returns: Keys: One run of keys, in the order of the direction. Raises: CancelledError: The progress callable stopped the scan.

Parameters

`startKeyLike \| None`		The first key the scan may return, or None for the first key in its direction.
`wantedint`		Most keys the scan returns.
`arenaArena`		Where the keys land, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.
`endKeyLike \| None`		The key the scan stops before, or None for no bound.
`directionScanDirection`		`ScanDirection.DESCENDING` walks down from `start`, largest key first.
`modeScanMode`		`ScanMode.UNORDERED` lets keys come out of order, removed or repeated, to speed up the read after the scan; no engine uses it yet.
`progressProgress \| None`		Called with the scans finished and the scans in all; a falsy answer other than None cancels the call.

scan_batchOne scan per start, reporting the scans finished to progress.

lib.pyi:950 ↗

Inherited from _Reads

def scan_batch(
    starts: KeysLike,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    ends: KeysLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    progress: Progress | None = None,
    patterns: Sequence[str | bytes] | None = None,
    pattern_kind: PatternKind = PatternKind.REGEX,
    sensitivity: CaseSensitivity = CaseSensitivity.CASED,
    weights: Sequence[float] | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Keys

sampleDraws keys uniformly at random from one collection, which is how a workload picks entries it has no list of.

lib.pyi:970 ↗

Inherited from _Reads

def sample(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Keys

Returns: Keys: One run of keys, in no particular order.

Parameters

`wantedint`		Most keys to draw.
`arenaArena`		Where the keys land, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.

sample_batchcount samples of up to wanted keys each, all drawn from the one collection named.

lib.pyi:981 ↗

Inherited from _Reads

def sample_batch(
    count: int,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Keys

measureEstimates what a key range holds without walking it, so the answers are bounds rather than counts.

lib.pyi:983 ↗

Inherited from _Reads

def measure(
    start: KeyLike | None,
    end: KeyLike | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Measurement

Returns: Measurement: The lower and upper bounds on the entries, the bytes of their values, and the space they take on disk.

Parameters

`startKeyLike \| None`		First key of the range, or None for the first key in the direction.
`endKeyLike \| None`		The key the range stops before, or None for no bound.
`arenaArena`		Where the bounds land before they are copied out, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.
`directionScanDirection`		`ScanDirection.DESCENDING` ranges down from `start`.

docs_readReads whole documents, or one field of each, as JSON text or as printed strings.

lib.pyi:1009 ↗

Inherited from _Reads

def docs_read(
    keys: KeysLike,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    field: str | None = None,
    outputs_type: FieldType = FieldType.JSON,
) -> Values

Whole documents read as JSON pass straight through from the engine, so nothing is parsed.

Returns: Values: One entry per key, None where the document or the field is absent.

Parameters

`keysKeysLike`		The keys to read.
`arenaArena`		Where the tape lands, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.
`fieldstr \| None`		A top-level key or a JSON Pointer to read inside every document; None reads whole documents.
`outputs_typeFieldType`		`FieldType.JSON` for JSON text, or `FieldType.STRING` to print scalars as text.

docs_gistLists every distinct path to a leaf across the requested documents, in the order they were first met, which is how a table learns the columns its documents hold.

lib.pyi:1033 ↗

Inherited from _Reads

def docs_gist(
    keys: KeysLike,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> tuple[str, ...]

Returns: tuple[str, ...]: One JSON Pointer per leaf, such as '/user/name'.

Parameters

`keysKeysLike`		The documents to inspect.
`arenaArena`		Where the paths land before they are copied out, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.

docs_gatherReads every field of every document into typed columns, converting each value on a best-effort basis and recording what was found, converted, or could not be.

lib.pyi:1045 ↗

Inherited from _Reads

def docs_gather(
    keys: KeysLike,
    fields: Sequence[str],
    outputs_types: FieldType | Sequence[FieldType],
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Columns

Returns: Columns: One column per field, each holding one entry per document.

Parameters

`keysKeysLike`		The documents, the rows of every column.
`fieldsSequence[str]`		Top-level keys or JSON Pointers, the columns of the result.
`outputs_typesFieldType \| Sequence[FieldType]`		One type per field, or one for every field: a fixed-width scalar from `FieldType.BOOL` to `FieldType.U8`, `FieldType.UUID`, `FieldType.STRING` or `FieldType.BINARY`. A `FieldType.F16` column exports as a half-precision view NumPy reads as float16, and a `FieldType.UUID` column as sixteen bytes per document.
`arenaArena`		Where the columns land, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.

docs_scanLists up to wanted document keys from start towards end, as scan lists the keys of blobs.

lib.pyi:1071 ↗

Inherited from _Reads

def docs_scan(
    start: KeyLike | None,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    progress: Progress | None = None,
    filter: str | bytes | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Keys

Documents are not exported, so a docs_read follows the scan.

Returns: Keys: One run of keys, in the order of the direction. Raises: CancelledError: The progress callable stopped the scan.

Parameters

`startKeyLike \| None`		The first key the scan may return, or None for the first key in its direction.
`wantedint`		Most keys the scan returns.
`arenaArena`		Where the keys land, rewound by this call.
`collectionCollectionLike`		The docs collection, by identifier or by name.
`endKeyLike \| None`		The key the scan stops before, or None for no bound.
`directionScanDirection`		Which way the scan walks, as `scan` takes it.
`modeScanMode`		In what order the keys come, as `scan` takes it.
`progressProgress \| None`		Called with the scans finished and the scans in all; a falsy answer other than None cancels the call.

docs_sampleUp to wanted document keys drawn at random, which a docs_read or a docs_gather follows.

lib.pyi:1106 ↗

Inherited from _Reads

def docs_sample(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Keys

docs_measureBounds on what a range of document keys holds, as measure reads them for blobs.

lib.pyi:1108 ↗

Inherited from _Reads

def docs_measure(
    start: KeyLike | None,
    end: KeyLike | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Measurement

strings_readthe key of every string, or None for a string the strings collection does not hold.

lib.pyi:1119 ↗

Inherited from _Reads

def strings_read(
    strings: TextsLike,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> tuple[UUID | None, ...]

strings_scanup to wanted strings starting with prefix, in the order of their bytes.

lib.pyi:1123 ↗

Inherited from _Reads

def strings_scan(
    prefix: str | bytes | None,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    start: str | bytes | None = None,
    end: str | bytes | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> tuple[str, ...]

strings_sampleup to wanted strings drawn at random.

lib.pyi:1136 ↗

Inherited from _Reads

def strings_sample(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> tuple[str, ...]

strings_measurebounds on what a range of strings holds.

lib.pyi:1138 ↗

Inherited from _Reads

def strings_measure(
    start: str | bytes | None,
    end: str | bytes | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Measurement

pages_*_read× 2Renders whole pages, or the subtrees of elements, one per task, None where a page or an element is absent.

lib.pyi:1149 ↗

Inherited from _Reads

def pages__read(
    keys: KeyLike | KeysLike,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    elements: KeyLike | KeysLike | None = None,
    outputs_encoding: PageEncoding = PageEncoding.XML,
) -> Values

pages_*_scan× 2Up to wanted page keys from start, keeping those holding a node of the XPath filter.

lib.pyi:1161 ↗

Inherited from _Reads

def pages__scan(
    start: KeyLike | None,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    progress: Progress | None = None,
    filter: str | bytes | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Keys

pages_sampleUp to wanted page keys drawn at random, which a pages_read follows.

lib.pyi:1178 ↗

Inherited from _Reads

def pages_sample(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Keys

pages_measureBounds on what a range of page keys holds, as measure reads them for blobs.

lib.pyi:1180 ↗

Inherited from _Reads

def pages_measure(
    start: KeyLike | None,
    end: KeyLike | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Measurement

graph_read_edgesReads every edge a batch of vertices takes part in.

lib.pyi:1191 ↗

Inherited from _Reads

def graph_read_edges(
    vertices: KeysLike,
    arena: Arena,
    /,
    *,
    role: Role = Role.ANY,
    collection: CollectionLike,
) -> Neighborhoods

The edges of one vertex come sorted by neighbour; with both roles the outgoing ones precede the incoming ones.

Returns: Neighborhoods: One run of (source, target, edge) triples per vertex, None where it is absent.

Parameters

`verticesKeysLike`		The vertices whose edges are read.
`arenaArena`		Where the degrees and the edges land, rewound by this call.
`roleRole`		`Role.SOURCE` for the edges a vertex leaves by, `Role.TARGET` for those it is entered by, or `Role.ANY` for both, which is how an undirected graph asks.
`collectionCollectionLike`		The graph collection, by identifier or by name.

graph_degreesCounts the edges of a batch of vertices without exporting them.

lib.pyi:1208 ↗

Inherited from _Reads

def graph_degrees(
    vertices: KeysLike,
    arena: Arena,
    /,
    *,
    role: Role = Role.ANY,
    collection: CollectionLike,
) -> tuple[int | None, ...]

Returns: tuple[int | None, ...]: The degree of every vertex, None where it is absent.

Parameters

`verticesKeysLike`		The vertices whose edges are counted.
`arenaArena`		Where the degrees land before they are copied out, rewound by this call.
`roleRole`		The role of every vertex, as `graph_read_edges` takes it.
`collectionCollectionLike`		The graph collection, by identifier or by name.

graph_containsWhether the vertex is present, read as its degree through a one-off arena.

lib.pyi:1222 ↗

Inherited from _Reads

def graph_contains(
    vertex: KeyLike,
    /,
    *,
    collection: CollectionLike,
) -> bool

graph_scan_verticesLists up to wanted vertices from start towards end, those without edges included.

lib.pyi:1224 ↗

Inherited from _Reads

def graph_scan_vertices(
    start: KeyLike | None,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    progress: Progress | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Keys

Edges are not exported, so a graph_read_edges follows the scan.

Returns: Keys: One run of vertices, in the order of the direction. Raises: CancelledError: The progress callable stopped the scan.

Parameters

`startKeyLike \| None`		The first vertex the scan may return, or None for the first vertex in its direction.
`wantedint`		Most vertices the scan returns.
`arenaArena`		Where the vertices land, rewound by this call.
`collectionCollectionLike`		The graph collection, by identifier or by name.
`endKeyLike \| None`		The vertex the scan stops before, or None for no bound.
`directionScanDirection`		Which way the scan walks, as `scan` takes it.
`modeScanMode`		In what order the vertices come, as `scan` takes it.
`progressProgress \| None`		Called with the scans finished and the scans in all; a falsy answer other than None cancels the call.

graph_sample_verticesUp to wanted vertices drawn at random, those without edges included.

lib.pyi:1258 ↗

Inherited from _Reads

def graph_sample_vertices(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Keys

graph_measure_verticesBounds on what a range of vertices holds, as measure reads them for blobs.

lib.pyi:1260 ↗

Inherited from _Reads

def graph_measure_vertices(
    start: KeyLike | None,
    end: KeyLike | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Measurement

onA view whose calls block on executor, after every call submitted to it before.

lib.pyi:1276 ↗

Inherited from _Receivers

def on(executor: Executor) -> On

deferredA view whose calls executor runs while each verb answers a Deferred at once.

lib.pyi:1279 ↗

Inherited from _Receivers

def deferred(executor: Executor) -> DeferredOn

ClassDeferredOnWhat a database, transaction or snapshot addresses, with the executor its calls go to, each verb answering a Deferred at once.53

lib.pyi:1805 ↗

class DeferredOn

Every pull of a cursor blocks, so it opens none.

__getitem__The collection name addresses, whose blobs[key] and docs[key] answer a Deferred.

lib.pyi:1813 ↗

def __getitem__(name: str) -> Collection

onon(executor) answers an On whose calls block on the executor.

lib.pyi:1816 ↗

def on(executor: Executor) -> On

Every call runs after the ones submitted to the executor before it finishes, so a read through it sees what earlier deferred writes wrote.

Parameters

`executorExecutor`		The threads that run the calls.

deferreddeferred(executor) answers a DeferredOn whose calls the executor runs meanwhile.

lib.pyi:1826 ↗

def deferred(executor: Executor) -> DeferredOn

Every verb of it submits its call and answers a Deferred at once.

Parameters

`executorExecutor`		The threads that run the calls.

watchedwatched() answers a view of the transaction whose calls record the keys they touch for conflicts.

lib.pyi:1835 ↗

def watched() -> DeferredOn

unwatchedunwatched() answers a view of the transaction whose calls record nothing, so they never fail its commit.

lib.pyi:1838 ↗

def unwatched() -> DeferredOn

readread(keys, arena, *, collection, offset=0, limit=None) answers a Values tape.

lib.pyi:1841 ↗

def read(
    keys: KeysLike,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    offset: int = 0,
    limit: int | None = None,
) -> Deferred[Values]

Reads a batch of binary values in one call, which no sequence of single reads matches for throughput. Nothing is copied: the tape sits in the arena, and indexing the answer gives a memoryview over the stored bytes, or None for an absent key.

Returns: Values: One entry per key, in the order they were asked for. Raises: ContendedError: The arena serves another call or exports a buffer. Error: Whatever the engine reported.

Parameters

`keysKeysLike`		The keys to read, as a sequence, a contiguous buffer of 16-byte keys, which is read in place, or one of 64-bit integers.
`arenaArena`		Where the tape lands, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.
`offsetint`		Byte of every value the read starts at, where an offset past the end reads empty.
`limitint \| None`		Most bytes of every value to read from the offset, or None for the rest of it.

getThe Deferred of a copy of one value, owning the one-off arena it reads into.

lib.pyi:1873 ↗

def get(
    key: KeyLike,
    *,
    collection: CollectionLike,
) -> Deferred[bytes | None]

containsThe Deferred of one presence, owning the one-off arena it reads into.

lib.pyi:1876 ↗

def contains(
    key: KeyLike,
    *,
    collection: CollectionLike,
) -> Deferred[bool]

scanscan(start, wanted, arena, *, collection, end=None, direction=ScanDirection.ASCENDING, mode=ScanMode.ORDERED, progress=None) answers a Keys tape.

lib.pyi:1879 ↗

def scan(
    start: KeyLike | None,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    progress: Progress | None = None,
    patterns: Sequence[str | bytes] | None = None,
    pattern_kind: PatternKind = PatternKind.REGEX,
    sensitivity: CaseSensitivity = CaseSensitivity.CASED,
    weights: Sequence[float] | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Deferred[Keys]

Lists up to wanted keys from start towards end. Values are not exported, so a read follows the scan, or a cursor() walks a collection with its values instead.

Returns: Keys: One run of keys, in the order of the direction. Raises: CancelledError: The progress callable stopped the scan.

Parameters

`startKeyLike \| None`		The first key the scan may return, or None for the first key in its direction.
`wantedint`		Most keys the scan returns.
`arenaArena`		Where the keys land, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.
`endKeyLike \| None`		The key the scan stops before, or None for no bound.
`directionScanDirection`		`ScanDirection.DESCENDING` walks down from `start`, largest key first.
`modeScanMode`		`ScanMode.UNORDERED` lets keys come out of order, removed or repeated, to speed up the read after the scan; no engine uses it yet.
`progressProgress \| None`		Called with the scans finished and the scans in all; a falsy answer other than None cancels the call.

scan_batchThe Deferred of one scan per start, whose progress runs on the executor's threads.

lib.pyi:1923 ↗

def scan_batch(
    starts: KeysLike,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    ends: KeysLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    progress: Progress | None = None,
    patterns: Sequence[str | bytes] | None = None,
    pattern_kind: PatternKind = PatternKind.REGEX,
    sensitivity: CaseSensitivity = CaseSensitivity.CASED,
    weights: Sequence[float] | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Deferred[Keys]

samplesample(wanted, arena, *, collection) answers a Keys tape.

lib.pyi:1943 ↗

def sample(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[Keys]

Draws keys uniformly at random from one collection, which is how a workload picks entries it has no list of.

Returns: Keys: One run of keys, in no particular order.

Parameters

`wantedint`		Most keys to draw.
`arenaArena`		Where the keys land, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.

sample_batchsample_batch(count, wanted, arena, *, collection) answers a Keys tape.

lib.pyi:1957 ↗

def sample_batch(
    count: int,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[Keys]

Draws count independent samples in one call, all from the one collection named, which is how a workload builds several random batches without paying for a call each.

Returns: Keys: One run of keys per sample, in no particular order.

Parameters

`countint`		Samples to draw.
`wantedint`		Most keys every sample draws.
`arenaArena`		Where the keys land, rewound by this call.
`collectionCollectionLike`		The one collection every sample draws from, by identifier or by name.

measuremeasure(start, end, arena, *, collection, direction=ScanDirection.ASCENDING) answers a Measurement.

lib.pyi:1973 ↗

def measure(
    start: KeyLike | None,
    end: KeyLike | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Deferred[Measurement]

Estimates what a key range holds without walking it, so the answers are bounds rather than counts.

Returns: Measurement: The lower and upper bounds on the entries, the bytes of their values, and the space they take on disk.

Parameters

`startKeyLike \| None`		First key of the range, or None for the first key in the direction.
`endKeyLike \| None`		The key the range stops before, or None for no bound.
`arenaArena`		Where the bounds land before they are copied out, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.
`directionScanDirection`		`ScanDirection.DESCENDING` ranges down from `start`.

docs_readdocs_read(keys, arena, *, collection, field=None, outputs_type=FieldType.JSON) answers a Values tape.

lib.pyi:2003 ↗

def docs_read(
    keys: KeysLike,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    field: str | None = None,
    outputs_type: FieldType = FieldType.JSON,
) -> Deferred[Values]

Reads whole documents, or one field of each, as JSON text or as printed strings. Whole documents read as JSON pass straight through from the engine, so nothing is parsed.

Returns: Values: One entry per key, None where the document or the field is absent.

Parameters

`keysKeysLike`		The keys to read.
`arenaArena`		Where the tape lands, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.
`fieldstr \| None`		A top-level key or a JSON Pointer to read inside every document; None reads whole documents.
`outputs_typeFieldType`		`FieldType.JSON` for JSON text, or `FieldType.STRING` to print scalars as text.

docs_gistdocs_gist(keys, arena, *, collection) answers a tuple of JSON Pointers.

lib.pyi:2031 ↗

def docs_gist(
    keys: KeysLike,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[tuple[str, ...]]

Lists every distinct path to a leaf across the requested documents, in the order they were first met, which is how a table learns the columns its documents hold.

Returns: tuple[str, ...]: One JSON Pointer per leaf, such as '/user/name'.

Parameters

`keysKeysLike`		The documents to inspect.
`arenaArena`		Where the paths land before they are copied out, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.

docs_gatherdocs_gather(keys, fields, outputs_types, arena, *, collection) answers Columns.

lib.pyi:2046 ↗

def docs_gather(
    keys: KeysLike,
    fields: Sequence[str],
    outputs_types: FieldType | Sequence[FieldType],
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[Columns]

Reads every field of every document into typed columns, converting each value on a best-effort basis and recording what was found, converted, or could not be.

Returns: Columns: One column per field, each holding one entry per document.

Parameters

`keysKeysLike`		The documents, the rows of every column.
`fieldsSequence[str]`		Top-level keys or JSON Pointers, the columns of the result.
`outputs_typesFieldType \| Sequence[FieldType]`		One type per field, or one for every field: a fixed-width scalar from `FieldType.BOOL` to `FieldType.U8`, `FieldType.UUID`, `FieldType.STRING` or `FieldType.BINARY`. A `FieldType.F16` column exports as a half-precision view NumPy reads as float16, and a `FieldType.UUID` column as sixteen bytes per document.
`arenaArena`		Where the columns land, rewound by this call.
`collectionCollectionLike`		The collection, by identifier or by name.

docs_scandocs_scan(start, wanted, arena, *, collection, end=None, direction=ScanDirection.ASCENDING, mode=ScanMode.ORDERED, progress=None) answers a Keys tape.

lib.pyi:2075 ↗

def docs_scan(
    start: KeyLike | None,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    progress: Progress | None = None,
    filter: str | bytes | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Deferred[Keys]

Lists up to wanted document keys from start towards end, as scan lists the keys of blobs. Documents are not exported, so a docs_read follows the scan.

Returns: Keys: One run of keys, in the order of the direction. Raises: CancelledError: The progress callable stopped the scan.

Parameters

`startKeyLike \| None`		The first key the scan may return, or None for the first key in its direction.
`wantedint`		Most keys the scan returns.
`arenaArena`		Where the keys land, rewound by this call.
`collectionCollectionLike`		The docs collection, by identifier or by name.
`endKeyLike \| None`		The key the scan stops before, or None for no bound.
`directionScanDirection`		Which way the scan walks, as `scan` takes it.
`modeScanMode`		In what order the keys come, as `scan` takes it.
`progressProgress \| None`		Called with the scans finished and the scans in all; a falsy answer other than None cancels the call.

docs_sampledocs_sample(wanted, arena, *, collection) answers a Keys tape.

lib.pyi:2115 ↗

def docs_sample(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[Keys]

Draws document keys uniformly at random from one collection, as sample draws the keys of blobs. Documents are not exported, so a docs_read or a docs_gather follows.

Returns: Keys: One run of keys, in no particular order.

Parameters

`wantedint`		Most keys to draw.
`arenaArena`		Where the keys land, rewound by this call.
`collectionCollectionLike`		The docs collection, by identifier or by name.

docs_measureThe Deferred of bounds on what a range of document keys holds.

lib.pyi:2129 ↗

def docs_measure(
    start: KeyLike | None,
    end: KeyLike | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Deferred[Measurement]

strings_readThe Deferred of the key of every string, or None for a string the strings collection does not hold.

lib.pyi:2140 ↗

def strings_read(
    strings: TextsLike,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[tuple[UUID | None, ...]]

strings_scanThe Deferred of up to wanted strings starting with prefix, in the order of their bytes.

lib.pyi:2144 ↗

def strings_scan(
    prefix: str | bytes | None,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    start: str | bytes | None = None,
    end: str | bytes | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Deferred[tuple[str, ...]]

strings_sampleThe Deferred of up to wanted strings drawn at random.

lib.pyi:2157 ↗

def strings_sample(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[tuple[str, ...]]

strings_measureThe Deferred of bounds on what a range of strings holds.

lib.pyi:2159 ↗

def strings_measure(
    start: str | bytes | None,
    end: str | bytes | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Deferred[Measurement]

pages_sampleThe Deferred of up to wanted page keys drawn at random.

lib.pyi:2202 ↗

def pages_sample(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[Keys]

pages_measureThe Deferred of bounds on what a range of page keys holds.

lib.pyi:2205 ↗

def pages_measure(
    start: KeyLike | None,
    end: KeyLike | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Deferred[Measurement]

graph_read_edgesgraph_read_edges(vertices, arena, *, role=Role.ANY, collection) answers Neighborhoods.

lib.pyi:2217 ↗

def graph_read_edges(
    vertices: KeysLike,
    arena: Arena,
    /,
    *,
    role: Role = Role.ANY,
    collection: CollectionLike,
) -> Deferred[Neighborhoods]

Reads every edge a batch of vertices takes part in. The edges of one vertex come sorted by neighbour; with both roles the outgoing ones precede the incoming ones.

Returns: Neighborhoods: One run of (source, target, edge) triples per vertex, None where it is absent.

Parameters

`verticesKeysLike`		The vertices whose edges are read.
`arenaArena`		Where the degrees and the edges land, rewound by this call.
`roleRole`		`Role.SOURCE` for the edges a vertex leaves by, `Role.TARGET` for those it is entered by, or `Role.ANY` for both, which is how an undirected graph asks.
`collectionCollectionLike`		The graph collection, by identifier or by name.

graph_degreesgraph_degrees(vertices, arena, *, role=Role.ANY, collection) answers a tuple.

lib.pyi:2237 ↗

def graph_degrees(
    vertices: KeysLike,
    arena: Arena,
    /,
    *,
    role: Role = Role.ANY,
    collection: CollectionLike,
) -> Deferred[tuple[int | None, ...]]

Counts the edges of a batch of vertices without exporting them.

Returns: tuple[int | None, ...]: The degree of every vertex, None where it is absent.

Parameters

`verticesKeysLike`		The vertices whose edges are counted.
`arenaArena`		Where the degrees land before they are copied out, rewound by this call.
`roleRole`		The role of every vertex, as `graph_read_edges` takes it.
`collectionCollectionLike`		The graph collection, by identifier or by name.

graph_containsgraph_contains(vertex, *, collection) answers a bool.

lib.pyi:2254 ↗

def graph_contains(
    vertex: KeyLike,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[bool]

Whether a vertex is present, read as its degree through a one-off arena, which a loop avoids with graph_degrees and an arena of its own.

Returns: bool: Whether the vertex is present.

Parameters

`vertexKeyLike`		The vertex to look for.
`collectionCollectionLike`		The graph collection, by identifier or by name.

graph_scan_verticesgraph_scan_vertices(start, wanted, arena, *, collection, end=None, direction=ScanDirection.ASCENDING, mode=ScanMode.ORDERED, progress=None) answers a Keys tape.

lib.pyi:2267 ↗

def graph_scan_vertices(
    start: KeyLike | None,
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    end: KeyLike | None = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    progress: Progress | None = None,
    predicate: Predicate | None = None,
    predicate_cost: PredicateCost = PredicateCost.CHEAP,
) -> Deferred[Keys]

Lists up to wanted vertices from start towards end, those without edges included. Edges are not exported, so a graph_read_edges follows the scan.

Returns: Keys: One run of vertices, in the order of the direction. Raises: CancelledError: The progress callable stopped the scan.

Parameters

`startKeyLike \| None`		The first vertex the scan may return, or None for the first vertex in its direction.
`wantedint`		Most vertices the scan returns.
`arenaArena`		Where the vertices land, rewound by this call.
`collectionCollectionLike`		The graph collection, by identifier or by name.
`endKeyLike \| None`		The vertex the scan stops before, or None for no bound.
`directionScanDirection`		Which way the scan walks, as `scan` takes it.
`modeScanMode`		In what order the vertices come, as `scan` takes it.
`progressProgress \| None`		Called with the scans finished and the scans in all; a falsy answer other than None cancels the call.

graph_sample_verticesThe Deferred of up to wanted vertices drawn at random.

lib.pyi:2306 ↗

def graph_sample_vertices(
    wanted: int,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
) -> Deferred[Keys]

graph_measure_verticesThe Deferred of bounds on what a range of vertices holds.

lib.pyi:2309 ↗

def graph_measure_vertices(
    start: KeyLike | None,
    end: KeyLike | None,
    arena: Arena,
    /,
    *,
    collection: CollectionLike,
    direction: ScanDirection = ScanDirection.ASCENDING,
) -> Deferred[Measurement]

collection_findcollection_find(name, arena) answers the identifier the name addresses.

lib.pyi:2321 ↗

def collection_find(
    name: str,
    arena: Arena,
    /,
) -> Deferred[UUID]

Reads the name at the snapshot of a snapshot, and at the head otherwise, since a transaction never creates or drops collections.

Returns: UUID: The identifier addressing the collection. Raises: NotFoundError: No collection carries the name.

Parameters

`namestr`		The name to resolve.
`arenaArena`		Where the lookup lands before it is copied out, rewound by this call.

collection_listcollection_list(arena) answers the identifiers of every collection.

lib.pyi:2337 ↗

def collection_list(
    arena: Arena,
    /,
) -> Deferred[tuple[UUID, ...]]

Lists the collections at the snapshot of a snapshot, and at the head otherwise. System collections are never listed, and collection_names answers the names.

Returns: tuple[UUID, ...]: One identifier per collection.

Parameters

`arenaArena`		Where the listing lands before it is copied out, rewound by this call.

savesave(path, *, progress=None) answers None.

lib.pyi:2350 ↗

def save(
    path: PathLikeOrStr,
    /,
    *,
    progress: Progress | None = None,
) -> Deferred[None]

Writes the snapshot out as a new database of the same engine, holding exactly the collections and names the snapshot records, which that engine's open then serves. RocksDB and LevelDB create the directory, the RAM engine writes its image into the directory the path names, and NVMe takes the path as the new database's manifest. Calls ustore_snapshot_save.

Raises: CancelledError: The progress callable stopped the save. UnsupportedError: The engine saves no snapshots.

Parameters

`pathPathLikeOrStr`		The directory the saved database lands in, or its manifest on NVMe.
`progressProgress \| None`		Called with the bytes of the keys and values saved and the bytes in all. A falsy answer other than None stops the save, which removes what it wrote.

clearclear(mode) answers None.

lib.pyi:2370 ↗

def clear(mode: DropMode, /) -> Deferred[None]

Empties every collection at once at the head, as collection_drop empties one. Calls ustore_database_clear.

Raises: InvalidArgumentError: The RAM and RocksDB engines drop no collection while a snapshot is open, since the snapshot belongs to its holder. ReadOnlyError: The database was opened read-only.

Parameters

`modeDropMode`		`DropMode.PAIRS` removes every key and value and keeps the collections, `DropMode.COLLECTION` drops every collection with its name, and `DropMode.VALUES` empties every value and keeps the keys.

compactcompact(*, progress=None) answers None.

lib.pyi:2386 ↗

def compact(
    *,
    progress: Progress | None = None,
) -> Deferred[None]

Reclaims the space overwritten and removed data still takes, one collection at a time: RocksDB and LevelDB flush and compact their trees, and the RAM engine frees the versions no reader needs and rewrites its image. Calls ustore_database_compact.

Raises: CancelledError: The progress callable stopped the compaction. ReadOnlyError: The database was opened read-only.

Parameters

`progressProgress \| None`		Called with the units compacted and the units in all, bytes where the engine measures them, as RocksDB does, and collections elsewhere. A falsy answer other than None stops between collections, keeping what was compacted.

flushflush() answers None.

lib.pyi:2403 ↗

def flush() -> Deferred[None]

Makes every commit that returned before this call durable, as if each had asked for Durability.FLUSHED. LevelDB syncs only its current log, so a commit in a log it already rotated stays unsynced until its compaction lands. Calls ustore_database_flush.

Raises

ReadOnlyError: The database was opened read-only.

describedescribe() answers a Description.

lib.pyi:2414 ↗

def describe() -> Deferred[Description]

Reports the engine serving the database, what it supports, its isolation, and the keys, memory and disk it holds, every size the engine's estimate and zero where it keeps none. Calls ustore_database_describe.

Returns

The capabilities, engine, isolation, keys, memory_bytes and disk_bytes of the database.

writewrite(keys, values, *, collection, durability=Durability.BUFFERED) answers None.

lib.pyi:2426 ↗

def write(
    keys: KeysLike,
    values: Sequence[ValueLike] | ValueLike | TapeLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> Deferred[None]

Upserts a batch of binary values in one call. Every value is borrowed for the length of the call rather than copied, so a memory-mapped buffer reaches the engine untouched.

Raises: TypeError: A value is None or exports no buffer. Error: Whatever the engine reported.

Parameters

`keysKeysLike`		The keys to write.
`valuesSequence[ValueLike] \| ValueLike \| TapeLike`		One value per key, a tape of them, or a single bytes-like object broadcast to every key. A tape is an Arrow `binary`, `large_binary`, `string` or `large_string` array, such as `Values`, or a `(data, offsets)` tuple of buffers with unsigned 32-bit or 64-bit offsets, and passes without a copy. None is refused, since `remove` removes keys.
`collectionCollectionLike`		The collection, by identifier or by name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

setset(key, value, *, collection, durability=Durability.BUFFERED) answers None.

lib.pyi:2455 ↗

def set(
    key: KeyLike,
    value: ValueLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> Deferred[None]

Upserts one binary value.

Raises: TypeError: The value is None or exports no buffer.

Parameters

`keyKeyLike`		The key to write.
`valueValueLike`		The bytes to store, borrowed rather than copied.
`collectionCollectionLike`		The collection, by identifier or by name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

removeremove(keys, *, collection, ends=None, durability=Durability.BUFFERED) answers None.

lib.pyi:2477 ↗

def remove(
    keys: KeyLike | KeysLike,
    *,
    collection: CollectionLike,
    ends: KeyLike | KeysLike | None = None,
    durability: Durability = Durability.BUFFERED,
) -> Deferred[None]

Removes a batch of keys with their values, or one key given on its own, while docs_remove removes documents. With ends, every key starts a range reaching up to its end, and every key of the range goes, all in one atomic call.

Parameters

`keysKeyLike \| KeysLike`		The keys to remove, or the first key of every range.
`collectionCollectionLike`		The collection, by identifier or by name.
`endsKeyLike \| KeysLike \| None`		The key every range stops before, one per key.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

docs_writedocs_write(keys, documents, *, collection, field=None, modification=Modification.UPSERT, type=FieldType.JSON, id_field=None, durability=Durability.BUFFERED) answers None.

lib.pyi:2501 ↗

def docs_write(
    keys: KeysLike | None,
    documents: Sequence[DocumentLike] | DocumentLike | TapeLike,
    *,
    collection: CollectionLike,
    field: str | None = None,
    modification: Modification = Modification.UPSERT,
    type: FieldType = FieldType.JSON,
    id_field: str | None = None,
    durability: Durability = Durability.BUFFERED,
) -> Deferred[None]

Writes a batch of JSON documents, or one field inside each of them. Every document is borrowed for the length of the call rather than copied.

Parameters

`keysKeysLike \| None`		The keys to write; None reads every key from `id_field` of its document.
`documentsSequence[DocumentLike] \| DocumentLike \| TapeLike`		One document per key, a tape of them, or one document broadcast to every key. Text, bytes and a tape, as `write` takes one, are JSON already, while a dict, a list or a number inside a sequence is serialized. None is refused: `remove` removes whole documents, and a merge with a JSON null removes a field. Under a fixed-width `type`, a contiguous buffer of one scalar per key is a column, which reaches the store without being printed as JSON and parsed back.
`collectionCollectionLike`		The collection, by identifier or by name.
`fieldstr \| None`		A top-level key or a JSON Pointer such as '/user/name' to write inside every document; None writes whole documents.
`modificationModification`		An upsert, update or insert, an RFC 6902 `Modification.PATCH` or an RFC 7386 `Modification.MERGE`.
`typeFieldType`		How every document is spelled: `FieldType.JSON`, `FieldType.STRING` for a plain string, `FieldType.NULL`, or the raw bytes of `FieldType.BOOL`, `FieldType.F64`, `FieldType.F32`, `FieldType.I64` through `FieldType.U8`.
`id_fieldstr \| None`		The field holding every key when `keys` is None.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

docs_removedocs_remove(keys, *, collection, ends=None, durability=Durability.BUFFERED) answers None.

lib.pyi:2548 ↗

def docs_remove(
    keys: KeyLike | KeysLike,
    *,
    collection: CollectionLike,
    ends: KeyLike | KeysLike | None = None,
    durability: Durability = Durability.BUFFERED,
) -> Deferred[None]

Removes a batch of whole documents, or one given on its own; a patch or a merge removes fields inside them instead. With ends, every key starts a range of documents removed up to its end, as remove takes them.

Parameters

`keysKeyLike \| KeysLike`		The keys of the documents to remove, or the first key of every range.
`collectionCollectionLike`		The docs collection, by identifier or by name.
`endsKeyLike \| KeysLike \| None`		The key every range stops before, one per key.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

import_arrowWrites every batch of an Arrow stream through the writes of the collection's modality.

lib.pyi:2597 ↗

def import_arrow(
    source: ArrowSource,
    *,
    collection: CollectionLike,
    durability: Durability | None = None,
) -> Deferred[int]

ingest_arrowLands every batch of an Arrow stream as one commit of its own at the head, refused through a transaction.

lib.pyi:2601 ↗

def ingest_arrow(
    source: ArrowSource,
    *,
    collection: CollectionLike,
    order: IngestOrder = 'sorted',
    durability: Durability | None = None,
) -> Deferred[int]

graph_write_edgesgraph_write_edges(sources, targets, *, edges=None, collection, durability=Durability.BUFFERED) answers None.

lib.pyi:2680 ↗

def graph_write_edges(
    sources: KeysLike,
    targets: KeysLike,
    *,
    edges: KeysLike | None = None,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> Deferred[None]

Inserts a batch of edges, creating the vertices they connect. An edge already present is kept, so writing the same batch twice changes nothing.

Parameters

`sourcesKeysLike`		The vertex every edge leaves.
`targetsKeysLike`		The vertex every edge enters.
`edgesKeysLike \| None`		The identifier of every edge, which tells apart several edges between one pair; None gives every edge `edge_id_default`.
`collectionCollectionLike`		The graph collection, by identifier or by name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

graph_remove_edgesgraph_remove_edges(sources, targets, *, edges=None, collection, durability=Durability.BUFFERED) answers None.

lib.pyi:2705 ↗

def graph_remove_edges(
    sources: KeysLike,
    targets: KeysLike,
    *,
    edges: KeysLike | None = None,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> Deferred[None]

Removes a batch of edges and keeps the vertices they connected, even once isolated.

Parameters

`sourcesKeysLike`		The vertex every edge leaves.
`targetsKeysLike`		The vertex every edge enters.
`edgesKeysLike \| None`		The identifier of every edge; None removes the edges that were given `edge_id_default`.
`collectionCollectionLike`		The graph collection, by identifier or by name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

graph_write_verticesgraph_write_vertices(vertices, *, collection, durability=Durability.BUFFERED) answers None.

lib.pyi:2729 ↗

def graph_write_vertices(
    vertices: KeysLike,
    *,
    collection: CollectionLike,
    durability: Durability = Durability.BUFFERED,
) -> Deferred[None]

Inserts a batch of vertices without edges, keeping those already present.

Parameters

`verticesKeysLike`		The vertices to insert.
`collectionCollectionLike`		The graph collection, by identifier or name.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

graph_remove_verticesgraph_remove_vertices(vertices, *, role=Role.ANY, collection, ends=None, durability=Durability.BUFFERED) answers None.

lib.pyi:2744 ↗

def graph_remove_vertices(
    vertices: KeysLike,
    *,
    role: Role = Role.ANY,
    collection: CollectionLike,
    ends: KeysLike | None = None,
    durability: Durability = Durability.BUFFERED,
) -> Deferred[None]

Removes a batch of vertices together with every edge they take part in. With ends, every vertex starts a range removed up to its end, as remove takes them.

Parameters

`verticesKeysLike`		The vertices to remove, or the first vertex of every range.
`roleRole`		The role every vertex plays, which only a joining graph between two collections needs; `Role.ANY` otherwise.
`collectionCollectionLike`		The graph collection, by identifier or by name.
`endsKeysLike \| None`		The vertex every range stops before, one per vertex.
`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

commitcommit(durability=Durability.BUFFERED) answers the commit stamp.

lib.pyi:2771 ↗

def commit(
    durability: Durability = Durability.BUFFERED,
) -> Deferred[int]

Applies every staged change, or none of them. The contents are kept whatever the outcome, so a rejected transaction can be inspected or replayed.

Returns: int: The commit stamp, this commit's position in commit order, which every snapshot whose read stamp is at or above it sees. Raises: ConflictError: A concurrent writer touched what this transaction watched.

Parameters

`durabilityDurability`		`Durability.FLUSHED` reaches the drive before returning.

stagestage() answers the read stamp.

lib.pyi:2787 ↗

def stage() -> Deferred[int]

Runs the first phase of a two-phase commit, after which a commit publishes the work. Staging reserves no position in commit order.

Returns

The read stamp, the stamp the transaction reads at and its commit validates against, which is no greater than the commit stamp the commit then answers.

database

lib.pyi:1809 ↗

database: Database

executorThe executor the view's calls go to, where an arena for them belongs.

lib.pyi:1810 ↗

executor: Executor | None

Functions

gpu_devicesEvery GPU this process can drive, NVIDIA devices first, then AMD, each at the ordinal Executor.for_vram names it by; empty on a machine without GPUs or their runtimes.

__init__.py:79 ↗

def gpu_devices() -> tuple[GPUDevice, ...]

Calls ustore_gpu_devices.