Scans | UStore for Mojo

API

Types

KeysViewA strided run of keys, ustore_keys_view_t.

comptime KeysView[origin: ImmOrigin = ImmUntrackedOrigin]: AnyStruct[StridedView[Key, origin]] = StridedView[Key, origin]

StructBlobsCursorConfigThe bound, order and filters of a walk over one collection.1

struct BlobsCursorConfig[patterns_origin: ImmOrigin = ImmUntrackedOrigin]

Parameters

`patterns_originImmOrigin`	comptime	The borrowed patterns, compiled once when the walk opens.

Fields

`end_key`	`Optional[Key]`	Key the walk stops before, exclusive; absent bounds nothing.
`direction`	`ScanDirection`	Ascending or descending from the start key.
`patterns`	`Patterns[patterns_origin]`	Patterns every value the walk hands out matches; empty walks every key.
`predicate`	`Predicate`	The caller's verdict on the keys of every page.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable

__init__Names only the knobs that differ from the defaults.

def __init__(
    out self,
    *,
    end_key: Optional[Key] = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    patterns: Patterns[patterns_origin] = Patterns(),
    predicate: Predicate = Predicate()
)

StructBlobsCursorA walk over the keys of one collection, every pull resuming past the last key the pull before it handed out, freed when it goes out of scope. It holds its database open, and the transaction or snapshot it reads through.3

struct BlobsCursor

Fields

`library`	`Library`	The loaded engine.
`database`	`Address`	The `ustore_database_t` it walks.
`address`	`Address`	The `ustore_blobs_cursor_t`.

Conforms to

Deinitable, Movable

__init__Adopts a cursor the engine just opened.

def __init__(out self, *, library: Library, database: Int, address: Int)

__deinit__Frees the cursor and the holds it kept. Calls ustore_blobs_cursor_free.

def __deinit__(deinit self)

nextPulls the next page of up to wanted keys, with their values when asked. Calls ustore_blobs_cursor_next.

def next(
    self,
    executor: Executor,
    mut arena: Arena,
    wanted: Int,
    values: Bool = True,
    progress: Progress = Progress()
) -> Pulled[origin_of(arena)]

Parameters

`executorExecutor`		The executor the pull runs on, of the kind the walk was opened for.
`arenaArena`	mut	The arena to rewind and refill, which the result borrows.
`wantedInt`		Most keys the page holds; a page of fewer exhausts the walk.
`valuesBool`		Whether the values of the page's keys come too.
`progressProgress`		Reports the pull, and may cancel it before the cursor advances.

Raises

Error with CANCELLED when progress stops the pull, which leaves the cursor where it was.

StructScanModeIn what order a scan hands its keys over, ustore_scan_mode_t.

struct ScanMode

Fields

`code`	`c_int`	The raw `ustore_scan_mode_t` value the ABI exchanges.

Values

`ORDERED`	`ScanMode(Int32(0))`	In order, each once, and only while present.
`UNORDERED`	`ScanMode(Int32(1))`	Possibly out of order, deleted or repeated, with no merge across partitions.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructScanDirectionWhich way a scan, a cursor or a measure walks from its start key, ustore_scan_direction_t.

struct ScanDirection

Fields

`code`	`c_int`	The raw `ustore_scan_direction_t` value the ABI exchanges.

Values

`ASCENDING`	`ScanDirection(Int32(0))`	Up from the start, smallest key first.
`DESCENDING`	`ScanDirection(Int32(1))`	Down from the start, largest key first.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructChangeKindWhat one committed change did to its key, ustore_change_kind_t.

struct ChangeKind

Fields

`code`	`c_int`	The raw `ustore_change_kind_t` value the ABI exchanges.

Values

`WRITE`	`ChangeKind(Int32(0))`	Wrote the whole value.
`REMOVAL`	`ChangeKind(Int32(1))`	Removed the key.
`CHANGE`	`ChangeKind(Int32(2))`	Changed part of the value.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructAdmissionWhether a predicate keeps a listed key or passes over it, ustore_admission_t.

struct Admission

Fields

`code`	`c_int`	The raw `ustore_admission_t` value the ABI exchanges.

Values

`REJECT`	`Admission(Int32(0))`	Pass over the key.
`ADMIT`	`Admission(Int32(1))`	Keep the key.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructPredicateCostHow costly one predicate call is, which decides where in a scan it is asked, ustore_predicate_cost_t.

struct PredicateCost

Fields

`code`	`c_int`	The raw `ustore_predicate_cost_t` value the ABI exchanges.

