Events commands
10 commands. Each entry gives the invocation and an example, in the interface you pick; open the details for parameters, return shape and error codes.
append
Append one event to the branch event log.
strata event append
db.events.append(event_type: 'str', payload: 'Any') -> 'Any'
Appends one event to the selected branch and space. Strata assigns the next sequence number, stamps the event with its append timestamp, and links it into the tamper-evident hash chain. Events are immutable once appended.
To see the complete help for this command, run:
strata event append --helphelp(db.events.append)
Example
strata event append user.created {"id":1}strata event count
_ = db.events.append("user.created", {"id": 1})db.events.len()
batch_append
Append multiple events in one commit.
db.events.append_many(entries: 'Any') -> 'BatchResult'
Appends multiple events to the selected branch and space in one engine commit. Sequences are assigned in entry order. Entries that fail validation report a positional item error while valid entries still append.
To see the complete help for this command, run:
help(db.events.append_many)
Example
_ = db.events.append_many([{"event_type": "user.created", "payload": {"id": 1}}, {"event_type": "user.updated", "payload": {"id": 2}}])db.events.len()
count
Count visible events in the log.
strata event count
db.events.len(*, as_of: 'Optional[int]' = None, as_of_time: 'Optional[TimeLike]' = None) -> 'int'
Counts events visible in the selected branch and space. The optional timestamp counts the events visible at that commit time.
To see the complete help for this command, run:
strata event count --helphelp(db.events.len)
Example
strata event append user.created {"id":1}strata event append user.updated {"id":2}strata event count
_ = db.events.append("user.created", {"id": 1})_ = db.events.append("user.updated", {"id": 2})db.events.len()
exists
Check whether an event sequence exists.
strata event exists
db.events.exists(sequence: 'int') -> 'bool'
Checks whether one event sequence exists in the selected branch and space without returning the record.
To see the complete help for this command, run:
strata event exists --helphelp(db.events.exists)
Example
strata event append user.created {"id":1}strata event exists 0strata event exists 999
_ = db.events.append("user.created", {"id": 1})db.events.exists(0)db.events.exists(999)
get
Read one event by sequence number.
strata event get
db.events.get(sequence: 'int', *, as_of: 'Optional[int]' = None, as_of_time: 'Optional[TimeLike]' = None) -> 'Any'
Reads one event from the selected branch and space by sequence number. The optional timestamp reads the record visible at that commit time. The record carries its payload, append timestamp, and hash-chain facts.
To see the complete help for this command, run:
strata event get --helphelp(db.events.get)
Example
strata event append user.created {"id":1}strata event get 0strata event get 999
_ = db.events.append("user.created", {"id": 1})db.events.get(0).event.payloaddb.events.get(999) is None
list
List events with optional type filter and cursor.
strata event list
db.events.list(event_type: 'Optional[str]' = None, *, limit: 'Optional[int]' = None, after_sequence: 'Optional[int]' = None, as_of: 'Optional[int]' = None, as_of_time: 'Optional[TimeLike]' = None) -> 'Page'
Lists events from the selected branch and space in sequence order. An optional event type narrows the results, the sequence cursor continues a previous page, and the optional timestamp reads the log visible at that commit time.
To see the complete help for this command, run:
strata event list --helphelp(db.events.list)
Example
strata event append user.created {"id":1}strata event append user.updated {"id":2}strata event list
_ = db.events.append("user.created", {"id": 1})_ = db.events.append("user.updated", {"id": 2})[e.event.payload for e in db.events.list()]
range
Read a range of events by sequence number.
strata event range
db.events.range(start: 'int', *, end: 'Optional[int]' = None, limit: 'Optional[int]' = None, reverse: 'bool' = False, event_type: 'Optional[str]' = None) -> 'Page'
Reads events from the selected branch and space by sequence range. The start sequence is inclusive and the optional end sequence is exclusive; reverse direction returns the same `[start_seq, end_seq)` window in descending order (newest first). An optional event type narrows the results.
To see the complete help for this command, run:
strata event range --helphelp(db.events.range)
Example
strata event append user.created {"id":1}strata event append user.updated {"id":2}strata event range 0 --direction forward
_ = db.events.append("user.created", {"id": 1})_ = db.events.append("user.updated", {"id": 2})[e.event.payload for e in db.events.range(0)]
range_time
Read a range of events by occurrence time.
strata event range-time
db.events.range_by_time(start_ts: 'int', *, end_ts: 'Optional[int]' = None, limit: 'Optional[int]' = None, reverse: 'bool' = False, event_type: 'Optional[str]' = None) -> 'Page'
Reads events from the selected branch and space whose append timestamps fall inside a half-open `[start_ts, end_ts)` microsecond window - the start is inclusive and the end is exclusive, matching the sequence-addressed range. This queries when events occurred; historical log states are the timestamped read commands' job. An optional event type narrows the results.
To see the complete help for this command, run:
strata event range-time --helphelp(db.events.range_by_time)
Example
strata event append user.created {"id":1}strata event append user.updated {"id":2}strata event range-time 0 --direction forward
_ = db.events.append("user.created", {"id": 1})_ = db.events.append("user.updated", {"id": 2})[e.event.payload for e in db.events.range_by_time(0)]
types
List distinct event types in the log.
strata event types
db.events.types(*, as_of: 'Optional[int]' = None, as_of_time: 'Optional[TimeLike]' = None) -> 'list'
Lists the distinct event types visible in the selected branch and space in sorted order. The optional timestamp lists the types visible at that commit time.
To see the complete help for this command, run:
strata event types --helphelp(db.events.types)
Example
strata event append user.created {"id":1}strata event append user.updated {"id":2}strata event types
_ = db.events.append("user.created", {"id": 1})_ = db.events.append("user.updated", {"id": 2})db.events.types()
verify_chain
Verify event log density and hash linkage.
strata event verify-chain
db.events.verify_chain() -> 'Any'
Verifies that the visible event log in the selected branch and space is dense and hash-linked: sequences are contiguous from zero, the genesis record links to the all-zeros hash, and every record's hash matches its content and predecessor.
To see the complete help for this command, run:
strata event verify-chain --helphelp(db.events.verify_chain)
Example
strata event append user.created {"id":1}strata event verify-chain
_ = db.events.append("user.created", {"id": 1})db.events.verify_chain().valid