Quickstart | UStore for Python

Every verb whose outputs scale with the call takes a ustore.Arena as its last positional argument and answers results viewing it:

import numpy as np
import ustore
from ustore.graph_view import DiGraph
from ustore.table_view import Table

with ustore.Database.open_ram() as database:
    arena = ustore.Arena()                              # host pages for calls on the calling thread
    blobs = database.collection_create("blobs", modality=ustore.Modality.BLOBS)  # none exists until created
    database.write([1, 2], [b"a", b"bb"], collection=blobs)
    values = database.read([1, 2], arena, collection=blobs)  # Values, indexed as memoryviews over the arena
    database.scan_batch([1, 100], 16, arena, collection=blobs)  # Keys, rewinding the arena: `values` goes stale
    with database.cursor(collection=blobs) as cursor:   # a walk over one collection, page by page
        while page := cursor.next(1024, arena, values=True):
            list(page), page.values                     # UUID keys and their Values, in one call per page

    people = database.collection_create("people", modality=ustore.Modality.DOCS)
    database.docs_write([10, 11], ['{"name": "Lex", "tweets": 2221}', '{"name": "Joe"}'], collection=people)
    database.docs_gist([10, 11], arena, collection=people)  # ("/name", "/tweets")
    types = [ustore.FieldType.STRING, ustore.FieldType.I64]
    columns = database.docs_gather([10, 11], ["name", "tweets"], types, arena, collection=people)
    columns[1], columns.validities(1)                   # memoryview of "q", bitmap bytes
    prices = np.array([1.5, 2.5], dtype=np.float64)
    database.docs_write([10, 11], prices, field="price", type=ustore.FieldType.F64, collection=people)

    follows = database.collection_create("follows", modality=ustore.Modality.GRAPH)
    database.graph_write_edges(np.array([1, 2]), np.array([2, 3]), collection=follows)
    neighborhoods = database.graph_read_edges([1, 2, 3], arena, role=ustore.Role.ANY, collection=follows)
    np.asarray(neighborhoods)                           # (edges, 3, 16) bytes of source, target, edge

    database.get(1, collection=blobs), 1 in database["blobs"].blobs  # one-off arena copies: b"a", True
    graph = DiGraph(database, "graph", nodes="nodes", edges="edges")
    graph.add_edge(1, 2, weight=3)
    list(graph.edges(data=True))                        # [(UUID(int=1), UUID(int=2), {"weight": 3})]
    Table(database, people).astype({"tweets": "int64"}).to_pandas(page=1 << 16)

A document or a vertex is a value like any other, so documents, graphs and binary values each keep collections of their own.

API

Types

EngineThe engine serving a database, as describe() reports it, valued as ustore_engine_t.

__init__.py:231 ↗

class Engine(IntEnum)

Values

`RAM`	`0`
`ROCKSDB`	`1`
`LEVELDB`	`2`
`NVME`	`3`

PathLikeOrStr

__init__.py:61 ↗

type PathLikeOrStr = str | bytes | PathLike[str]

DataDirectory

__init__.py:62 ↗

type DataDirectory = PathLikeOrStr | tuple[PathLikeOrStr, int]

ClassDatabaseAn embedded database, opened through one class method per engine.75

lib.pyi:1566 ↗

class Database

open_ramAn in-memory database, persisted as one image when it names a directory, opened blocking on executor and confined to cpu_class.

lib.pyi:1581 ↗

@classmethod
def open_ram(
    directory: PathLikeOrStr | None = None,
    *,
    isolation: Isolation = Isolation.STRICT_SERIALIZABLE,
    executor: Executor | None = None,
    cpu_class: CPUClass = CPUClass.AUTOMATIC,
) -> Self

open_rocksdbA database on RocksDB, whose table files may spread over data directories, opened blocking on executor.

lib.pyi:1593 ↗

@classmethod
def open_rocksdb(
    directory: PathLikeOrStr,
    *,
    data_directories: Sequence[DataDirectory] = (),
    executor: Executor | None = None,
) -> Self

view_rocksdbA read-only database on RocksDB, refusing every change with ReadOnlyError while snapshots and their saves still serve, opened blocking on executor.

lib.pyi:1603 ↗

@classmethod
def view_rocksdb(
    directory: PathLikeOrStr,
    *,
    data_directories: Sequence[DataDirectory] = (),
    executor: Executor | None = None,
) -> Self