Values

`CHEAP`	`PredicateCost(Int32(0))`	Asked once per page of listed keys, before patterns or filters read any value.
`EXPENSIVE`	`PredicateCost(Int32(1))`	Asked once per page about the keys patterns and filters kept.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructPredicateThe caller's verdict on the keys a scan lists, ustore_predicate_t, asked on the calling side in pages of keys, never concurrently with itself within one call.2

struct Predicate

Fields

`callback`	`Address`	The handler's C entry point; `NULL_ADDRESS` admits every key.
`state`	`Address`	Forwarded into every call; it must outlive the scan.
`cost`	`PredicateCost`	Where in a scan the handler is asked.

Conforms to

Copyable, Defaultable, Deinitable, ImplicitlyCopyable, Movable

__init__No handler: every key is admitted.

def __init__(out self)

ofAsks handler about every page of listed keys, which writes one admission per key.

def of[T: AnyType, origin: MutOrigin, //, handler: def(Span[Key, MutAnyOrigin], Span[Admission, MutAnyOrigin], Pointer[T, MutAnyOrigin]) thin -> None](
    state: Pointer[T, origin],
    cost: PredicateCost = PredicateCost.CHEAP
) -> Self

Parameters

`TAnyType`	comptime	What `state` points at, inferred from it.
`originMutOrigin`	comptime	The state's origin, inferred with it.
`handlerdef(Span[Key, MutAnyOrigin], Span[Admission, MutAnyOrigin], Pointer[T, MutAnyOrigin]) thin -> None`	comptime	Called with the page's keys, their admissions to write, and `state`.
`statePointer[T, origin]`		Forwarded into every call; it must outlive the scan.
`costPredicateCost`		Where in a scan the handler is asked.

StructChangesThe changes one pull of a feed yielded, oldest first, read in place from the arena it borrows.6

struct Changes[origin: MutOrigin]

Parameters

`originMutOrigin`	comptime	The arena the changes live in, which this result borrows.

Fields

`arena`	`Pointer[Arena, origin]`	The arena holding the changes.
`generation`	`Int`	The arena's call the changes came from.
`written`	`ChangesWritten`	The views the engine wrote.

Values

`Written`	`ChangesWritten`

Conforms to

Answer, Deinitable, Movable, Sized

__init__

def __init__(out self, arena: Int, generation: Int, written: ChangesWritten, count: Int)

__len__The changes yielded, zero at the newest commit.

def __len__(self) -> Int

keysThe key of every change.

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

stampsThe stamp every change was committed at.

def stamps(ref self) -> Span[Stamp, origin_of(self)]

kindsWhat every change did.

def kinds(ref self) -> Span[ChangeKind, origin_of(self)]

valuesThe bytes every change carries, empty for a removal or when the pull skipped them.

def values(self) -> Tape[origin]

StructChangesCursorA feed of the changes committed to one collection after a stamp, oldest first, freed when it goes out of scope. It pins its stamp and holds its database open until then.3

struct ChangesCursor

Fields

`library`	`Library`	The loaded engine.
`address`	`Address`	The `ustore_changes_cursor_t`.

Conforms to

Deinitable, Movable

__init__Adopts a feed the engine just opened.

def __init__(out self, *, library: Library, address: Int)

__deinit__Frees the feed, releasing its stamp. Calls ustore_changes_cursor_free.

def __deinit__(deinit self)

nextPulls up to wanted next changes, with their values when asked. Calls ustore_changes_cursor_next.

def next(
    self,
    executor: Executor,
    mut arena: Arena,
    wanted: Int,
    values: Bool = True
) -> Changes[origin_of(arena)]

Parameters

`executorExecutor`		The executor the pull runs on.
`arenaArena`	mut	The arena to rewind and refill, which the result borrows.
`wantedInt`		Most changes the pull yields.
`valuesBool`		Whether the bytes every change carries come too.

Raises

Error if the collection was dropped meanwhile.

StructDocsScanConfigThe bounds, order and filter of a scan over document keys.1

struct DocsScanConfig[end_origin: ImmOrigin = ImmUntrackedOrigin, filter_origin: ImmOrigin = ImmUntrackedOrigin]

Parameters

`end_originImmOrigin`	comptime	The borrowed end keys.
`filter_originImmOrigin`	comptime	The borrowed filter.

Fields

