SortedMap
Standard library collection that may be larger than memory, and which is efficiently mapped to Reboot's underlying storage.
- Python
- TypeScript
from reboot.std.collections.sorted_map import SortedMap
import sortedMap, {
SortedMap,
} from "@reboot-dev/reboot-std/collections/sorted_map.js";
Keys are strings and values are bytes. SortedMaps are frequently used to
create indexes of other state types, but can also be used to efficiently store
large collections of primitive values.
For example:
- To index a data type in its natural state-ID order, you can create a
SortedMapwith the type's ID as keys and empty values. This is effectively a sorted set. - To index a data type by creation time, you can use time-ordered UUIDs (such as UUIDv1 or UUIDv7) as keys and the data type's state-ID as values.
- To index a large collection of Protobuf message types, you can use a key of your choice and the serialized value of each Protobuf message as a value.
To use a SortedMap in your application, you typically want to choose an ID for
the map and store it somewhere (e.g., as a field in the appropriate state data
type). To use the map, first lookup the map using its ID and then invoke the
appropriate operations. The map will be implicitly constructed when the first
writer method is invoked (e.g., Insert()).
You should also include the SortedMap servicer when starting your application,
as described in the overview.
SortedMap
A larger than memory map, sorted by its keys. Supports batch insertion, batch removal, sorted range queries, and point-lookup queries.
Insert
rpc Insert(InsertRequest) InsertResponse
Insert a batch of entries into the SortedMap.
Keys which are already in the map will be overwritten.
Remove
rpc Remove(RemoveRequest) RemoveResponse
Remove a batch of keys from the SortedMap.
Any keys in the batch that are not present in the map will be ignored.
Get
rpc Get(GetRequest) GetResponse
Fetch a single key's value.
If the key does not exist, the GetResponse leaves the value field
unset; the client can use proto's generated field-presence check to
determine whether the key existed.
Range
rpc Range(RangeRequest) RangeResponse
Read a range of data from the SortedMap.
The start_key must be less than the end_key (if both are specified),
and the results are returned in ascending key order.
The start_key is inclusive and the end_key is exclusive. If the start
or end are unset, then the range is unbounded in that direction. If both
the start and end keys are unset, the limit smallest keys in the map are
returned.
The limit argument is required, to avoid exhausting memory in the client
or server.
ReverseRange
rpc ReverseRange(ReverseRangeRequest) ReverseRangeResponse
Read a range of data in descending order from the SortedMap.
This is similar to Range but reads data in reverse order: the start_key
must be greater than the end_key (if both are specified), and the results
are returned in descending key order.
The start_key is inclusive and the end_key is exclusive. If the start
or end are unset, then the range is unbounded in that direction. If both
the start and end keys are unset, the limit largest keys in the map are
returned.
The limit argument is required, to avoid exhausting memory in the client
or server
Messages
Entry
See Range and ReverseRange.
| Field | Type | Description |
|---|---|---|
| key | string | The key of an entry. |
| value | bytes | The value of an entry. |
GetRequest
See Get.
| Field | Type | Description |
|---|---|---|
| key | string | none |
GetResponse
See Get.
| Field | Type | Description |
|---|---|---|
| oneof _value.value | optional bytes | none |
InsertRequest
See Insert.
| Field | Type | Description |
|---|---|---|
| entries | map InsertRequest.EntriesEntry | The entries to insert. |
InsertRequest.EntriesEntry
| Field | Type | Description |
|---|---|---|
| key | string | none |
| value | bytes | none |
InsertResponse
See Insert.
InvalidRangeError
See Range and ReverseRange. Raised when the requested range is not valid;
contains an error string explaining why the range is not valid.
| Field | Type | Description |
|---|---|---|
| message | string | none |
RangeRequest
See Range.
| Field | Type | Description |
|---|---|---|
| oneof _start_key.start_key | optional string | The start key to scan from (inclusive). Must be smaller than end_key. If not specified, the range is unbounded at the start. |
| oneof _end_key.end_key | optional string | The end key to scan to (exclusive). If not specified, the range is unbounded at the end. |
| limit | uint32 | The maximum number of entries to return. Must be specified and non-zero. |
RangeResponse
See Range.
| Field | Type | Description |
|---|---|---|
| entries | repeated Entry | Entries are in (ascending) key order. We cannot use protobuf's map because it does not preserve insertion order. |
RemoveRequest
See Remove.
| Field | Type | Description |
|---|---|---|
| keys | repeated string | The keys to remove. |
RemoveResponse
See Remove.
ReverseRangeRequest
See ReverseRange.
| Field | Type | Description |
|---|---|---|
| oneof _start_key.start_key | optional string | The start key to scan from (inclusive). Must be greater than end_key. If not specified, the range is unbounded at the start. |
| oneof _end_key.end_key | optional string | The end key to scan to (exclusive). If not specified, the range is unbounded at the end. |
| limit | uint32 | The maximum number of entries to return. Must be specified and non-zero. |
ReverseRangeResponse
See ReverseRange.
| Field | Type | Description |
|---|---|---|
| entries | repeated Entry | Entries are in (descending) key order. We cannot use protobuf's map because it does not preserve insertion order. |
See the protobuf documentation for more information on scalar value types.