open_leveldbA database on LevelDB, opened blocking on executor.

lib.pyi:1614 ↗

@classmethod
def open_leveldb(
    directory: PathLikeOrStr,
    *,
    executor: Executor | None = None,
) -> Self

open_nvmeA database on the NVMe engine, named by its manifest, <database>.ustore.json in an existing directory or the raw address of its first slot, where every zero size keeps the engine's default, opened blocking on executor, which tells it how to move bytes when Executor.for_nvme made it, merging on the device of compactions when Executor.for_vram made it.

lib.pyi:1618 ↗

@classmethod
def open_nvme(
    manifest: PathLikeOrStr,
    *,
    executor: Executor | None = None,
    data_directories: Sequence[DataDirectory] = (),
    compactions: Executor | None = None,
    cpu_class: CPUClass = CPUClass.AUTOMATIC,
    memory_limit: int = 0,
    transaction_max_bytes: int = 0,
    transaction_max_deltas: int = 0,
    collection_concurrency_limit: int = 0,
    collection_cache_limit: int = 0,
    collection_memory_runs_max_bytes: int = 0,
    collection_memory_runs_max_deltas: int = 0,
    collection_level_enlarge_factor: int = 0,
    collection_value_size: int = 0,
    collection_value_max_size: int = 0,
) -> Self

ingest_arrowLands every batch of an Arrow stream as one commit of its own at the head, answering the rows landed.

lib.pyi:1571 ↗

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

closeCloses the database once every deferred call on it finished, while its open transactions and snapshots keep working, each holding the database open until it closes too.

lib.pyi:1649 ↗

def close() -> None

clearEmpties every collection at once: its pairs, every collection with its name, or its values.

lib.pyi:1653 ↗

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

compactReclaims the space overwritten and removed data takes, one collection at a time, reporting bytes where the engine measures them and collections elsewhere.

lib.pyi:1656 ↗

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

flushMakes every commit that returned before the call durable, as if each had asked for Durability.FLUSHED.

lib.pyi:1660 ↗

def flush() -> None

describeThe engine, its capabilities and isolation, and the keys, memory and disk it holds.

lib.pyi:1663 ↗

def describe() -> Description

collection_createCreates an empty collection holding modality and records the name for it, which may not start with _.

lib.pyi:1666 ↗

def collection_create(name: str, *, modality: Modality) -> UUID

collection_findThe collection ID the name addresses.

lib.pyi:1669 ↗

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

collection_containsWhether a collection carries the name, read into a one-off arena.

lib.pyi:1672 ↗

def collection_contains(name: str) -> bool

collection_listThe IDs of every collection, never a system one.

lib.pyi:1675 ↗

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

collection_namesOne page of the names recorded for collections, in the order of their text.

lib.pyi:1678 ↗

def collection_names(
    arena: Arena,
    /,
    *,
    after: str | None = None,
    limit: int = 1024,
) -> tuple[str, ...]

collection_dropRemoves a collection, or empties its pairs or its values.

lib.pyi:1681 ↗

def collection_drop(
    collection: UUID | str,
    mode: DropMode = DropMode.COLLECTION,
) -> None

snapshotPins a point-in-time state of the whole database, which the snapshot's read verbs see.

lib.pyi:1684 ↗

def snapshot() -> Snapshot

changes_cursorA feed of the changes committed to collection after the commit stamp since, oldest first.

lib.pyi:1687 ↗

def changes_cursor(
    since: int = 0,
    /,
    *,
    collection: CollectionLike,
) -> ChangesCursor

transactionBegins a transaction over this database, recording the keys its verbs touch unless Watch.NONE.

lib.pyi:1690 ↗

def transaction(watch: Watch = Watch.KEYS) -> Transaction

capabilities

lib.pyi:1569 ↗

capabilities: Capabilities

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_writeUpserts 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_removeRemoves strings with their keys.

lib.pyi:1401 ↗

Inherited from _Writes

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

pages_importReplaces 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_insertParses 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_removeRemoves 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_moveMoves 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_spliceReplaces 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_attributesSets one attribute of an element per task, adding the ones it lacks.

lib.pyi:1469 ↗

Inherited from _Writes

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

pages_remove_attributesRemoves one attribute of an element per task.

lib.pyi:1480 ↗

Inherited from _Writes

def pages_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_readRenders 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_scanUp 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