`end_keys`	`StridedView[Key, end_origin]`	Key every scan stops before, exclusive; zeroed bounds nothing.
`direction`	`ScanDirection`	Ascending or descending from the start keys.
`mode`	`ScanMode`	In what order the keys come.
`filter`	`BytesView[filter_origin]`	A JSONPath, or a bare root filter such as "?@.age>30", every listed document matches; zeroed lists every key.
`predicate`	`Predicate`	The caller's verdict on the listed keys.
`progress`	`Progress`	Reports the scans finished, and stops the call where it says to.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable

__init__Names only the knobs that differ from the defaults.

def __init__(
    out self,
    *,
    end_keys: StridedView[Key, end_origin] = StridedView(),
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    filter: BytesView[filter_origin] = BytesView(),
    predicate: Predicate = Predicate(),
    progress: Progress = Progress()
)

StructDocsCursorConfigThe bound, order and filter of a walk over one collection, the filter copied when the walk opens.1

struct DocsCursorConfig[filter_origin: ImmOrigin = ImmUntrackedOrigin]

Parameters

`filter_originImmOrigin`	comptime	The borrowed filter.

Fields

`end_key`	`Optional[Key]`	Key the walk stops before, exclusive; absent bounds nothing.
`direction`	`ScanDirection`	Ascending or descending from the start key.
`filter`	`BytesView[filter_origin]`	A JSONPath or bare root filter every document the walk hands out matches; zeroed walks every key.
`predicate`	`Predicate`	The caller's verdict on the keys of every page.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable

__init__Names only the knobs that differ from the defaults.

def __init__(
    out self,
    *,
    end_key: Optional[Key] = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    filter: BytesView[filter_origin] = BytesView(),
    predicate: Predicate = Predicate()
)

StructDocsCursorA walk over the document keys of one collection, every pull resuming past the last key the pull before it handed out, freed when it goes out of scope. It holds its database open, and the transaction or snapshot it reads through.3

struct DocsCursor

Fields

`library`	`Library`	The loaded engine.
`database`	`Address`	The `ustore_database_t` it walks.
`address`	`Address`	The `ustore_docs_cursor_t`.

Conforms to

Deinitable, Movable

__init__Adopts a cursor the engine just opened.

def __init__(out self, *, library: Library, database: Int, address: Int)

__deinit__Frees the cursor and the holds it kept. Calls ustore_docs_cursor_free.

def __deinit__(deinit self)

nextPulls the next page of up to wanted keys, with the whole documents when asked. Calls ustore_docs_cursor_next.

def next(
    self,
    executor: Executor,
    mut arena: Arena,
    wanted: Int,
    values: Bool = True,
    progress: Progress = Progress()
) -> Pulled[origin_of(arena)]

Raises

Error with CANCELLED when progress stops the pull, which leaves the cursor where it was.

StructGraphCursorConfigThe bound, order and verdict of a walk over the vertices of one collection.1

struct GraphCursorConfig

Fields

`end_key`	`Optional[Key]`	Vertex the walk stops before, exclusive; absent bounds nothing.
`direction`	`ScanDirection`	Ascending or descending from the start key.
`predicate`	`Predicate`	The caller's verdict on the keys of every page.

Conforms to

Copyable, Defaultable, Deinitable, ImplicitlyCopyable, Movable

__init__Unbounded, ascending, admitting every vertex.

def __init__(out self)

StructEffectiveKeysThe key every inserted element ended up with, minted or given, read in place from the arena an insert borrows.3

struct EffectiveKeys[origin: MutOrigin]

Parameters

`originMutOrigin`	comptime	The arena the keys live in, which this result borrows.

Fields

`arena`	`Pointer[Arena, origin]`	The arena holding the keys.
`generation`	`Int`	The arena's call the keys came from.
`written`	`EffectiveKeysWritten`	The views the engine wrote.
`count`	`Int`	Insertions the call carried.

Values

`Written`	`EffectiveKeysWritten`

Conforms to

Answer, Deinitable, Movable, Sized

__init__

def __init__(out self, arena: Int, generation: Int, written: EffectiveKeysWritten, count: Int)

__len__The insertions the call carried.

def __len__(self) -> Int

keysThe key of every inserted element.

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

StructPagesCursorConfigThe bound, order and filter of a walk over one collection's pages, the filter copied when it opens.1

struct PagesCursorConfig[filter_origin: ImmOrigin = ImmUntrackedOrigin]

Parameters

`filter_originImmOrigin`	comptime	The borrowed filter.

Fields

