refs.kh57

Module nustd.kv.refs.kh57.

kv sampled map: an int-keyed mapping laid out so a key range samples cheaply.

A dict slot whose keys are pinned to non-negative 57-bit ints and whose storage is kh57-encoded, so sampling or scanning a window of keys reads only that window. Everything else, descent and typing included, is a DictRef.

Name	Sort	Call	Meaning
Kh57Ref	`ref`	`Kh57Ref(address, view_type=None, parent_ref=None, owner_shape=None)`	A sparse int-keyed mapping in KV storage, laid out for range sampling.

Kh57Ref

A sparse int-keyed mapping in KV storage, laid out for range sampling.

Kh57Ref(address, view_type=None, parent_ref=None, owner_shape=None)

Path nustd.kv.Kh57Ref. Kind Ref, sort ref, cardinality scalar.

Same mapping surface as a dict slot, with the keys pinned to non-negative 57-bit ints and the physical layout encoded so that a sample or a scan over a key range reads only that range. Built for the case where the map holds billions of entries and the question is about a window of them.

Notes

Keys are ints; a key outside the non-negative 57-bit range is out of contract.
Iteration and keys come back in ascending key order, whatever order the writes happened in.
sample and range are what the layout buys; everything else behaves as it does on a plain dict slot.
Declare a Shape as the value and each entry is a row with fields of its own: series[ts].value reads one field of one row. sample and range then yield each row as a view over its stored fields, for reading a window rather than descending.

Example

class Ledger(Shape):
    entries = Kh57Ref.slot(int)
run(Ledger.entries.set_item(42, 100), ctx)
run(Ledger.entries.sample(10, begin=0, end=1000), ctx)

Methods

`.sample(n, begin=None, end=None)`

Draw a uniform sample of up to n entries from a key range.

Builds Object.

Arguments

Name	Type	Default	Meaning
`n`	`IntArg`		the ceiling on how many pairs come back. A range holding fewer than `n` entries yields all of them.
`begin`	`IntArg \| None`	`None`	inclusive lower bound on the key. None leaves the range open at the bottom.
`end`	`IntArg \| None`	`None`	exclusive upper bound on the key. None leaves the range open at the top.

Yields

A list of (int_key, value) pairs, unordered. EMPTY when the container is not reachable.

Notes

Cost tracks n, not the size of the range, so a window holding a billion entries samples as cheaply as a small one.
Each argument is a child, so any of them may be an expression or a ref read at run time.
Draws from the unseeded module random source. Build the Kh57Sample atom directly with its rng argument when a run has to be reproducible.
Stable under appends outside the queried range.

Example

run(Ledger.entries.sample(100, begin=0, end=10_000), ctx)

`.range(begin, end)`

Read a key range whole, in ascending key order.

Builds Object.

Arguments

Name	Type	Default	Meaning
`begin`	`IntArg`		inclusive lower bound on the key. Must be non-negative.
`end`	`IntArg`		exclusive upper bound on the key. Must stay inside the key space the container's layout covers.

Yields

A list of (int_key, value) pairs, ascending by key. EMPTY when the container is not reachable.

Notes

Cost tracks the size of the range, so this is the wrong call for a window that grows without bound; sample that instead.
Both bounds are required, unlike on sample, and both are children, so either may be computed at run time.
An empty or inverted range yields an empty list rather than an error; bounds outside the key space raise ValueError.

Example

run(Ledger.entries.range(0, 100), ctx)

Inherited methods

From nustd.kv.refs.containers.DictRef:

Call	Builds	Meaning
`.iter()`	`Iterator[K]`	A lazy stream over the keys, each the declared key's form.
`a[key]`	`StructuredRef`	The kv ref for the declared value at `key`.

From nu.forms.collections.abc.mapping.ReactiveMappingForm:

Call	Builds	Meaning
`.on_change()`	`object`	Subscribe to any change on this mapping slot.

From nu.forms.collections.abc.mapping.MutableMappingForm:

Call	Builds	Meaning
`.set_item(key, value)`	`Any`	Set the value at key, inserting the key if it's missing: mapping[key] = value.
`.del_item(key)`	`Any`	Delete the entry at key: del mapping[key].
`.update(other)`	`Any`	Write other's entries into self, in place: mapping.update(other).
`.pop(key, default=None)`	`ValueResultT`	Remove key and yield its value, or default if key is missing.
`.popitem()`	`ValueResultT`	Remove and yield an arbitrary (key, value) pair: mapping.popitem().
`.setdefault(key, default=None)`	`ValueResultT`	Value at key, inserting default there first if key is missing.
`.merge_update(other)`	`CollectionResultT`	Merge other into self in place, and yield self, like Python's dict `\|=`.
`.clear()`	`Any`	Remove all entries: mapping.clear().

From nu.forms.collections.abc.mapping.MappingForm:

Call	Builds	Meaning
`.keys()`	`CollectionResultT`	All keys of the mapping: mapping.keys().
`.values()`	`CollectionResultT`	All values of the mapping: mapping.values().
`.items()`	`CollectionResultT`	All (key, value) pairs of the mapping: mapping.items().
`.get_item(key, default=None)`	`ValueResultT`	Value at key, falling back to default: mapping.get_item(key, default).
`.copy()`	`CollectionResultT`	Shallow copy of self: mapping.copy().
`.reversed_keys()`	`CollectionResultT`	Keys in reverse insertion order: reversed(mapping).
`.reversed_values()`	`CollectionResultT`	Values in reverse insertion order: reversed(mapping.values()).
`.reversed_items()`	`CollectionResultT`	(key, value) pairs in reverse insertion order: reversed(mapping.items()).
`.merge(other)`	`CollectionResultT`	Self and other merged into a new mapping, like Python's dict `\|`.

From nu.forms.collections.abc.collection.CollectionForm:

Call	Builds	Meaning
`.extract()`	`object`	Materialise the full subtree rooted at self.

From nu.forms.collections.abc.sized.SizedForm:

Call	Builds	Meaning
`.len()`	`Int`	Length of self.

From nu.forms.collections.abc.container.ContainerForm:

Call	Builds	Meaning
`.contains(item)`	`Bool`	Whether item is a member of self.

From nu.domains.shape.collection.ReactiveCollectionForm:

Call	Builds	Meaning
`.on_child_change(address)`	`OnChildChange`	Observe writes at one child's own address; for its subtree use `on_descendants_change`.
`.on_children_change()`	`OnChildrenChange`	Observe writes at the direct children only; for subtrees use `on_descendants_change`.
`.on_descendants_change()`	`OnDescendantsChange`	Observe changes across descendants matching `pattern`.

From nu.domains.shape.collection.MutableCollectionForm:

Call	Builds	Meaning
`.set(value)`	`SetCmd`	Build a `SetCmd`.
`.erase()`	`Erase`	Build an `Erase`.
`.init(value)`	`IfDo`	Set `value` iff the collection is currently missing.

From nu.domains.shape.collection.CollectionForm:

Call	Builds	Meaning
`.exists()`	`Bool`	Whether this collection slot holds a value, as a `Bool`.
`.missing()`	`Bool`	Whether this slot holds no value, as a `Bool`: the negation of `exists()`.

From nu.lang.forms.Form:

Call	Builds	Meaning
`a == b`	`Bool`	Self equal to other by value: an `Eq` term, never a Python bool.
`a != b`	`Bool`	Self not equal to other by value: a `Ne` term, never a Python bool.
`.is_empty()`	`Bool`	True if this Form yields the EMPTY sentinel.
`.not_empty()`	`Bool`	True if this Form does not yield EMPTY.
`.fallback(*alternatives)`	`Self`	The first of this value and `alternatives` that is not EMPTY.

refs.kh57

Kh57Ref

.sample(n, begin=None, end=None)

.range(begin, end)

On this page

`.sample(n, begin=None, end=None)`

`.range(begin, end)`