class SnapshotAPI
ClassSnapshotA point-in-time state of the whole database, whose read verbs see what it pinned.41
saveWrites the snapshot out as a new database of the same engine, holding exactly the collections it records, reporting the bytes of keys and values saved; a cancelled save removes what it wrote.
def save(
path: PathLikeOrStr,
/,
*,
progress: Progress | None = None,
) -> Nonecollection_findThe collection ID the name addresses at this snapshot.
def collection_find(name: str, arena: Arena, /) -> UUIDcollection_listThe IDs of every collection at this snapshot, never a system one.
def collection_list(arena: Arena, /) -> tuple[UUID, ...]closeReleases the snapshot once its deferred calls finished, unpinning the versions only it kept.
def close() -> Nonedatabase
database: Databaseread_stampThe stamp the snapshot reads at: it sees every commit whose commit stamp is at or below it, and none above.
read_stamp: int__getitem__The collection name addresses.
readReads a batch of binary values in one call, which no sequence of single reads matches for throughput.
Inherited from _Reads
def read(
keys: KeysLike,
arena: Arena,
/,
*,
collection: CollectionLike,
offset: int = 0,
limit: int | None = None,
) -> ValuesNothing 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.
Inherited from _Reads
def get(
key: KeyLike,
*,
collection: CollectionLike,
) -> bytes | NonecontainsReads one presence into a one-off arena.
Inherited from _Reads
def contains(
key: KeyLike,
*,
collection: CollectionLike,
) -> boolcursorA 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.
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,
) -> CursorCalls ustore_blobs_cursor_init.
docs_cursorA walk over documents, keeping those filter matches.
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,
) -> CursorCalls 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.
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,
) -> CursorCalls ustore_pages_cursor_init.
graph_vertices_cursorA walk over the vertices of one graph collection.
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,
) -> CursorCalls ustore_graph_vertices_cursor_init.
scanLists up to wanted keys from start towards end.
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,
) -> KeysValues 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.
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,
) -> KeyssampleDraws keys uniformly at random from one collection, which is how a workload picks entries it has no list of.
Inherited from _Reads
def sample(
wanted: int,
arena: Arena,
/,
*,
collection: CollectionLike,
) -> KeysReturns: 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.
Inherited from _Reads
def sample_batch(
count: int,
wanted: int,
arena: Arena,
/,
*,
collection: CollectionLike,
) -> KeysmeasureEstimates what a key range holds without walking it, so the answers are bounds rather than counts.
Inherited from _Reads
def measure(
start: KeyLike | None,
end: KeyLike | None,
arena: Arena,
/,
*,
collection: CollectionLike,
direction: ScanDirection = ScanDirection.ASCENDING,
) -> MeasurementReturns: 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.
Inherited from _Reads
def docs_read(
keys: KeysLike,
arena: Arena,
/,
*,
collection: CollectionLike,
field: str | None = None,
outputs_type: FieldType = FieldType.JSON,
) -> ValuesWhole 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.
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.
Inherited from _Reads
def docs_gather(
keys: KeysLike,
fields: Sequence[str],
outputs_types: FieldType | Sequence[FieldType],
arena: Arena,
/,
*,
collection: CollectionLike,
) -> ColumnsReturns: 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.
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,
) -> KeysDocuments 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.
Inherited from _Reads
def docs_sample(
wanted: int,
arena: Arena,
/,
*,
collection: CollectionLike,
) -> Keysdocs_measureBounds on what a range of document keys holds, as measure reads them for blobs.
Inherited from _Reads
def docs_measure(
start: KeyLike | None,
end: KeyLike | None,
arena: Arena,
/,
*,
collection: CollectionLike,
direction: ScanDirection = ScanDirection.ASCENDING,
) -> Measurementstrings_readthe key of every string, or None for a string the strings collection does not hold.
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.
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.
Inherited from _Reads
def strings_sample(
wanted: int,
arena: Arena,
/,
*,
collection: CollectionLike,
) -> tuple[str, ...]strings_measurebounds on what a range of strings holds.
Inherited from _Reads
def strings_measure(
start: str | bytes | None,
end: str | bytes | None,
arena: Arena,
/,
*,
collection: CollectionLike,
direction: ScanDirection = ScanDirection.ASCENDING,
) -> Measurementpages_readRenders whole pages, or the subtrees of elements, one per task, None where a page or an element is absent.
Inherited from _Reads
def pages_read(
keys: KeyLike | KeysLike,
arena: Arena,
/,
*,
collection: CollectionLike,
elements: KeyLike | KeysLike | None = None,
outputs_encoding: PageEncoding = PageEncoding.XML,
) -> Valuespages_scanUp to wanted page keys from start, keeping those holding a node of the XPath filter.
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,
) -> Keyspages_sampleUp to wanted page keys drawn at random, which a pages_read follows.
Inherited from _Reads
def pages_sample(
wanted: int,
arena: Arena,
/,
*,
collection: CollectionLike,
) -> Keyspages_measureBounds on what a range of page keys holds, as measure reads them for blobs.
Inherited from _Reads
def pages_measure(
start: KeyLike | None,
end: KeyLike | None,
arena: Arena,
/,
*,
collection: CollectionLike,
direction: ScanDirection = ScanDirection.ASCENDING,
) -> Measurementgraph_read_edgesReads every edge a batch of vertices takes part in.
Inherited from _Reads
def graph_read_edges(
vertices: KeysLike,
arena: Arena,
/,
*,
role: Role = Role.ANY,
collection: CollectionLike,
) -> NeighborhoodsThe 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.
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.
Inherited from _Reads
def graph_contains(
vertex: KeyLike,
/,
*,
collection: CollectionLike,
) -> boolgraph_scan_verticesLists up to wanted vertices from start towards end, those without edges included.
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,
) -> KeysEdges 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.
Inherited from _Reads
def graph_sample_vertices(
wanted: int,
arena: Arena,
/,
*,
collection: CollectionLike,
) -> Keysgraph_measure_verticesBounds on what a range of vertices holds, as measure reads them for blobs.
Inherited from _Reads
def graph_measure_vertices(
start: KeyLike | None,
end: KeyLike | None,
arena: Arena,
/,
*,
collection: CollectionLike,
direction: ScanDirection = ScanDirection.ASCENDING,
) -> Measurement