`end_key`	`Optional[Key]`	Key the walk stops before, exclusive; absent bounds nothing.
`direction`	`ScanDirection`	Ascending or descending from the start key.
`filter`	`BytesView[filter_origin]`	A path in StringZilla's XPath subset every page the walk hands out holds a node of; zeroed walks every page.
`predicate`	`Predicate`	The caller's verdict on the keys of every page.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable

__init__Names only the knobs that differ from the defaults.

def __init__(
    out self,
    *,
    end_key: Optional[Key] = None,
    direction: ScanDirection = ScanDirection.ASCENDING,
    filter: BytesView[filter_origin] = BytesView(),
    predicate: Predicate = Predicate()
)

StructPagesCursorA walk over the page keys of one collection, every pull resuming past the last key the pull before it handed out, freed when it goes out of scope. It holds its database open, and the transaction or snapshot it reads through.3

struct PagesCursor

Fields

`library`	`Library`	The loaded engine.
`database`	`Address`	The `ustore_database_t` it walks.
`address`	`Address`	The `ustore_pages_cursor_t`.

Conforms to

Deinitable, Movable

__init__Adopts a cursor the engine just opened.

def __init__(out self, *, library: Library, database: Int, address: Int)

__deinit__Frees the cursor and the holds it kept. Calls ustore_pages_cursor_free.

def __deinit__(deinit self)

nextPulls the next page of up to wanted keys, with the whole pages rendered when asked. Calls ustore_pages_cursor_next.

def next(
    self,
    executor: Executor,
    mut arena: Arena,
    wanted: Int,
    values: Bool = True,
    outputs_encoding: PageEncoding = PageEncoding.XML,
    progress: Progress = Progress()
) -> Pulled[origin_of(arena)]

Raises

Error with CANCELLED when progress stops the pull, which leaves the cursor where it was.

StructStringKeysThe keys a batch of strings map onto, read in place from the arena a strings read borrows.4

struct StringKeys[origin: MutOrigin]

Parameters

`originMutOrigin`	comptime	The arena the keys live in, which this result borrows.

Fields

`arena`	`Pointer[Arena, origin]`	The arena holding the keys.
`generation`	`Int`	The arena's call the keys came from.
`written`	`StringKeysWritten`	The views the engine wrote.
`count`	`Int`	Strings the read carried.

Values

`Written`	`StringKeysWritten`

Conforms to

Answer, Deinitable, Movable, Sized

__init__

def __init__(out self, arena: Int, generation: Int, written: StringKeysWritten, count: Int)

__len__The strings the read carried.

def __len__(self) -> Int

presentWhether string index is present.

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

keysThe key every string maps onto, nil for a missing one.

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

StructPatternKindWhat the strings of Patterns are matched as, ustore_pattern_kind_t.

struct PatternKind

Fields

`code`	`c_int`	The raw `ustore_pattern_kind_t` value the ABI exchanges.

Values

`REGEX`	`PatternKind(Int32(0))`	Regular expressions, of which a listed value matches at least one somewhere.
`SUBSTRINGS`	`PatternKind(Int32(1))`	Literal substrings, of which a listed value holds at least one.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructCaseSensitivityWhether patterns compare bytes as they are or after Unicode case folding, ustore_case_sensitivity_t.

struct CaseSensitivity

Fields

`code`	`c_int`	The raw `ustore_case_sensitivity_t` value the ABI exchanges.

Values

`CASED`	`CaseSensitivity(Int32(0))`	Bytes as they are.
`UNCASED`	`CaseSensitivity(Int32(1))`	Full Unicode case folding of both the patterns and the values.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructPatternsPatterns a scan keeps the values or strings matching, compiled once per call or per cursor.2

struct Patterns[origin: ImmOrigin = ImmUntrackedOrigin]

Parameters

`originImmOrigin`	comptime	The borrowed patterns and weights, kept alive for as long as these are used.

Fields

`patterns`	`StringsView[origin]`	The patterns; an empty batch matches everything.
`kind`	`PatternKind`	What the patterns are matched as.
`sensitivity`	`CaseSensitivity`	Whether matching folds case.
`weights`	`Optional[Pointer[Float32, origin]]`	One weight per substring pattern, which turns on scores; absent scores nothing.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable

__init__Matches everything.

def __init__(out self)

def __init__(
    out self,
    patterns: StringsView[origin],
    kind: PatternKind = PatternKind.REGEX,
    sensitivity: CaseSensitivity = CaseSensitivity.CASED
)

Matches patterns as kind, scoring nothing.

argumentsThe C layout, erased only inside a verb so the borrow lives through the call.

def arguments(self) -> PatternsArguments